BlueGit

blue-star tribegen

Files

tribegen / web / docs / API_REFERENCE.md

API_REFERENCE.md

farming
timfa Tim · pushed by timfa · 9 months ago
569cc974 History
API_REFERENCE.md 6.8 KiB Download Raw

API Reference

Authentication Endpoints

POST /api/auth/register

Register a new user.

Request:

{
    "email": "user@example.com",
    "password": "password123"
}

Response (Success - 200):

{
    "success": true,
    "user": {
        "id": 1,
        "email": "user@example.com",
        "token": "hex_token_string"
    }
}

Response (Error - 400):

{
    "success": false,
    "error": "Email already registered"
}

---

POST /api/auth/login

Login existing user.

Request:

{
    "email": "user@example.com",
    "password": "password123"
}

Response (Success - 200):

{
    "success": true,
    "user": {
        "id": 1,
        "email": "user@example.com",
        "token": "hex_token_string"
    }
}

Response (Error - 401):

{
    "success": false,
    "error": "Invalid email or password"
}

---

GET /api/auth/logout

Logout current user.

Response (Success - 200):

{
    "success": true
}

---

Game Endpoints

POST /api/game/generation

Generate initial tribe setup (20 random kobolds).

Request:

{
    "userId": 1,
    "saveName": "My Tribe"
}

Response (Success - 200):

{
    "success": true,
    "save": {
        "id": 1,
        "name": "My Tribe"
    },
    "kobolds": [
        {
            "id": 1,
            "age": 15,
            "stats": {
                "vitality": 45,
                "intelligence": 52,
                "medicine": 42,
                "crafting": 61,
                "personality": 48,
                "will": 55
            }
        }
    ]
}

---

GET /api/game/list

List all saves for user.

Headers:

Authorization: Bearer {token}

Response (Success - 200):

{
    "success": true,
    "saves": [
        {
            "id": 1,
            "name": "My Tribe",
            "current_month": 5,
            "current_season": "summer",
            "last_played": "2024-01-27 10:30:00"
        }
    ]
}

---

GET /api/game/load

Load a specific save.

Parameters:

saveId=1

Headers:

Authorization: Bearer {token}

Response (Success - 200):

{
    "success": true,
    "save": {
        "id": 1,
        "name": "My Tribe",
        "current_month": 5,
        "current_season": "summer"
    },
    "tribe": {
        "kobolds": [
            {
                "id": 1,
                "name": "Zyx",
                "age": 25,
                "ageCategory": "adult"
            }
        ]
    }
}

---

POST /api/game/save

Save tribe setup after kobold selection.

Request:

{
    "saveId": 1,
    "leaderName": "Zyx",
    "memberIndices": [1, 2, 3, 4, 5]
}

Response (Success - 200):

{
    "success": true,
    "tribe": {}
}

---

POST /api/game/event

Execute a player-initiated event.

Request:

{
    "saveId": 1,
    "eventType": "hunting"
}

Response (Success - 200):

{
    "success": true,
    "story": "The hunting party set out into the wilderness...\n\nThe hunters returned with valuable supplies."
}

---

POST /api/game/endMonth

End the current month and progress the game.

Request:

{
    "saveId": 1
}

Response (Success - 200):

{
    "success": true,
    "save": {
        "id": 1,
        "current_month": 6,
        "current_season": "summer"
    },
    "monthStory": "The month passed without major incident.\n\nZyx has grown older and wiser."
}

---

Error Responses

400 Bad Request

{
    "success": false,
    "error": "Description of what went wrong"
}

401 Unauthorized

{
    "success": false,
    "error": "Not authenticated"
}

404 Not Found

{
    "error": "Not found"
}

---

Frontend Usage Example

// Registration
const response = await fetch('/api/auth/register', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
        email: 'user@example.com', 
        password: 'pass123' 
    })
});
const data = await response.json();

// Use token for authenticated requests
const gameResponse = await fetch('/api/game/list', {
    method: 'GET',
    headers: { 'Authorization': `Bearer ${data.user.token}` }
});

---

Stat Values Reference

All stats are 0-100 internally but displayed as:

RangeLabel
0-10terrible
10-20bad
20-30unskilled
30-40decent
40-50good
50-60excellent
60-70fantastic
70-80master
80-90divine
90-100godlike

---

Age Categories Reference

CategoryAge RangeStat Scaling
egg< 00%
baby0-30-100% progression
adult4-34100%
old35-59100% + injuries
very_old60+100% + many injuries

---

Data Types

Kobold Object

