API Reference of GS2-MegaField SDK for Game Engine

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

Model

EzAreaModel

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

	Type	Require	Default	Limitation	Description
name	string	✓		~ 128 chars	Area Model Name
metadata	string			~ 2048 chars	metadata
layerModels	List<EzLayerModel>		[]	~ 1000 items	List of layer models

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	Require	Default	Limitation	Description
name	string		✓		~ 128 chars	Layer Model Name
metadata	string				~ 2048 chars	metadata

EzMyPosition

My Location

	Type	Require	Default	Limitation	Description
position	EzPosition	✓			Position
vector	EzVector	✓			Vector
r	float	✓	1	~ 10000	Radius

EzPosition

Position

	Type	Require	Limitation	Description
x	float	✓	~ 1048574	X position
y	float	✓	~ 1048574	Y position
z	float	✓	~ 1048574	Z position

EzScope

Surroundings to be acquired

	Type	Condition	Require	Default	Limitation	Description
r	float		✓		1 ~ 16777214	Radius
limit	int		✓		1 ~ 100	Maximum number of result

EzSpatial

Spatial

	Type	Require	Limitation	Description
userId	string	✓	~ 128 chars	User Id
areaModelName	string	✓	~ 128 chars	Area name
layerModelName	string	✓	~ 128 chars	Layer name
position	EzPosition	✓		Position
vector	EzVector	✓		Vector

EzVector

Position

	Type	Require	Limitation	Description
x	float	✓	~ 1048574	X position
y	float	✓	~ 1048574	Y position
z	float	✓	~ 1048574	Z position

Methods

describeAreaModels

Get list of Area Model

Request

	Type	Condition	Require	Default	Limitation	Description
namespaceName	string		✓		~ 128 chars	Namespace name

Result

	Type	Description
items	List<EzAreaModel>	List of Area Models

Implementation Example

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

    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;
        }
    }

    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

    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);

    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;
        }
    }

    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);

Warning

This event is called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

getAreaModel

Get Area Model

Request

	Type	Condition	Require	Default	Limitation	Description
namespaceName	string		✓		~ 128 chars	Namespace name
areaModelName	string		✓		~ 128 chars	Area Model Name

Result

	Type	Description
item	EzAreaModel	Area Model

Implementation Example

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

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

    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

    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);

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

    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);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

describeLayerModels

Get list of Layer Model

Request

	Type	Condition	Require	Default	Limitation	Description
namespaceName	string		✓		~ 128 chars	Namespace name
areaModelName	string		✓		~ 128 chars	Area Model Name

Result

	Type	Description
items	List<EzLayerModel>	List of Layer Model

Implementation Example

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

    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;
        }
    }

    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

    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);

    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;
        }
    }

    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);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

getLayerModel

Get Layer Model

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
areaModelName	string	✓	~ 128 chars	Area Model Name
layerModelName	string	✓	~ 128 chars	Layer Model Name

Result

	Type	Description
item	EzLayerModel

Implementation Example

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

    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;

    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

    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);

    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;

    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);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

update

Send position

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 128 chars	Namespace name
areaModelName	string	✓	~ 128 chars	Area name
layerModelName	string	✓	~ 128 chars	Layer name
position	EzMyPosition	✓		My Location
scopes	List<EzScope>		~ 10 items	List of Scope of acquisition by other players
accessToken	string	✓	~ 128 chars	Access token

Result

	Type	Description
items	List<EzSpatial>	List of Spatial

Implementation Example

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

    var domain = gs2.MegaField.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Spatial(
        areaModelName: "area-0001",
        layerModelName: "layer-0001"
    );
    var future = domain.UpdateFuture(
        position: ,
        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;

    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Spatial(
        "area-0001", // areaModelName
        "layer-0001" // layerModelName
    );
    const auto Future = Domain->Update(
         // 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();