> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-MegaField SDK for Game Engine API Reference

Specifications of models and API references for GS2-MegaField SDK for Game Engine



## Models

### EzSpatial

Spatial

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string |  | ✓ |  |  ~ 128 chars | User ID |
| areaModelName | string |  | ✓ |  |  ~ 128 chars | Area name |
| layerModelName | string |  | ✓ |  |  ~ 128 chars | Layer name |
| position | [EzPosition](#ezposition) |  | ✓ |  |  | Position |
| vector | [EzVector](#ezvector) |  | ✓ |  |  | Vector |

**Related methods:**
update - Send position


---

### EzAreaModel

Area divides space, and different areas can be treated as different spaces even if they have the same coordinates.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128 chars | Area Model name |
| metadata | string |  |  |  |  ~ 2048 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| layerModels | [List&lt;EzLayerModel&gt;](#ezlayermodel) |  |  | [] | 0 ~ 1000 items | List of layer models |

**Related methods:**
describeAreaModels - List Area Models
getAreaModel - Get Area Model


---

### EzLayerModel

Layers allow for multiple logical hierarchies within a single space.
For example, it solves the problem of an Enemy being invisible in a space with a large number of characters.
Characters are placed on Layer 1. If Enemies are placed on Layer 2, there is no need to worry about them becoming invisible, since each layer can specify the quantity to be acquired within a specified distance.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128 chars | Layer Model name |
| metadata | string |  |  |  |  ~ 2048 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |

**Related methods:**
describeLayerModels - List Layer Models
getLayerModel - Get Layer Model


**Related models:**
EzAreaModel - Area divides space, and different areas can be treated as different spaces even if they have the same coordinates.



---

### EzMyPosition

My Location

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| position | [EzPosition](#ezposition) |  | ✓ |  |  | Position |
| vector | [EzVector](#ezvector) |  | ✓ |  |  | Vector |
| r | float |  |  | 1 | 0 ~ 10000 | Radius |

**Related methods:**
update - Send position


---

### EzPosition

Position

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| x | float |  | ✓ |  | -1048574 ~ 1048574 | X position |
| y | float |  | ✓ |  | -1048574 ~ 1048574 | Y position |
| z | float |  | ✓ |  | -1048574 ~ 1048574 | Z position |


**Related models:**
EzSpatial - Spatial
EzMyPosition - My Location



---

### EzScope

Surroundings to be acquired

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| r | float |  | ✓ |  | 1 ~ 16777214 | Radius |
| limit | int |  | ✓ |  | 1 ~ 100 | Maximum number of result |

**Related methods:**
update - Send position


---

### EzVector

Position

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| x | float |  | ✓ |  | -1048574 ~ 1048574 | X position |
| y | float |  | ✓ |  | -1048574 ~ 1048574 | Y position |
| z | float |  | ✓ |  | -1048574 ~ 1048574 | Z position |


**Related models:**
EzSpatial - Spatial
EzMyPosition - My Location



---

## Methods

### describeAreaModels

List Area Models

#### Request

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |

#### Result

|  | Type | Description |
| --- | --- | --- |
| items | [List&lt;EzAreaModel&gt;](#ezareamodel) | List of Area Models|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.AreaModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.AreaModels(
    );
    List<EzAreaModel> items = new List<EzAreaModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->AreaModels(
    );
    TArray<Gs2::UE5::MegaField::Model::FEzAreaModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### Value change event handling




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeAreaModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeAreaModels(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeAreaModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeAreaModels(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeAreaModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeAreaModels(CallbackId);

```


{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.

The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### getAreaModel

Get Area Model

#### Request

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| areaModelName | string |  | ✓|  |  ~ 128 chars | Area Model name |

#### Result

|  | Type | Description |
| --- | --- | --- |
| item | [EzAreaModel](#ezareamodel) | Area Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


##### Value change event handling




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::MegaField::Model::FAreaModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

```


{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.

The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### describeLayerModels

List Layer Models

#### Request

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| areaModelName | string |  | ✓|  |  ~ 128 chars | Area Model name |

#### Result

|  | Type | Description |
| --- | --- | --- |
| items | [List&lt;EzLayerModel&gt;](#ezlayermodel) | List of Layer Models|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    );
    var items = await domain.LayerModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    );
    var it = domain.LayerModels(
    );
    List<EzLayerModel> items = new List<EzLayerModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    );
    const auto It = Domain->LayerModels(
    );
    TArray<Gs2::UE5::MegaField::Model::FEzLayerModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### Value change event handling




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeLayerModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeLayerModels(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeLayerModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeLayerModels(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeLayerModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeLayerModels(CallbackId);

```


{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.

The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### getLayerModel

Get Layer Model

#### Request

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| areaModelName | string |  | ✓|  |  ~ 128 chars | Area Model name |
| layerModelName | string |  | ✓|  |  ~ 128 chars | Layer Model name |

#### Result

|  | Type | Description |
| --- | --- | --- |
| item | [EzLayerModel](#ezlayermodel) | Layer Model|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    ).LayerModel(
        layerModelName: "layer-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    ).LayerModel(
        layerModelName: "layer-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    )->LayerModel(
        "layer-0001" // layerModelName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


##### Value change event handling




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    ).LayerModel(
        layerModelName: "layer-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).AreaModel(
        areaModelName: "area-0001"
    ).LayerModel(
        layerModelName: "layer-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    )->LayerModel(
        "layer-0001" // layerModelName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::MegaField::Model::FLayerModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

```


{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.

The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}

---

### update

Send position

#### Request

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| areaModelName | string |  | ✓|  |  ~ 128 chars | Area name |
| layerModelName | string |  | ✓|  |  ~ 128 chars | Layer name |
| position | [EzMyPosition](#ezmyposition) |  | ✓|  |  | My Location |
| scopes | [List&lt;EzScope&gt;](#ezscope) |  | |  | 0 ~ 10 items | List of Scope of acquisition by other players |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | Type | Description |
| --- | --- | --- |
| items | [List&lt;EzSpatial&gt;](#ezspatial) | List of Spatial|

#### Implementation Example




**Unity (UniTask)**
```csharp
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Spatial(
        areaModelName: "area-0001",
        layerModelName: "layer-0001"
    );
    var result = await domain.UpdateAsync(
        position: null,
        scopes: null
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Spatial(
        areaModelName: "area-0001",
        layerModelName: "layer-0001"
    );
    var future = domain.UpdateFuture(
        position: null,
        scopes: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Spatial(
        "area-0001", // areaModelName
        "layer-0001" // layerModelName
    );
    const auto Future = Domain->Update(
        nullptr // position
        // scopes
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

```


---