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	Required	Value Limits	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

EzAreaModel

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

	Type	Required	Default	Value Limits	Description
name	string	✓		~ 128 chars	Area Model name
metadata	string			~ 2048 chars	Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game.
layerModels	List<EzLayerModel>		[]	0 ~ 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	Required	Default	Value Limits	Description
name	string		✓		~ 128 chars	Layer Model name
metadata	string				~ 2048 chars	Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game.

EzMyPosition

My Location

	Type	Required	Default	Value Limits	Description
position	EzPosition	✓			Position
vector	EzVector	✓			Vector
r	float		1	0 ~ 10000	Radius

EzPosition

Position

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

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

EzVector

Position

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

Methods

describeAreaModels

Get a list of Area Model

Request

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

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"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeAreaModels(
        () => {
            // Called when an element of the list changes.
        }
    );

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

    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 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 a GS2-JobQueue with 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	Required	Default	Value Limits	Description
namespaceName	string		✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
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"
    );
    
    // 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);

    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 triggered when the value stored in the SDK’s local cache changes.

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

describeLayerModels

Get a list of Layer Model

Request

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

Result

	Type	Description
items	List<EzLayerModel>	List of Layer Models

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"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeLayerModels(
        () => {
            // Called when an element of the list changes.
        }
    );

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

    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 triggered when the value stored in the SDK’s local cache changes.

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

getLayerModel

Get Layer Model

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific 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

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

    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 triggered when the value stored in the SDK’s local cache changes.

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

update

Send position

Request

	Type	Required	Value Limits	Description
namespaceName	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
areaModelName	string	✓	~ 128 chars	Area name
layerModelName	string	✓	~ 128 chars	Layer name
position	EzMyPosition	✓		My Location
scopes	List<EzScope>		0 ~ 10 items	List of Scope of acquisition by other players
gameSession	GameSession	✓		GameSession

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: null,
        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: 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;

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