GS2-MegaField SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-MegaField SDK의 모델 사양과 API 레퍼런스

모델

EzSpatial

공간 정보

	타입	필수	값 제한	설명
userId	string	✓	~ 128자	사용자ID
areaModelName	string	✓	~ 128자	에어리어 이름
layerModelName	string	✓	~ 128자	레이어 이름
position	EzPosition	✓		좌표
vector	EzVector	✓		방향

EzAreaModel

에어리어는 공간을 분할하는 것으로, 같은 좌표라도 에어리어가 다르면 별도의 공간으로 취급할 수 있습니다.

	타입	필수	기본값	값 제한	설명
name	string	✓		~ 128자	에어리어 모델 이름
metadata	string			~ 2048자	메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
layerModels	List<EzLayerModel>		[]	0 ~ 1000 items	레이어 모델 목록

EzLayerModel

레이어는 하나의 공간 내에서 여러 개의 논리적 계층을 구현합니다.
예를 들어, 캐릭터가 대량으로 존재하는 공간에서 에너미가 보이지 않게 되는 문제를 해결합니다.
레이어 1에는 캐릭터를 배치합니다. 레이어 2에 에너미를 배치한 경우, 레이어마다 지정한 거리 내에서의 취득 수량을 지정할 수 있으므로 보이지 않게 될 걱정이 없습니다.

	타입	활성화 조건	필수	기본값	값 제한	설명
name	string		✓		~ 128자	레이어 모델 이름
metadata	string				~ 2048자	메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.

EzMyPosition

내 위치 정보

	타입	필수	기본값	값 제한	설명
position	EzPosition	✓			좌표
vector	EzVector	✓			방향
r	float		1	0 ~ 10000	반경

EzPosition

좌표

	타입	필수	값 제한	설명
x	float	✓	-1048574 ~ 1048574	X 좌표
y	float	✓	-1048574 ~ 1048574	Y 좌표
z	float	✓	-1048574 ~ 1048574	Z 좌표

EzScope

취득할 주변 상황

	타입	활성화 조건	필수	기본값	값 제한	설명
r	float		✓		1 ~ 16777214	반경
limit	int		✓		1 ~ 100	최대 개수

EzVector

좌표

	타입	필수	값 제한	설명
x	float	✓	-1048574 ~ 1048574	X 좌표
y	float	✓	-1048574 ~ 1048574	Y 좌표
z	float	✓	-1048574 ~ 1048574	Z 좌표

메서드

describeAreaModels

에어리어 모델 목록 조회

Request

	타입	활성화 조건	필수	기본값	값 제한	설명
namespaceName	string		✓		~ 128자	네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.

Result

	타입	설명
items	List<EzAreaModel>	에어리어 모델 리스트

구현 예제

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

값 변경 이벤트 핸들링

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

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeAreaModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeAreaModels(callbackId);

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

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeAreaModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeAreaModels(callbackId);

    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeAreaModels(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeAreaModels(CallbackId);

Warning

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

getAreaModel

에어리어 모델 조회

Request

	타입	활성화 조건	필수	기본값	값 제한	설명
namespaceName	string		✓		~ 128자	네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
areaModelName	string		✓		~ 128자	에어리어 모델 이름

Result

	타입	설명
item	EzAreaModel	에어리어 모델

구현 예제

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

var domain = ez.mega_field.namespace_(
        "namespace-0001"
    ).area_model(
        "area-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

값 변경 이벤트 핸들링

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

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

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

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::MegaField::Model::FAreaModel> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);

var domain = ez.mega_field.namespace_(
        "namespace-0001"
    ).area_model(
        "area-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

Warning

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

describeLayerModels

레이어 모델 목록 조회

Request

	타입	활성화 조건	필수	기본값	값 제한	설명
namespaceName	string		✓		~ 128자	네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
areaModelName	string		✓		~ 128자	에어리어 모델 이름

Result

	타입	설명
items	List<EzLayerModel>	레이어 모델 리스트

구현 예제

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

값 변경 이벤트 핸들링

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

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeLayerModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeLayerModels(callbackId);

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

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeLayerModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeLayerModels(callbackId);

    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeLayerModels(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeLayerModels(CallbackId);

Warning

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

getLayerModel

레이어 모델 조회

Request

	타입	필수	값 제한	설명
namespaceName	string	✓	~ 128자	네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
areaModelName	string	✓	~ 128자	에어리어 모델 이름
layerModelName	string	✓	~ 128자	레이어 모델 이름

Result

	타입	설명
item	EzLayerModel	레이어 모델

구현 예제

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

var domain = ez.mega_field.namespace_(
        "namespace-0001"
    ).area_model(
        "area-0001"
    ).layer_model(
        "layer-0001"
    )

var async_result = await domain.model()
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

값 변경 이벤트 핸들링

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

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

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

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);

    const auto Domain = Gs2->MegaField->Namespace(
        "namespace-0001" // namespaceName
    )->AreaModel(
        "area-0001" // areaModelName
    )->LayerModel(
        "layer-0001" // layerModelName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::MegaField::Model::FLayerModel> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);

var domain = ez.mega_field.namespace_(
        "namespace-0001"
    ).area_model(
        "area-0001"
    ).layer_model(
        "layer-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

Warning

이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.

따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.

update

좌표 전송

Request

	타입	필수	값 제한	설명
namespaceName	string	✓	~ 128자	네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
areaModelName	string	✓	~ 128자	에어리어 이름
layerModelName	string	✓	~ 128자	레이어 이름
position	EzMyPosition	✓		내 위치 정보
scopes	List<EzScope>		0 ~ 10 items	다른 플레이어의 취득 범위 리스트
gameSession	GameSession	✓		GameSession

Result

	타입	설명
items	List<EzSpatial>	물체 리스트

구현 예제

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

    // 변경된 값 / 결과 값을 취득
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

var domain = ez.mega_field.namespace_(
        "namespace-0001"
    ).me(game_session).spatial(
        "area-0001",
        "layer-0001"
    )

var async_result = await domain.update(
    null, # position
    null # scopes
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result