This repository has been archived by the owner on May 21, 2018. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
dinoisland.thrift
407 lines (383 loc) · 14.4 KB
/
dinoisland.thrift
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
/**
* Dinosaur Island
*
* Dinosaur Island is meant to be an open-ended game/puzzle where authors can
* write their own dinosaur logic and attempt to thrive and/or dominate on the
* eponymous island. Dinosaur Island features two types of dinosaurs,
* herbivores and carnivores. You start the game by implementing a dinosaur
* client using the Thrift open-source RPC framework. Your client must provide
* an email address which is used to generate a unique identifier for your
* newly created species of dinosaur. As the game progresses, your dinosaur
* may be able to lay an egg, allowing you to connect an additional client to
* the server, and take control of newly created instance of your species.
*
* Your dinosaur starts off with a limited calorie pool and must spend them
* wisely, moving around the island, detecting danger, growing in size, and
* eating things (either plants or other dinosaurs).
*
* Dinosaur Island features arcade style scoring, where your species (i.e. all
* clients under your control, representing all instances of your dinosaur
* species) has a fixed time limit to accumulate points by performing actions
* appropriate to its species type. At the end of that time limit, all
* instances of your species will die (i.e. an extinction event). Regardless of
* how this happens, either through species time limit being reached, or your
* dinosaur goes extinct from predation or lack of food, your species will be
* given a score. If your species scored above a certain threshold
* (even if it's not in the top 10 scores), you will be given a hash string.
* Send an email to [email protected], attach your code, and use that string
* code as the subject line in order to receive credit for solving Dinosaur
* Island.
*
*/
/**
* Recommended Java namespace
*/
namespace java com.facebook.puzzles.dinoisland.thrift
/**
* Entity types
*
* Entities are things that your dinosaur can see and possibly interact with.
* Your dinosaur is able to interact with Plants, Herbivore dinosaurs, and
* Carnivore dinosaurs. Your dinosaur can see impassable terrain, but cannot
* interact with it.
*/
enum EntityType {
PLANT = 0,
HERBIVORE = 1,
CARNIVORE = 2,
IMPASSABLE = 3
}
/**
* Directions
*
* These enums define directions used on the grid based map of Dinosaur Island.
* In order for your dinosaur to lay an egg, look, or move, it must supply one
* of these enums.
*/
enum Direction {
N = 0,
NE = 1,
E = 2,
SE = 3,
S = 4,
SW = 5,
W = 6,
NW = 7
}
/**
* Coordinate struct
*
* This structure is intended to explicitly define how the coordinate system of
* Dinosaur Island is set up.
*/
struct Coordinate {
1:i32 row,
2:i32 column
}
/**
* Dinosaur State
*
* This structure contains all pertinent data regarding your dinosaur instance,
* including its available calories to spend, its current size, and how many
* calories it will cost to lay an egg, grow one size, look in a direction,
* and move in a direction.
*/
struct DinosaurState {
1:i32 calories,
2:i32 size,
3:i32 eggCost,
4:i32 growCost,
5:i32 lookCost,
6:i32 moveCost
}
/**
* Sighting struct
*
* This structure represents your dinosaur sighting something interesting, be
* it plants to eat, dinosaurs to eat, or fearsome carnivores to avoid. Lastly,
* this struct is also used to tell your dinosaur when it sees impassable
* terrain.
*
* Each sighting includes coordinates of the sighting (coordinates are always
* relative to your own dinosaur's position), what kind of entity was spotted,
* as well as the species string and what size the entity is. In the case of
* impassable terrain, species will be blank and size will be 0.
*/
struct Sighting {
1:Coordinate coordinate,
2:EntityType type,
3:string species,
4:i32 size
}
/**
* Register Client results
*
* This structure is returned to your client after it calls the registerClient
* function. It includes a string message welcoming you to Dinosaur Island,
* as well as your randomly generated species name. It is important to note
* that this randomly generated species name is how other clients will see your
* dinosaur, and this is different from the highScoreName you chose originally
* if your dinosaur makes it into the evolutionary hall of fame. Lastly, it
* includes an integer egg ID which your client can then use to take over
* control of the very first instance of your dinosaur species.
*/
struct RegisterClientResults {
1:string message,
2:string species,
3:i64 eggID
}
/**
* Look action results
*
* This structure is returned to your client after it calls the look function.
* It includes a string message (useful for debugging), a boolean indicating
* action success, as well as the new state for your dinosaur, and a list of
* Sighting structs (see above).
*/
struct LookResults {
1:string message,
2:bool succeeded,
3:DinosaurState myState,
4:list<Sighting> thingsSeen
}
/**
* Grow action results
*
* This structure is returned to your client after it calls the grow function.
* It includes a string message (useful for debugging), a boolean indicating
* action success, as well as the new state for your dinosaur.
*/
struct GrowResults {
1:string message,
2:bool succeeded,
3:DinosaurState myState
}
/**
* Move action results
*
* This structure is returned to your client after it calls the move function.
* It includes a string message (useful for debugging), a boolean indicating
* action success, as well as the new state for your dinosaur. The most common
* reason for the boolean succeeded returning False is your dinosaur attempted
* to move into impassable terrain.
*/
struct MoveResults {
1:string message,
2:bool succeeded,
3:DinosaurState myState
}
/**
* Lay an Egg action results
*
* This structure is returned to your client after it calls the egg function.
* It includes a string message (useful for debugging), a boolean indicating
* action success, the new state of your dinosaur, and the integer egg ID of
* your newly created egg if the action was successful. If the egg function
* fails, the egg ID will be 0.
*/
struct EggResults {
1:string message,
2:bool succeeded,
3:DinosaurState parentDinoState,
4:i64 eggID
}
/**
* Bad egg exception
*
* This exception is thrown if a client attempts to take control of a newly
* hatched dinosaur egg but fails. The string contains a description of the
* failure, which may include incorrect egg ID or trying to take over an egg
* of a different species (i.e. a dinosaur that does not belong to your email
* address).
*/
exception BadEggException {
1:string description
}
/**
* You are dead exception
*
* This exception is thrown if a client attempts to call an action function,
* but the dinosaur controlled turns out to be already dead. This can happen if
* the dinosaur your client controls is eaten by a predator, or has exceeded
* its real time lifespan. The string will contain useful information about the
* cause of death for your dinosaur.
*/
exception YouAreDeadException {
1:string description
}
/**
* Already registered exception
*
* This exception is thrown if a client that is already controlling a dinosaur
* attempts to call registerClient().
*/
exception AlreadyRegisteredException {
1:string description
}
/**
* Game over exception
*
* This exception is thrown if a client attempts to call an action function,
* but the species has already died out, either due to having all of the
* dinosaurs die of natural causes or due to the species time limit being
* reached. The wonGame field will be true if your species scored high enough
* to win the game. The score field will provide your total score. The message
* field will contain instructions for how to get credit for winning the game
* if your species scored high enough to win, and will also contain the reason
* your species went extinct. The highScoreTable field will contain the top 10
* high scores since the server was started. Note that the highScoreTable
* does not list dinosaur species names, instead it users the chosen
* highScoreNames provided by each puzzler's registerClient() call to register
* their species.
*/
exception GameOverException {
1:bool wonGame,
2:i32 score
3:string message,
4:string highScoreTable,
}
/**
* Dinosaur Island service
*
* This is the API used by clients to interact with the Dinosaur Island
* server. Functions have two attributes, whether they are actual game
* functions which cost calories to use, and whether they take up a dinosaur's
* turn, causing that connection thread to sleep until the next game turn.
*
* All dinosaurs have two resources, their size and their available calories.
* In addition, all dinosaurs have an individual lifespan before that
* particular instance of the dinosaur will die of old age. In order for your
* species to survive and score points, it must eventually lay eggs.
*
* Should your dinosaur not have enough calories to perform a given action, it
* will die of starvation. If your dinosaur simply idles, it will eventually
* die of old age.
*
* Eventually, your species time limit will expire, and all instances of your
* dinosaur species will die off at the same time. One of your client(s) will
* call an action API and the GameOverException will be returned, informing you
* that your species died off, what your high score is, and whether your
* species scored high enough to "solve" the puzzle, and what the top 10 scores
* are for this island.
*/
service Dinosaur {
/**
* Register Client
*
* Costs calories: No
* Uses up turn: No
*
* This function must be the very first thing called by the first client that
* connects to the Dinosaur Island server. This function is slightly
* different from the instructions on the Public Thrift Server, but serves an
* identical purpose. In addition to the required email, it also requires
* a string of what to display in the high score table should your species
* rank in the top 10, as well as a chosen dinosaur type (herbivore or
* carnivore).
*/
RegisterClientResults registerClient(string email, string highScoreName, EntityType type)
throws (AlreadyRegisteredException alreadyRegistered);
/**
* Hatch an egg (take over a previously laid egg)
*
* Costs calories: No
* Uses up turn: No
*
* Allows a client connection to take control of an egg, identified by the
* egg ID parameter. Returns the DinosaurState of the newly controlled
* dinosaur if successful, throws an exception otherwise.
*/
DinosaurState hatch(i64 eggID)
throws (BadEggException badEgg, YouAreDeadException youAreDead,
GameOverException gameOver);
/**
* Lay an egg
*
* Costs calories: Yes
* Uses up turn: Yes
*
* Lays an egg in the specified direction, in addition to giving the new
* egg some calories to help it survive. This function costs calories to use
* and your dinosaur is responsible for ensuring it has enough to call this
* function without starving to death. The cost of this function is equal to
* the eggCost value (found in any DinosaurState struct returned) plus the
* calories given to the egg. The newly hatched dinosaur will not gain all
* of these calories, up to 20% of them will be lost in the transfer.
*
* This function returns an EggResults on success that contains useful
* information, such as the current state of the egg laying dinosaur, the
* egg ID of the newly laid egg, among other info. Another Dinosaur Island
* client can then connect and start playing after calling the hatch func
* with the egg ID. This function throws an exception otherwise.
*/
EggResults egg(Direction direction, i32 calories_given)
throws (YouAreDeadException youAreDead, GameOverException gameOver);
/**
* Look (in a direction)
*
* Costs calories: Yes
* Uses up turn: Yes
*
* If successful, the dinosaur will use up a number of calories (found in any
* DinosaurState struct returned) and return an list of Sighting structs
* representing things the dinosaur saw in that direction. Sight is treated
* as a cone radiating out from the dinosaur in question.
*
* How far a dinosaur can see is dependent on how big the actual dinosaur
* is, and the sizes of the objects in the cone.
*
* Two examples of cone shapes are given below:
*
* + +
* ++ ++
* +++ +++
* D+++ ++++
* +++ +++++
* ++ ++++++
* + D++++++
*/
LookResults look(Direction direction)
throws (YouAreDeadException youAreDead, GameOverException gameOver);
/**
* Grow
*
* Costs calories: Yes
* Uses up turn: Yes
*
* If successful, the dinosaur will increments its size by one. All dinosaurs
* start with a size of one. Size is used in determining how far a dinosaur
* can see (or how easily your dinosaur can be seen), as well as how likely
* a dinosaur is in winning a fight with another dinosaur. Lastly, if your
* dinosaur is eaten, it will be worth more calories the bigger it is.
*
* This function returns a GrowResults struct upon success and throws an
* exception otherwise.
*/
GrowResults grow()
throws (YouAreDeadException youAreDead, GameOverException gameOver);
/**
* Move
*
* Costs calories: Yes
* Uses up turn: Yes
*
* Moves the dinosaur in the direction specified; if an entity exists in the
* target square, the dinosaur will fight with that entity.
*
* Plants always lose battles, no matter what moves into their square. If the
* attacker is an herbivore, it will gain calories based upon the plant's
* size. Carnivores merely destroy the plant with no calories gained.
*
* If one dinosaur moves into another, they will fight. Carnivores gain a
* significant boost to their odds of victory when fighting herbivores. If
* a carnivore wins over an herbivore, it will gain calories based upon the
* size of the herbivore, and how many calories the herbivore had at time of
* death.
*
* If your dinosaur attempts to move into impassable terrain, the
* MoveResults struct will contain a success boolean of false, indicating
* the dinosaur did not actually change positions.
*/
MoveResults move(Direction direction)
throws (YouAreDeadException youAreDead, GameOverException gameOver);
}