[
    'id' => int,
    'saveId' => int,
    'name' => string,
    'age' => int (0-100),
    'stats' => [
        'vitality' => int (0-100),
        'intelligence' => int (0-100),
        'medicine' => int (0-100),
        'crafting' => int (0-100),
        'personality' => int (0-100),
        'will' => int (0-100)
    ],
    'spriteMorph' => string,
    'isLeader' => bool,
    'isAlive' => bool,
    'injuries' => [
        [
            'id' => int,
            'injuryType' => string,
            'category' => string,
            'severity' => int (0-10)
        ]
    ],
    'items' => [
        [
            'id' => int,
            'name' => string,
            'description' => string,
            'itemType' => string,
            'modifications' => ['stat_name' => int]
        ]
    ]
]

Tribe Object

[
    'id' => int,
    'name' => string,
    'currentMonth' => int,
    'currentSeason' => string (spring|summer|autumn|winter),
    'kobolds' => [Kobold, ...],
    'storage' => [Item, ...]
]

Save Object

[
    'id' => int,
    'userId' => int,
    'name' => string,
    'currentMonth' => int,
    'currentSeason' => string,
    'createdAt' => datetime,
    'lastPlayed' => datetime
]

---

HTTP Status Codes

CodeMeaning
200Success
400Bad request / validation error
401Unauthorized / not authenticated
404Not found
500Server error

---

Rate Limiting

Currently none implemented. Add if needed for production.

---

CORS

CORS is not enabled by default. Configure if needed for cross-origin requests.

---

Authentication

Use the token from login/register response in the Authorization: Bearer header for all subsequent requests that require authentication.

Tokens are stored in browser localStorage and should be cleared on logout.

---

Pagination

Not currently implemented. Can be added to the game/list endpoint if needed for large numbers of saves.

