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:
| Range | Label |
|---|---|
| 0-10 | terrible |
| 10-20 | bad |
| 20-30 | unskilled |
| 30-40 | decent |
| 40-50 | good |
| 50-60 | excellent |
| 60-70 | fantastic |
| 70-80 | master |
| 80-90 | divine |
| 90-100 | godlike |
---
Age Categories Reference
| Category | Age Range | Stat Scaling |
|---|---|---|
| egg | < 0 | 0% |
| baby | 0-3 | 0-100% progression |
| adult | 4-34 | 100% |
| old | 35-59 | 100% + injuries |
| very_old | 60+ | 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
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request / validation error |
| 401 | Unauthorized / not authenticated |
| 404 | Not found |
| 500 | Server 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 |
| 6 | Register 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 |
| 39 | Login 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 |
| 72 | Logout 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 |
| 86 | Generate 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 |
| 124 | List all saves for user. |
| 125 | |
| 126 | **Headers:** |
| 127 | ``` |
| 128 | Authorization: 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 |
| 150 | Load a specific save. |
| 151 | |
| 152 | **Parameters:** |
| 153 | ``` |
| 154 | saveId=1 |
| 155 | ``` |
| 156 | |
| 157 | **Headers:** |
| 158 | ``` |
| 159 | Authorization: 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 |
| 188 | Save 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 |
| 210 | Execute 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 |
| 231 | End 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 |
| 286 | const 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 | }); |
| 294 | const data = await response.json(); |
| 295 | |
| 296 | // Use token for authenticated requests |
| 297 | const 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 | |
| 307 | All 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 | |
| 417 | Currently none implemented. Add if needed for production. |
| 418 | |
| 419 | --- |
| 420 | |
| 421 | ## CORS |
| 422 | |
| 423 | CORS is not enabled by default. Configure if needed for cross-origin requests. |
| 424 | |
| 425 | --- |
| 426 | |
| 427 | ## Authentication |
| 428 | |
| 429 | Use the token from login/register response in the `Authorization: Bearer` header for all subsequent requests that require authentication. |
| 430 | |
| 431 | Tokens are stored in browser localStorage and should be cleared on logout. |
| 432 | |
| 433 | --- |
| 434 | |
| 435 | ## Pagination |
| 436 | |
| 437 | Not currently implemented. Can be added to the game/list endpoint if needed for large numbers of saves. |