Skip to content

Objects API (Draft)

Jump to bottom Edit New page
Artie Choi edited this page May 29, 2014 · 5 revisions

Problems

Player별 정보를 기록하는 API는 V4기준으로 Item과 UserData가 있다. 그런데, 다음의 문제점이 있다.

  • Item이라는 이름 때문에, Item에는 게임내의 아이템을 넣어야 한다는 선입견이 있다.
  • Item은 일종의 singleton이기 때문에, instance 개념으로 클라이언트가 디자인될 때 제약이 생긴다. 예를 들어, 최근 모바일 게임의 '강화', '합성'의 구현이 어렵다
  • UserData와 Item이 분리되어 있어서, item_changes나 condition등에서 서로의 값을 참조할 수가 없도록 되어 있다.
  • Farm류 게임에서 일정 시간뒤에 아이템이 변경되는 것들을 안전하게(hacking-safe) 처리하기가 어렵다. (ex: Clash of Clans 에서 GoldMine 업그레이드시 1시간 후에 처리가 되어야 함)

Solution

Player별 정보를 저장하는 Object라는 새로운 개념을 만든다. Item과 UserData는 모두 deprecate 시킨다.

1. Object

Object는 기본적으로 다음과 같이 구성된다.

Name Type Description
class String Object의 class이름
id Option[String] ID. 서버에서 generate한다. singleton인 경우에는 null
[field] String 객체에 포함된 field들.

1.1 Object의 사용

1.1.1 Get API 제공
1.1.2 Set API 제공
  • UserData처럼 Set을 할 수 있는 API 제공한다.
  • 만약 class 레벨에서 Set에 제한이 걸린경우 Set API 호출시 error 처리한다. 여기에 대해서는 ClassDescriptor 참고
1.1.3 Mission, IAP Conversion, Round 연동
  • Item에서와 마찬가지로 Mission, IAP Conversion, Round와 연동 한다.
1.1.4 Object Conversion Procedure 제공
  • ItemConversion의 대응 버전

1.2 Object의 Fields

  • 자유롭게 field를 추가 삭제할 수 있다.
  • field의 type은 모두 string이다.
  • default 값 세팅은 ClassDescriptor를 이용한다.
  • 다음 keyword는 reserved이다.
    • id
    • class
    • '_'로 시작하는 단어

2. ClassDescriptor

이전에 ItemProperty가 하는 기능에 더해서, Object에 제약 사항들을 정의한다. Object에 따라서 만들 수도 있고, 안만들 수도 있다.

Name Type Description
name String Object의 class 이름
comment String 사용자가 참고하기 적어놓는 것. API 동작과 무관
as_singleton Boolean singleton 방식인 경우. false인 경우 instance를 만들어서 사용해야 한다. 2가지 방식의 혼용은 안됨
protected_methods Array of String 'create'나 'destroy', 'set' 중에 막고자 하는 method 열거. singleton인 경우 자동으로 'create', 'destroy'는 막힌다.
fields Array of JSON Object
Name Type Description
name String field의 이름
default String default 값
event_handlers JSON Object key는 event 이름, value에는 handler의 역할을 하는 procedure의 이름이 들어간다.
event의 종류와 handler에 대해서는 하단의 'Event' 설명 참고

Event

Event Handler의 signature

Event handler의 procedure는 항상 'this'라는 객체를 전달받는다.

Event의 종류

Name 호출 시점 this
before_load 객체가 load되기 직전에 호출 'class'와 'id'만 담겨있다
after_load 객체가 load된 직후에 호출 load된 객체의 모든 정보가 담겨있다
before_save 객체가 save되기 직전에 호출 저장하려고 하는 객체의 정보
after_save 객체가 save된 직후에 호출 저장된 객체의 정보

API List

Object 얻어오기

  • Path: /:version/objects
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
    Name Type Description
    key Array of String [class]:[id]. id는 생략 가능. class가 'sword'이고, id가 'A'라면 'sword:A'가 됨

https://[server-url]/:version/objects?key=money&key=sword:A&key=sword:B

  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
objects Array of JSON Object Object의 array

Object instance 생성

  • Path: /:version/objects/create

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    objects Array of JSON Object
    Name Type Description
    class String 생성하려고 하는 instance의 class 이름

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
objects Array of JSON Object object

Object 저장

  • Path: /:version/objects/set

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    objects Array of JSON Object
    Name Type Description
    class String class 이름
    id Option[String] instance의 id. singleton인 경우 생략
    changes JSON Object {"item_name":"babo", "size": "100"} 과 같은 형식. 값이 null인 경우 field 삭제

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Object 제거

object를 제거. singleton인 경우에는 field가 reset됨.

  • Path: /:version/objects/destroy

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    objects Array of JSON Object
    Name Type Description
    class String class 이름
    id Option[String] instance의 id. singleton인 경우 생략

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Object Methods

Object의 method 종류는 다음과 같다.

Name Description
set 주어진 값으로 해당 field를 set 한다
create class 필요. object를 1개 생성
destroy id 필요. object를 소멸

Procedure

V4까지의 Item Conversion은 일종의 procedure 였다. V5부터는 Procedure를 Javascript를 이용해 정의하도록 한다.

자세한 설명은 Procedure 참고

Add a custom footer
Add a custom sidebar

Clone this wiki locally