Architecture Overview
Database Schema
Users
id(PK)email(UNIQUE)password_hashcreated_at
Saves
id(PK)user_id(FK)namecurrent_monthcurrent_seasoncreated_atlast_played
Kobolds
id(PK)save_id(FK)nameagevitality,intelligence,medicine,crafting,personality,willsprite_morphis_leaderis_aliveexpelledfather_id(FK, self-reference)mother_id(FK, self-reference)created_at
Injuries
id(PK)kobold_id(FK)injury_type(string)category(wound, fracture, etc.)severity(0-10)created_at
Items
id(PK)save_id(FK)namedescriptionitem_typecreated_at
Item Modifications
id(PK)item_id(FK)stat_namemodification(-5 to +5)
Kobold Items (many-to-many)
kobold_id(FK)item_id(FK)
Events Enabled
id(PK)save_id(FK)event_classenabled(boolean)
Injuries Enabled
id(PK)save_id(FK)injury_typeenabled(boolean)
NPCs
id(PK)save_id(FK)namenpc_type(tribe, individual)is_rival(boolean)data(JSON for extensibility)created_at
Class Hierarchy
Core Classes
Database: Singleton for SQLite accessUser: User authentication and save managementKobold: Individual kobold with stats, injuries, items, geneticsTribe: Collection of kobolds, tribe-level managementItem: Items with stat modificationsInjury: Injury tracking with severityNPC: Non-player characters/tribes
Event System
Event(abstract): Base class for all eventsEventManager: Manages enabled events, executes them- Event implementations:
HuntingEvent,ExplorationEvent,FarmingEvent, etc.
API Flow
Authentication
1. User registers/logs in via /api/auth/ 2. Server returns user object with token 3. Token stored in localStorage 4. Token sent with all subsequent requests
Game Creation
1. User submits tribe name to /api/game/generation 2. Server creates save record 3. Server generates 20 random kobolds 4. Returns kobold data to frontend
Game Load
1. User clicks save to load 2. Frontend calls /api/game/load?saveId=X 3. Server loads tribe, kobolds, items, injuries 4. Returns complete game state
Event Execution
1. User initiates event via /api/game/event 2. Server loads tribe state 3. Event modifies tribe state 4. Event returns narrative story 5. Frontend displays story in modal
Month Progression
1. User clicks "End Month" 2. Server increments month/season 3. Kobolds age 4. Old-age injuries applied 5. Random month-progression events occur 6. Dead kobolds removed 7. Story returned to frontend
Stat System
Stat Ranges
All stats are 0-100 internally but displayed as text:
- 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
Stat Checks
1. Get base stat value 2. Apply item modifications 3. Subtract injury severity total 4. For non-adults, multiply by age progress percentage 5. Clamp to 0-100 6. Roll 1d100 under stat (≤ stat = success)
Age Progression
- Eggs and babies: effective stat = base stat × age progress (0-100%)
- At age 4 (adult): 100% effective stat
- Stats remain at full value until old age
Event Architecture
Each event: 1. Receives the current Tribe object 2. Can read tribe state (kobolds, items, storage) 3. Can modify tribe state 4. Generates narrative story 5. Returns story to display
Example:
class HuntingEvent extends Event {
public function execute() {
$this->story = "The hunters set out...";
// Access tribe
$kobolds = $this->tribe->getAliveKobolds();
// Modify state
foreach ($kobolds as $kobold) {
if ($kobold->checkStat('vitality')) {
// Success
} else {
// Fail - maybe injury
$kobold->addInjury('wound', 'wound', 1);
}
}
$this->story .= "\nThe hunters returned...";
return $this->story;
}
}
Storage Structure
User saves are stored entirely in the SQLite database. Per-user directories in data/users/ are reserved for:
- Modified sprites (if sprite transformation is implemented)
- Custom user content
- Temporary files
Format: data/users/{userId}/{koboldId}/sprite/ for modified sprites
Frontend Architecture
Screens
- Auth Screen: Login/register
- Main Menu: List saves, new game
- Game Setup: Tribe generation and selection
- Game Screen: Main gameplay with events
- Config Screen: Enable/disable content
- Event Modal: Story display
State Management
currentUser: Logged-in user objectcurrentSave: Current save metadatacurrentTribe: Current tribe with kobolds
Communication
- Fetch API for all server communication
- JSON request/response
- Token in Authorization header
Extensibility Points
New Events
1. Create class extending Event 2. Register in EventManager::registerEventClasses() 3. No database changes needed
New Injuries
1. Add injury type in events 2. Ensure category is in injury type map 3. Optional: add to injuries_enabled table
New Items
1. Create items via API or events 2. Set stat modifications 3. Store in items table
New Stats
1. Add to Kobold::$statNames 2. Ensure database has column (migration needed) 3. All stat systems auto-support new stat
New Age Tiers
1. Modify age tier detection in Kobold::getAgeCategory() 2. Update sprite selection 3. May need new sprites in morphs
Source
| 1 | # Architecture Overview |
| 2 | |
| 3 | ## Database Schema |
| 4 | |
| 5 | ### Users |
| 6 | - `id` (PK) |
| 7 | - `email` (UNIQUE) |
| 8 | - `password_hash` |
| 9 | - `created_at` |
| 10 | |
| 11 | ### Saves |
| 12 | - `id` (PK) |
| 13 | - `user_id` (FK) |
| 14 | - `name` |
| 15 | - `current_month` |
| 16 | - `current_season` |
| 17 | - `created_at` |
| 18 | - `last_played` |
| 19 | |
| 20 | ### Kobolds |
| 21 | - `id` (PK) |
| 22 | - `save_id` (FK) |
| 23 | - `name` |
| 24 | - `age` |
| 25 | - `vitality`, `intelligence`, `medicine`, `crafting`, `personality`, `will` |
| 26 | - `sprite_morph` |
| 27 | - `is_leader` |
| 28 | - `is_alive` |
| 29 | - `expelled` |
| 30 | - `father_id` (FK, self-reference) |
| 31 | - `mother_id` (FK, self-reference) |
| 32 | - `created_at` |
| 33 | |
| 34 | ### Injuries |
| 35 | - `id` (PK) |
| 36 | - `kobold_id` (FK) |
| 37 | - `injury_type` (string) |
| 38 | - `category` (wound, fracture, etc.) |
| 39 | - `severity` (0-10) |
| 40 | - `created_at` |
| 41 | |
| 42 | ### Items |
| 43 | - `id` (PK) |
| 44 | - `save_id` (FK) |
| 45 | - `name` |
| 46 | - `description` |
| 47 | - `item_type` |
| 48 | - `created_at` |
| 49 | |
| 50 | ### Item Modifications |
| 51 | - `id` (PK) |
| 52 | - `item_id` (FK) |
| 53 | - `stat_name` |
| 54 | - `modification` (-5 to +5) |
| 55 | |
| 56 | ### Kobold Items (many-to-many) |
| 57 | - `kobold_id` (FK) |
| 58 | - `item_id` (FK) |
| 59 | |
| 60 | ### Events Enabled |
| 61 | - `id` (PK) |
| 62 | - `save_id` (FK) |
| 63 | - `event_class` |
| 64 | - `enabled` (boolean) |
| 65 | |
| 66 | ### Injuries Enabled |
| 67 | - `id` (PK) |
| 68 | - `save_id` (FK) |
| 69 | - `injury_type` |
| 70 | - `enabled` (boolean) |
| 71 | |
| 72 | ### NPCs |
| 73 | - `id` (PK) |
| 74 | - `save_id` (FK) |
| 75 | - `name` |
| 76 | - `npc_type` (tribe, individual) |
| 77 | - `is_rival` (boolean) |
| 78 | - `data` (JSON for extensibility) |
| 79 | - `created_at` |
| 80 | |
| 81 | ## Class Hierarchy |
| 82 | |
| 83 | ### Core Classes |
| 84 | - `Database`: Singleton for SQLite access |
| 85 | - `User`: User authentication and save management |
| 86 | - `Kobold`: Individual kobold with stats, injuries, items, genetics |
| 87 | - `Tribe`: Collection of kobolds, tribe-level management |
| 88 | - `Item`: Items with stat modifications |
| 89 | - `Injury`: Injury tracking with severity |
| 90 | - `NPC`: Non-player characters/tribes |
| 91 | |
| 92 | ### Event System |
| 93 | - `Event` (abstract): Base class for all events |
| 94 | - `EventManager`: Manages enabled events, executes them |
| 95 | - Event implementations: `HuntingEvent`, `ExplorationEvent`, `FarmingEvent`, etc. |
| 96 | |
| 97 | ## API Flow |
| 98 | |
| 99 | ### Authentication |
| 100 | 1. User registers/logs in via `/api/auth/` |
| 101 | 2. Server returns user object with token |
| 102 | 3. Token stored in localStorage |
| 103 | 4. Token sent with all subsequent requests |
| 104 | |
| 105 | ### Game Creation |
| 106 | 1. User submits tribe name to `/api/game/generation` |
| 107 | 2. Server creates save record |
| 108 | 3. Server generates 20 random kobolds |
| 109 | 4. Returns kobold data to frontend |
| 110 | |
| 111 | ### Game Load |
| 112 | 1. User clicks save to load |
| 113 | 2. Frontend calls `/api/game/load?saveId=X` |
| 114 | 3. Server loads tribe, kobolds, items, injuries |
| 115 | 4. Returns complete game state |
| 116 | |
| 117 | ### Event Execution |
| 118 | 1. User initiates event via `/api/game/event` |
| 119 | 2. Server loads tribe state |
| 120 | 3. Event modifies tribe state |
| 121 | 4. Event returns narrative story |
| 122 | 5. Frontend displays story in modal |
| 123 | |
| 124 | ### Month Progression |
| 125 | 1. User clicks "End Month" |
| 126 | 2. Server increments month/season |
| 127 | 3. Kobolds age |
| 128 | 4. Old-age injuries applied |
| 129 | 5. Random month-progression events occur |
| 130 | 6. Dead kobolds removed |
| 131 | 7. Story returned to frontend |
| 132 | |
| 133 | ## Stat System |
| 134 | |
| 135 | ### Stat Ranges |
| 136 | All stats are 0-100 internally but displayed as text: |
| 137 | - 0-10: terrible |
| 138 | - 10-20: bad |
| 139 | - 20-30: unskilled |
| 140 | - 30-40: decent |
| 141 | - 40-50: good |
| 142 | - 50-60: excellent |
| 143 | - 60-70: fantastic |
| 144 | - 70-80: master |
| 145 | - 80-90: divine |
| 146 | - 90-100: godlike |
| 147 | |
| 148 | ### Stat Checks |
| 149 | 1. Get base stat value |
| 150 | 2. Apply item modifications |
| 151 | 3. Subtract injury severity total |
| 152 | 4. For non-adults, multiply by age progress percentage |
| 153 | 5. Clamp to 0-100 |
| 154 | 6. Roll 1d100 under stat (≤ stat = success) |
| 155 | |
| 156 | ### Age Progression |
| 157 | - Eggs and babies: effective stat = base stat × age progress (0-100%) |
| 158 | - At age 4 (adult): 100% effective stat |
| 159 | - Stats remain at full value until old age |
| 160 | |
| 161 | ## Event Architecture |
| 162 | |
| 163 | Each event: |
| 164 | 1. Receives the current `Tribe` object |
| 165 | 2. Can read tribe state (kobolds, items, storage) |
| 166 | 3. Can modify tribe state |
| 167 | 4. Generates narrative story |
| 168 | 5. Returns story to display |
| 169 | |
| 170 | Example: |
| 171 | ```php |
| 172 | class HuntingEvent extends Event { |
| 173 | public function execute() { |
| 174 | $this->story = "The hunters set out..."; |
| 175 | |
| 176 | // Access tribe |
| 177 | $kobolds = $this->tribe->getAliveKobolds(); |
| 178 | |
| 179 | // Modify state |
| 180 | foreach ($kobolds as $kobold) { |
| 181 | if ($kobold->checkStat('vitality')) { |
| 182 | // Success |
| 183 | } else { |
| 184 | // Fail - maybe injury |
| 185 | $kobold->addInjury('wound', 'wound', 1); |
| 186 | } |
| 187 | } |
| 188 | |
| 189 | $this->story .= "\nThe hunters returned..."; |
| 190 | return $this->story; |
| 191 | } |
| 192 | } |
| 193 | ``` |
| 194 | |
| 195 | ## Storage Structure |
| 196 | |
| 197 | User saves are stored entirely in the SQLite database. Per-user directories in `data/users/` are reserved for: |
| 198 | - Modified sprites (if sprite transformation is implemented) |
| 199 | - Custom user content |
| 200 | - Temporary files |
| 201 | |
| 202 | Format: `data/users/{userId}/{koboldId}/sprite/` for modified sprites |
| 203 | |
| 204 | ## Frontend Architecture |
| 205 | |
| 206 | ### Screens |
| 207 | - Auth Screen: Login/register |
| 208 | - Main Menu: List saves, new game |
| 209 | - Game Setup: Tribe generation and selection |
| 210 | - Game Screen: Main gameplay with events |
| 211 | - Config Screen: Enable/disable content |
| 212 | - Event Modal: Story display |
| 213 | |
| 214 | ### State Management |
| 215 | - `currentUser`: Logged-in user object |
| 216 | - `currentSave`: Current save metadata |
| 217 | - `currentTribe`: Current tribe with kobolds |
| 218 | |
| 219 | ### Communication |
| 220 | - Fetch API for all server communication |
| 221 | - JSON request/response |
| 222 | - Token in Authorization header |
| 223 | |
| 224 | ## Extensibility Points |
| 225 | |
| 226 | ### New Events |
| 227 | 1. Create class extending `Event` |
| 228 | 2. Register in `EventManager::registerEventClasses()` |
| 229 | 3. No database changes needed |
| 230 | |
| 231 | ### New Injuries |
| 232 | 1. Add injury type in events |
| 233 | 2. Ensure category is in injury type map |
| 234 | 3. Optional: add to `injuries_enabled` table |
| 235 | |
| 236 | ### New Items |
| 237 | 1. Create items via API or events |
| 238 | 2. Set stat modifications |
| 239 | 3. Store in items table |
| 240 | |
| 241 | ### New Stats |
| 242 | 1. Add to `Kobold::$statNames` |
| 243 | 2. Ensure database has column (migration needed) |
| 244 | 3. All stat systems auto-support new stat |
| 245 | |
| 246 | ### New Age Tiers |
| 247 | 1. Modify age tier detection in `Kobold::getAgeCategory()` |
| 248 | 2. Update sprite selection |
| 249 | 3. May need new sprites in morphs |