h2. 게임 데이터를 표현하는 기본적인 개념 소개 h3. 데이터시트 게임에서 사용할 레벨 데이터들은 일반적으로 행(Row)과 열(Column)로 구성된 테이블 형태로 표현한다. 캐릭터, 아이템, 스킬, 보상 등의 많은 항목들을 표현하므로, 대개 그러한 테이블 형태가 수십 개 이상 필요할 수 있다. 그러한 테이블 데이터들은 대개 스프레트시트 포맷으로 작성하는데, 이를 프로젝트 내부의 용어로 "데이터시트(Datasheet)"라고 부른다. 이 설명서에서 다루는 대상들은 모두 데이터시트들이다. h3. 데이터 스크립트 데이터시트들은 게임 프로그램에서 그대로 사용하지 않는다. 그 이유는 게임 프로그램이 서버와 클라이언트로 나뉘어져 있기 때문이다. 서버와 클라이언트들은 각자 필요로 하는 정보의 종류가 다르다. 예를 들어, 캐릭터의 모델, 아이템의 모델, 지형 맵의 모델, 아이콘, UI 텍스트 등의 정보들은 전부 클라이언트에서만 필요로 하는 정보들이고, 서버는 이런 정보들이 전혀 필요가 없다. 반면에, (게임의 특성에 따라 다르겠지만)보상 판정, 아이템 생성 옵션을 결정하는 사항 등은 서버만 가지고 있으면 되고, 클라이언트에서 알 필요가 없는 정보들이다. 그렇지만 데이터시트는 사람이 편집하기 좋도록 만들기 때문에, 게임 서비스 모듈 별로 필요한 데이터들만 따로 모아놓는 방식으로 테이블 데이터들을 구분하지는 않는다. 또한, 서버와 클라이언트가 둘 다 필요로 하는 정보들도 매우 많으므로, 서버와 클라이언트가 사용하는 데이터시트를 별도로 제작할 경우, 종복해서 작성해야 하는 데이터가 매우 많아진다. 데이터시트는 사람이 편집해야 하기 때문에, 이런 중복 정보가 많아지면 관리도 힘들고, 공통 항목 중에서 한 쪽에는 반영하고 다른 쪽은 반영하지 않는 실수가 일어나기도 쉽다. 다른 이유도 존재한다. 데이터시트는 사람이 알아보거나 편집하기 쉽게 하기 위해 가급적 문자열 기반으로 데이터를 참조하도록 유도한다. 문자열 기반의 데이터 참조는 사람이 사용하기에는 쉽지만, 컴퓨터 프로그램은 숫자를 사전 키(Dictionary Key)로 사용할 때 처리를 훨씬 빠르게 할 수 있다. 또한, 게임 내에서는 전혀 사용하지 않을 주석으로 할당하는 필드도 존재한다. 이런 이유들 때문에, 데이터시트는 그대로 게임에 탑재하지 않고, 각각 클라이언트와 서버의 프로그램에 더 적합한 포맷으로 변환해서 사용한다. 이를 위한 별도의 전용 변환 도구 프로그램이 존재한다. (EodDatascriptGenerator가 그것이다.) 이 변환 도구는 데이터시트에 들어 있는 데이터를 클라이언트와 서버에 맞는 포맷으로 변환하는 기능을 한다. 그렇게 각 서비스 모듈에 맞게 변환되어 나온 데이터 파일들을 "데이터 스크립트"로 부른다. h3. 소스 파일 데이터시트를 데이터스크립트로 변환할 때, 클라이언트 또는 서버의 프로젝트 소스에서 데이터시트에서 정의한 내용들을 직접 소스 코드로 사용할 수 있도록 소스 파일을 생성한다. 소스 파일의 포맷은 그것을 사용할 클라이언트, 서버 프로젝트의 프로그래밍 언어에 따라 다를 수 있다. 이 부분은 순전히 프로그래머를 위한 기능이다. h2. 데이터시트의 기본 형식 모든 데이터시트는 기본적으로 아래와 같은 4개의 줄을 가진다. h3. 1번째 줄 - 데이터 스크립트 / 소스 파일 제목 총 2개의 열로 구성되어 있으며, 데이터시트에서 열의 개수가 고정적으로 정해져 있는 유일한 줄이다. 1번째 열 : 생성할 데이터 스크립트의 파일 이름이다. 2번째 열 : 소스 파일을 생성할 경우, 그 소스 파일에서 사용할 데이터 객체의 이름이다. h3. 2번째 줄 - 필드 이름 선언 필드 이름을 지을 때는 다음과 같은 규칙을 따라야 한다. * 영어 대 / 소문자와 아라비아 숫자, 언더 바(_)만을 사용해서 이름을 지어야 한다. * 이름은 중간에 공백이 없어야 한다. 공백이 필요할 경우, 언더 바(_)로 대신한다. * 맨 앞글자는 숫자가 올 수 없다. 필드 이름은 소스 코드의 변수 이름으로도 사용한다. h3. 3번째 줄 - 데이터를 탑재할 게임 서비스 모듈 지정 해당 필드가 어떤 게임 서비스 모듈에 탑재될 것인지 지정한다. 다음과 같은 값들이 올 수 있다. Common : 서버와 클라이언트가 둘 다 사용하는 필드 Client : 클라이언트에서만 사용하는 필드 Server : 서버에서만 사용하는 필드 Tool : 변환 툴에서만 사용하고, 클라이언트, 서버 어느 쪽에서도 사용하지 않는 필드 h3. 4번째 줄 - 자료형 선언 자료형은 데이터시트의 각 필드를 어떤 데이터 타입으로 읽고 저장할지 지정하는 역할을 한다. 데이터 중에서 어떤 열은 숫자로 해석하고, 어떤 열은 문자열로 읽어야 할 수 있다. 또는 숫자 중에서도 정수로 읽을지 소수로 읽을지 등을 결정해야 할 수도 있다. 데이터시트의 각 필드 열(Column)들은 하나의 데이터 타입으로 해석해야 한다. 같은 열에 있는 데이터들 중에서 어떤 줄은 숫자로 읽고 어떤 줄은 문자열로 읽게 할 수 없다. h2. 데이터시트에서 사용하는 자료형 사용할 수 있는 자료형의 종류는 다음과 같다. 정수를 표현해야 하는 경우는 다음 자료형들을 사용한다. *sbyte* : -128 ~ 127 *byte* : 0 ~ 255 *short* : -32,768 ~ 32,767 *unsigned short* : 0 ~ 65,535 *int* : -2,147,483,648 ~ 2,147,483,647 *unsigned int* : 0 ~ 4,294,967,295 *long* : ?9,223,372,036,854,775,808 ~ 9,223,372,036,854,775,807 *unsigned long* : 0 ~ 18,446,744,073,709,551,615 가급적 예상되는 최소 ~ 최대값의 범위에 딱 맞는 자료형을 사용하는 게 좋다. 에를 들어, 사용하는 값이 아무리 해봐야 0 ~ 100 범위를 넘지 않는다면, int 대신 sbyte를 쓰는 게 좋다. 왜냐하면 더 큰 범위의 숫자를 저장하는 값들은 더 많은 공간을 차지하기 때문이다. (sbyte는 1바이트, int는 4바이트의 저장공간을 차지한다.) 데이터 값들은 경우에 따라 네트워크로 전송하거나 데이터베이스에 저장하는 대상이 될 수 있는데, 이 때는 숫자의 저장공간의 크기도 효율에 영향을 미치는 요소가 될 수 있다. 더 큰 저장공간을 차지하는 자료들일수록 네트워크 전송은 더 지연된다. 데이터베이스의 경우, 고작 몇 바이트 정도의 불필요한 공간 낭비일지라도, 그런 데이터가 수백만 ~ 수천만 건씩 쌓아야 할 경우에는 저장장치의 용량에 있어 큰 부담이 될 수 있다. 실수를 표현해야 하는 경우는 다음 자료형들을 사용한다. *float* : 소수점 3자리까지 허용한다. *double* : 소수점 6자리까지 허용한다. *percent* : 퍼센트 단위를 사용해야 하는 경우에 쓴다. 데이터시트에는 100% = 100의 관계이지만, 데이터 스크립트로 변환할 때는 100% = 1.0의 관계가 되도록 변환하여 저장한다. 그 외 자료형들 *EodGTC* : 일반 타입 식별 코드 자료형 사용에 대한 문서를 참조한다. *bool* : 참 / 거짓만 표현하는 필드일 경우에 사용한다. 값은 TRUE와 FALSE의 두 가지 뿐이다. *string* : 문자열로 저장해야 하는 경우에 사용한다. *enum* : 열거형 사용에 대한 문서를 참조한다. *list<$Type$>* : 목록 자료형 사용에 대한 문서를 참조한다. *datetime* : 날짜를 표현해야 하는 경우에 사용한다. 반드시 *YYYY-MM-DD*(4자리 연도-2자리 월-2자리 일) 형식으로 써야 한다. 연도를 두 자리수로 표기하거나, 일월의 순서를 바꾸는 등의 방식은 허용하지 않는다. h2. 일반 타입 식별 코드(General Type Code) 일반 타입 식별 코드는 종종 GTC라는 약자로 지칭한다. 게임 내에서 종류를 구별해야 하는 식별 단위들은 공통적으로 GTC를 식별키로 사용할 수 있다. h3. GTC의 사용 조건 - *GTC는 한 번 정의하면, 그 값이 절대로 바뀌어서는 안 된다.* 특히, 게임을 공개 서비스한 이후에는 한 번 정의한 GTC의 숫자 값은 결코 바꿔서는 안 된다. GTC의 값은 사용자 데이터베이스에서도 사용할 수 있는 값이기 때문이다. 따라서, GTC의 번호를 부여하는 방식은 사전에 향후 컨텐츠의 확장을 고려해서 엄밀하게 규정해야 나중에 혼란을 줄일 수 있다. - GTC의 값은 가급적 전체 테이블에서 유일하도록 설계하기를 권장하지만, 최소한 하나의 데이터시트 단위에서는 독립적으로 숫자 범위를 사용할 수 있다. : 예를 들어, 만약 아이템 데이터시트가 1000 ~ 5000의 GTC들로 구성되어 있다면, 다른 종류의 데이터시트(캐릭터, 스테이지 등)에서 1000 ~ 5000의 GTC들을 사용하더라도 관계가 없다는 뜻이다. 물론, 아이템 데이터시트 내에서는 GTC가 서로 겹치는 값이 있으면 안 된다. A 아이템의 GTC가 1500이면, 다른 아이템들은 A 아이템의 GTC인 1500과 다른 숫자를 가져야 한다. (그게 1499이든, 1501이든 간에) 그러나 텍스트 데이터시트 중의 한 항목은 아이템 데이터시트에서 1500의 GTC를 가진 항목이 있는지와 관계없이 1500의 GTC를 가질 수 있다. h3. GTC 사용 방식 GTC를 데이터시트의 필드에 사용할 때는, GTC를 사용할 열에서 값 타입을 정의하는 부분(데이터시트의 4번째 줄)을 다음 중 하나로 지정한다. *EodGTC : primitive* GTC를 정의할 때 사용한다. GTC는 본래 int의 값 범위를 가지는 숫자이다. 따라서, EodGTC : primitive를 사용하는 필드의 값은 숫자를 적어야 한다. *EodGTC : key_define* EodGTC : primitive로 정의한 타입 식별 코드 숫자를 특정한 문자열 값과 결합할 때 사용한다. 따라서 EodGTC : primitive로 GTC를 정의한 열과 다른 열에 사용해야 하고, 항상 EodGTC : primitive로 정의한 열과 같이 사용해야 한다. 실제로, 모든 데이터시트를 살펴봐도, GTC : primitive를 쓰는 열이 있으면, 반드시 그 옆에 EodGTC : key_define을 쓰는 열이 같이 있다. *EodGTC : key_reference : $(Datasheet Name)* 데이터시트의 한 항목 열을 다른 데이터시트에 정의한 데이터와 관계짓고 싶은 경우, 그 열의 데이터는 참조할 다른 데이터시트의 GTC를 값을 필드에 넣도록 설계를 하게 된다. 이 때, 그 GTC를 GTC 본래의 값인 int 숫자 값으로 받는 대신, EodGTC : key_define으로 정의한 GTC 문자열 키를 값으로 받게 하기 위해서 이와 같은 방식으로 값 형식을 선언한다. $(Datasheet Name)는 어떤 데이터시트에서 정의한 GTC인지를 지정하기 위해서 필요하다. GTC는 가급적 전역적으로 유일한 값을 가지도록 권장하지만, 이를 강제하지는 않기 때문에, 반드시 어느 데이터시트의 GTC인지를 알아야 한다. 데이터시트는 사람이 수동으로 편집하는 경우가 대부분이기 때문에, 숫자보다는 문자열로 GTC를 구분하게 하는 편이 편의성이나, 사용성에 있어 훨씬 더 좋다. 다만, 프로그램에서는 GTC 값이 숫자인 편이 욜양이나 속도 면에서 더 낫기 때문에, 툴에서 데이터시트를 데이터 스크립트로 변환할 때는, 문자로 참조한 GTC들은 전부 GTC의 본래 숫자 값으로 변환하여 저장한다. h2. 열거형(enum) 열거형은 미리 정의되어 있는 몇 개의 값 중 하나를 선택하는 방식이다. 그래서 프로그램 내부에서 실제로는 숫자값으로 작동하지만, 데이터시트에 기입할 때는 사전에 값과 연결하도록 정의한 문자열을 쓴다. 열거형 세부 규약은 프로그램 소스 코드 단계에서 사전에 정의해야 하기 때문에, 새로운 열거형이 필요한 경우에는 개발자 간에 이 부분을 먼저 조율하고, 새 열거형 타입을 소스 코드에 반영하는 작업이 우선되어야 데이터시트에서도 사용할 수 있다. 데이터시트에서 열거형 타입을 선언하는 형식은 다음과 같다. enum : $(정수 타입) : $(열거형의 이름) *$(정수 타입)* : 해당 열거형이 정수 값으로 어느 정도의 범위를 사용하는지 적는다. 대개는 sbyte, short 둘 중 하나이다. *$(열거형의 이름) : 열거형의 이름을 쓴다. h2. 목록 자료형(list<$Type$>) 하나의 필드에 여러 개의 자료를 넣어야 하는 경우가 종종 있다. 특히, *매개변수가 몇 개가 필요한지 그때그때 달라야 하는 경우*에 주로 매개변수들을 목록으로 만들어서 넣는 기능이 특히 유용하다. 데이터의 모델은 같은데 매개변수가 어떤 경우에는 3개가 필요하고 어떤 경우는 5개가 필요한 경우가 있다면, 그리고 그러한 경우의 가짓수가 매우 많다면 테이블을 일일이 분리하는 것보다는 필드 하나에 여러 개의 데이터를 묶어서 보낼 수 있게 하는 편이 더 낫다. h3. 목록 자료형의 선언 방식 목록 자료형을 사용하는 형식은 다음과 같다. list<$(자료형)> 특히, 매개변수들을 보내는 개수 뿐 아니라, 형식조차도 각 데이터마다 달라질 수 있는 경우에는 매개변수들을 모두 문자열 형식으로 전달하는 기법(list)을 쓸 수 있다. 이 경우, 매개변수들을 적절하게 해석하는 일은 데이터시트의 데이터들을 받아들이는 객체에게 그 책임이 있다. GTC를 목록으로 보내야 하는 경우에는, 그 GTC가 원시 타입(숫자 형)인지 참조키 타입(문자열 형)인지 콜론(':')으로 구분해야 한다. 원시 타입일 경우에는 list : primitive 참조키 타입일 경우에는 list : key_reference : $(데이터 객체의 이름) 만약 아무런 추가 정보 없이 list라고만 사용할 경우에는 list : primitive와 동일하다. h3. 목록 자료형으로 값 넣기 * 어떤 필드에 값을 목록으로 넣으려고 할 경우, 여러 개의 값을 쉼표(',')로 구분해서 기입한다. 예를 들어, 1 ~ 5를 목록으로 필드에 값을 할당하려고 할 경우, 다음처럼 표기한다. 1, 2, 3, 4, 5 5개의 문자열을 목록으로 구성해서 필드에 값을 넣는 경우 다음처럼 표기한다. apple, peach, melon, grape, tomato * 쉼표와 쉼표 사이에는 공백이나 줄바꿈을 할 수 있다. 아래 예시는 둘 다 규약에 맞는 표현이며 해석 결과도 같다. apple, peach, melon, grape, tomato apple, peach, melon, grape, tomato * 콜론(':')을 이용해서 목록의 개별적인 원소 값에 참조할 수 있는 이름을 부여할 수 있다. 참조 이름은 데이터시트 편집자의 편의를 위한 기능이며, 데이터 스크립트나 소스 파일로 변환할 때는 전혀 이용하지 않는다. 목록 필드에서의 참조 이름은 다음과 같은 형식으로 부여한다. $(값) : $(이름), $(값) : $(이름), $(값) : $(이름)... 예시는 다음과 같다. 1 : apple, 2 : peach, 3 : melon, 4 : grape, 5 : tomato 1 : apple, 2 : peach, 3 : melon, 4 : grape, 5 : tomato 위의 예에서, apple, peach 등의 문자열 값들은 데이터 스크립트나 소스 파일에서는 전혀 나타나지 않는다. 변환 과정을 거친 데이터 스크립트에서는 그냥 1, 2, 3, 4, 5의 값으로만 보인다. h2. 데이터시트 작성 규칙 - 데이터시트는 Excel 2003 XML 포맷(*.xml)으로 작성한다. - 원칙적으로 데이터 테이블의 형식이 달라질 경우, 데이터시트 파일은 별도로 만들어야 한다. : 하나의 데이터시트 파일 안에 여러 개의 다른 형식의 데이터 테이블을 워크시트 별로 생성해서는 안 된다. - 같은 데이터 테이블의 형식을 사용하지만 데이터가 너무 많거나 편집의 용이함을 위해 별도의 시트로 분리하고 싶은 경우, 하나의 데이터시트 파일 내에 여러 개의 탭으로 분할된 시트에 분리해서 저장할 수 있다. : 예를 들자면, UI에 표시할 텍스트 데이터들은 모두 같은 형식으로 작성하는 테이블 데이터이지만, 편집의 용이함을 위해 Text_Popup, Text_Stage, Text_Item 등으로 내부에 워크시트들을 탭으로 분할해서 둘 수도 있다. 그러나 소스 파일의 데이터 객체는 같은 타입의 객체를 사용해야 하고, 분할한 각 워크시트의 데이터들도 데이터 스크립트로 변환할 때는 하나의 파일에 합쳐서 들어간다.