BlueGit

blue-star tribegen

Files

tribegen / web / docs / API_REFERENCE.md

API_REFERENCE.md

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