Documentation index for AI agents

GS2 States Language 포맷

소개

GS2 States Language(GSL)는 고유한 구조를 가진 스테이트 머신 정의 언어입니다. 스테이트 머신은 일반적으로 여러 상태를 나타내는 Task와 태스크 간의 전환을 나타내는 Transition으로 구성됩니다. 외부에서 메시지를 전송하면 Transition에 의해 정해진 규칙에 따라 「실행 중인 Task」가 전환되어 상태를 관리합니다.

스테이트 머신은 「실행 중인 Task」 외에 「상태 변수」를 가지고 있습니다. Task에는 몇 가지 종류가 있으며, 일반적으로 GS2-Script를 실행하여 처리를 기술할 수 있습니다. GS2-Script는 「상태 변수」를 참조할 수 있으며, 스크립트 실행 결과로 「상태 변수」를 다시 쓸 수 있습니다.

(C) Game Server Services Inc. and affiliates.

GSL 사양의 구현 및 파생 사양은 무상으로 허용합니다. 단, 위 저작권 표시를 파생물에 포함해야 합니다. 본 사양의 파생물을 서브라이선스하거나 판매할 수 없습니다.

본 사양은 「있는 그대로」 제공되며, 본 사양이 타사의 저작권 등을 침해하지 않는다는 것을 보증하지 않습니다. 본 사용으로 인해 발생하는 모든 청구, 손해, 기타 책임에 대해서도 Game Server Services, Inc.는 책임을 지지 않습니다.

본 사양서에 포함된 샘플 코드는 별도로 명시되지 않는 한 Apache License, Version 2.0 하에 라이선스됩니다.

GSL 예제

StateMachine MainStateMachine {
  Variables {
    int counter;
  }

  EntryPoint Task1;

  Task Task1(int initCounter) {
    Event StartLoop();
    Event Error(string Reason);

    Payload {
      args.variables.counter = args.params.initCounter
      result = {
          event="StartLoop",
          params={},
          updatedVariables=args.variables
      }
    }
  }

  SubStateMachineTask Task2 {
    using SubStateMachine;
    in (initCounter <- counter);
    out (loopCounter -> counter);
  }

  WaitTask WaitForExternalEvent {
    Event ExternalEvent(int newCounter);
  }

  Task Task3(int newCounter) {
    Event Pass();

    Payload {
      print(args.variables.counter)
      print(args.params.newCounter)
      result = {
          event="Pass",
          params={},
          updatedVariables=args.variables
      }
    }
  }

  PassTask Pass;

  ErrorTask Error(string reason);

  Transition Task1 handling StartLoop -> Task2;
  Transition Task2 handling Pass -> WaitForExternalEvent;
  Transition Task2 handling Error -> Error;
  Transition WaitForExternalEvent handling ExternalEvent -> Task3;
  Transition Task3 handling Pass -> Pass;
}

StateMachine SubStateMachine {
  Variables {
    int currentCounter;
    int loopCounter;
  }

  EntryPoint SubTask1;

  Task SubTask1(int initCounter) {
    Event Pass();
    Event Error(string reason);

    Script grn:gs2:{region}:{ownerId}:script:state-machine-0001:script:SubTask1
  }

  Task SubTask2(int currentCounter) {
    Event IncrementCounter();
    Event Pass();
    Event Error(string reason);

    Script grn:gs2:{region}:{ownerId}:script:state-machine-0001:script:SubTask2
  }

  PassTask Pass;
  ErrorTask Error(string reason);

  Transition SubTask1 handling Pass -> SubTask2;
  Transition SubTask1 handling Error -> Error;
  Transition SubTask2 handling IncrementCounter -> SubTask2;
  Transition SubTask2 handling Pass -> Pass;
  Transition SubTask2 handling Error -> Error;
}

샘플에 대응하는 GS2-Script 예제

SubTask1

args.variables.currentCounter = args.params.initCounter
args.variables.loopCounter = 0
result = {
	event="Pass",
	params={},
	updatedVariables=args.variables
}

SubTask2

args.variables.loopCounter = args.variables.loopCounter + 1
if args.variables.currentCounter < 5 then
	args.variables.currentCounter = args.variables.currentCounter + 1
	result = {
		event="IncrementCounter",
		params={},
		updatedVariables=args.variables
	}
else
	result = {
		event="Pass",
		params={},
		updatedVariables=args.variables
	}
end

언어 사양

StateMachine

StateMachine ${name} {

}

StateMachine 블록은 스테이트 머신을 정의하기 위해 사용하며, 파일 내에 여러 개를 기술할 수 있습니다. StateMachine에는 이름을 붙일 수 있으며, 파일 내에서 고유해야 합니다.

Variables

Variables {
  string ${variableName};
  int ${variableName};
  float ${variableName};
  bool ${variableName};
}

Variables 블록에서는 스테이트 머신이 가지는 상태 변수를 지정할 수 있습니다. 상태 변수는 「데이터 타입」과 「변수명」으로 구성됩니다.

데이터 타입에는 다음 종류를 지정할 수 있습니다.