Source
1# API Reference
2
3## Authentication Endpoints
4
5### POST /api/auth/register
6Register a new user.
7
8**Request:**
9```json
10{
11 "email": "user@example.com",
12 "password": "password123"
13}
14```
15
16**Response (Success - 200):**
17```json
18{
19 "success": true,
20 "user": {
21 "id": 1,
22 "email": "user@example.com",
23 "token": "hex_token_string"
24 }
25}
26```
27
28**Response (Error - 400):**
29```json
30{
31 "success": false,
32 "error": "Email already registered"
33}
34```
35
36---
37
38### POST /api/auth/login
39Login existing user.
40
41**Request:**
42```json
43{
44 "email": "user@example.com",
45 "password": "password123"
46}
47```
48
49**Response (Success - 200):**
50```json
51{
52 "success": true,
53 "user": {
54 "id": 1,
55 "email": "user@example.com",
56 "token": "hex_token_string"
57 }
58}
59```
60
61**Response (Error - 401):**
62```json
63{
64 "success": false,
65 "error": "Invalid email or password"
66}
67```
68
69---
70
71### GET /api/auth/logout
72Logout current user.
73
74**Response (Success - 200):**
75```json
76{
77 "success": true
78}
79```
80
81---
82
83## Game Endpoints
84
85### POST /api/game/generation
86Generate initial tribe setup (20 random kobolds).
87
88**Request:**
89```json
90{
91 "userId": 1,
92 "saveName": "My Tribe"
93}
94```
95
96**Response (Success - 200):**
97```json
98{
99 "success": true,
100 "save": {
101 "id": 1,
102 "name": "My Tribe"
103 },
104 "kobolds": [
105 {
106 "id": 1,
107 "age": 15,
108 "stats": {
109 "vitality": 45,
110 "intelligence": 52,
111 "medicine": 42,
112 "crafting": 61,
113 "personality": 48,
114 "will": 55
115 }
116 }
117 ]
118}
119```
120
121---
122
123### GET /api/game/list
124List all saves for user.
125
126**Headers:**
127```
128Authorization: Bearer {token}
129```
130
131**Response (Success - 200):**
132```json
133{
134 "success": true,
135 "saves": [
136 {
137 "id": 1,
138 "name": "My Tribe",
139 "current_month": 5,
140 "current_season": "summer",
141 "last_played": "2024-01-27 10:30:00"
142 }
143 ]
144}
145```
146
147---
148
149### GET /api/game/load
150Load a specific save.
151
152**Parameters:**
153```
154saveId=1
155```
156
157**Headers:**
158```
159Authorization: Bearer {token}
160```
161
162**Response (Success - 200):**
163```json
164{
165 "success": true,
166 "save": {
167 "id": 1,
168 "name": "My Tribe",
169 "current_month": 5,
170 "current_season": "summer"
171 },
172 "tribe": {
173 "kobolds": [
174 {
175 "id": 1,
176 "name": "Zyx",
177 "age": 25,
178 "ageCategory": "adult"
179 }
180 ]
181 }
182}
183```
184
185---
186
187### POST /api/game/save
188Save tribe setup after kobold selection.
189
190**Request:**
191```json
192{
193 "saveId": 1,
194 "leaderName": "Zyx",
195 "memberIndices": [1, 2, 3, 4, 5]
196}
197```
198
199**Response (Success - 200):**
200```json
201{
202 "success": true,
203 "tribe": {}
204}
205```
206
207---
208
209### POST /api/game/event
210Execute a player-initiated event.
211
212**Request:**
213```json
214{
215 "saveId": 1,
216 "eventType": "hunting"
217}
218```
219
220**Response (Success - 200):**
221```json
222{
223 "success": true,
224 "story": "The hunting party set out into the wilderness...\n\nThe hunters returned with valuable supplies."
225}
226```
227
228---
229
230### POST /api/game/endMonth
231End the current month and progress the game.
232
233**Request:**
234```json
235{
236 "saveId": 1
237}
238```
239
240**Response (Success - 200):**
241```json
242{
243 "success": true,
244 "save": {
245 "id": 1,
246 "current_month": 6,
247 "current_season": "summer"
248 },
249 "monthStory": "The month passed without major incident.\n\nZyx has grown older and wiser."
250}
251```
252
253---
254
255## Error Responses
256
257### 400 Bad Request
258```json
259{
260 "success": false,
261 "error": "Description of what went wrong"
262}
263```
264
265### 401 Unauthorized
266```json
267{
268 "success": false,
269 "error": "Not authenticated"
270}
271```
272
273### 404 Not Found
274```json
275{
276 "error": "Not found"
277}
278```
279
280---
281
282## Frontend Usage Example
283
284```javascript
285// Registration
286const response = await fetch('/api/auth/register', {
287 method: 'POST',
288 headers: { 'Content-Type': 'application/json' },
289 body: JSON.stringify({
290 email: 'user@example.com',
291 password: 'pass123'
292 })
293});
294const data = await response.json();
295
296// Use token for authenticated requests
297const gameResponse = await fetch('/api/game/list', {
298 method: 'GET',
299 headers: { 'Authorization': `Bearer ${data.user.token}` }
300});
301```
302
303---
304
305## Stat Values Reference
306
307All stats are 0-100 internally but displayed as:
308
309| Range | Label |
310|-------|-------|
311| 0-10 | terrible |
312| 10-20 | bad |
313| 20-30 | unskilled |
314| 30-40 | decent |
315| 40-50 | good |
316| 50-60 | excellent |
317| 60-70 | fantastic |
318| 70-80 | master |
319| 80-90 | divine |
320| 90-100 | godlike |
321
322---
323
324## Age Categories Reference
325
326| Category | Age Range | Stat Scaling |
327|----------|-----------|--------------|
328| egg | < 0 | 0% |
329| baby | 0-3 | 0-100% progression |
330| adult | 4-34 | 100% |
331| old | 35-59 | 100% + injuries |
332| very_old | 60+ | 100% + many injuries |
333
334---
335
336## Data Types
337
338### Kobold Object
339```php
340[
341 'id' => int,
342 'saveId' => int,
343 'name' => string,
344 'age' => int (0-100),
345 'stats' => [
346 'vitality' => int (0-100),
347 'intelligence' => int (0-100),
348 'medicine' => int (0-100),
349 'crafting' => int (0-100),
350 'personality' => int (0-100),
351 'will' => int (0-100)
352 ],
353 'spriteMorph' => string,
354 'isLeader' => bool,
355 'isAlive' => bool,
356 'injuries' => [
357 [
358 'id' => int,
359 'injuryType' => string,
360 'category' => string,
361 'severity' => int (0-10)
362 ]
363 ],
364 'items' => [
365 [
366 'id' => int,
367 'name' => string,
368 'description' => string,
369 'itemType' => string,
370 'modifications' => ['stat_name' => int]
371 ]
372 ]
373]
374```
375
376### Tribe Object
377```php
378[
379 'id' => int,
380 'name' => string,
381 'currentMonth' => int,
382 'currentSeason' => string (spring|summer|autumn|winter),
383 'kobolds' => [Kobold, ...],
384 'storage' => [Item, ...]
385]
386```
387
388### Save Object
389```php
390[
391 'id' => int,
392 'userId' => int,
393 'name' => string,
394 'currentMonth' => int,
395 'currentSeason' => string,
396 'createdAt' => datetime,
397 'lastPlayed' => datetime
398]
399```
400
401---
402
403## HTTP Status Codes
404
405| Code | Meaning |
406|------|---------|
407| 200 | Success |
408| 400 | Bad request / validation error |
409| 401 | Unauthorized / not authenticated |
410| 404 | Not found |
411| 500 | Server error |
412
413---
414
415## Rate Limiting
416
417Currently none implemented. Add if needed for production.
418
419---
420
421## CORS
422
423CORS is not enabled by default. Configure if needed for cross-origin requests.
424
425---
426
427## Authentication
428
429Use the token from login/register response in the `Authorization: Bearer` header for all subsequent requests that require authentication.
430
431Tokens are stored in browser localStorage and should be cleared on logout.
432
433---
434
435## Pagination
436
437Not currently implemented. Can be added to the game/list endpoint if needed for large numbers of saves.