이름데이터 타입
string문자열
int64비트 부호 있는 정수 값
float64비트 부동소수점 수
bool불리언 값

EntryPoint

EntryPoint ${taskName};

EntryPoint에는 스테이트 머신을 시작했을 때 최초로 전환되는 태스크를 지정합니다.

Task

Task는 상태를 나타내는 노드를 정의합니다. 노드에는 용도에 따라 몇 가지 종류가 존재합니다.

Task

Task ${taskName}(sting ${argumentName}, int ${argumentName}) {
  Event ${eventName}();
  Event Error(string Reason);

  Script ${scriptId}
}

Task 블록은 가장 일반적인 노드로, GS2-Script의 스크립트를 실행합니다. Task에는 이름을 붙일 수 있지만, StateMachine 내에서 고유해야 합니다. 여기서 정의한 이름은 태스크 간 Transition을 지정하는 데 사용합니다.

Task ${taskName}(sting ${argumentName}, int ${argumentName})

Task는 인수를 받을 수 있습니다. 인수는 없음, 단수, 또는 복수로 지정할 수 있습니다. 인수 선언에는 「데이터 타입 변수명」을 사용하며, 여러 인수를 사용할 경우 쉼표로 구분합니다.

Event ${eventName}();

Event는 태스크 실행 중에 수신하는 이벤트의 종류를 정의합니다. Event는 여러 개 정의할 수 있습니다. 이벤트에는 이름을 붙일 수 있으며, 이벤트에 추가할 파라미터도 지정할 수 있습니다.

Event Error(string Reason);

주의할 점으로, Error(string Reason)라는 이벤트는 반드시 선언해야 합니다. 이는 스크립트 내에서 오류가 발생했을 때 메시지를 전송할 수도 있지만, 스크립트 실행에 실패하는 등 내부 처리에서도 전송될 수 있습니다.

Script ${scriptId}

Script는 태스크로 전환되었을 때 실행할 GS2-Script의 스크립트 GRN을 지정합니다.

Payload {
  result = {
      event="Event",
      params={},
      updatedVariables=args.variables
  }
}

Payload는 태스크로 전환되었을 때 실행할 GS2-Script를 직접 지정합니다.

Task는 Script 또는 Payload 중 하나를 반드시 구현해야 합니다. 두 가지를 동시에 기술한 경우에는 Script가 채택됩니다.

SubStateMachineTask

SubStateMachineTask ${taskName} {
  using ${nextStateMachine};
  in (${inputArgumentName} <- ${variableName});
  out (${outputVariableName} -> ${variableName});
}

SubStateMachineTask는 처리를 다른 스테이트 머신으로 이관하는 처리를 정의합니다. nextStateMachine에는 전환할 대상 스테이트 머신의 이름을 지정합니다.

in (${inputArgumentName} <- ${variableName});

in에는 전환 대상 스테이트 머신의 엔트리 포인트에 전달할 인수를 지정합니다. inputArgumentName에는 엔트리 포인트로 지정한 태스크가 받는 인수의 이름을 지정하고, variableName에는 인수에 전달할 값을 전환 전 스테이트 머신이 가진 상태 변수명으로 지정합니다.

out (${outputVariableName} -> ${variableName});

out에는 전환 대상 스테이트 머신이 PassTask로 전환되었을 때 받는 파라미터를 지정합니다. outputVariableName에는 전환 대상 스테이트 머신이 가진 상태 변수의 이름을 지정하고, variableName에는 돌아온 결과를 받는 현재 스테이트 머신의 상태 변수 이름을 지정합니다.

WaitTask

WaitTask ${taskName} {
  Event ${eventName}(sting ${argumentName}, int ${argumentName});
}

WaitTask는 특별히 아무것도 하지 않는 태스크입니다. 다만 외부로부터의 메시지 전송을 대기합니다. 일반적으로 클라이언트에서 진행되는 게임의 결과를 기다리는 데 사용합니다.

Event ${eventName}(sting ${argumentName}, int ${argumentName});

Event는 태스크 실행 중에 수신하는 이벤트의 종류를 정의합니다. Event는 여러 개 정의할 수 있습니다. 이벤트에는 수신할 이벤트를 식별하는 이름을 붙일 수 있으며, 이벤트에 추가할 파라미터도 지정할 수 있습니다.

PassTask

PassTask Pass;

PassTask는 필수 노드로, 스테이트 머신의 완료를 나타내는 태스크입니다. PassTask의 이름은 반드시 Pass여야 합니다.

ErrorTask
ErrorTask Error(string reason);

ErrorTask는 필수 노드로, 스테이트 머신의 비정상 종료를 나타내는 태스크입니다. ErrorTask의 이름은 반드시 Error여야 합니다.

Transition

Transition ${taskName} handling ${eventName} -> ${nextTaskName};

Transition은 노드 간의 전환을 나타냅니다. taskName에는 전환 전 태스크명을, eventName에는 수신한 이벤트의 종류를, nextTaskName에는 전환 대상 태스크명을 지정합니다.