BlueGit

blue-star tribegen

Files

tribegen / web / docs / ARCHITECTURE.md

ARCHITECTURE.md

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

Architecture Overview

Database Schema

Users

  • id (PK)
  • email (UNIQUE)
  • password_hash
  • created_at

Saves

  • id (PK)
  • user_id (FK)
  • name
  • current_month
  • current_season
  • created_at
  • last_played

Kobolds

  • id (PK)
  • save_id (FK)
  • name
  • age
  • vitality, intelligence, medicine, crafting, personality, will
  • sprite_morph
  • is_leader
  • is_alive
  • expelled
  • father_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)
  • name
  • description
  • item_type
  • created_at

Item Modifications

  • id (PK)
  • item_id (FK)
  • stat_name
  • modification (-5 to +5)

Kobold Items (many-to-many)

  • kobold_id (FK)
  • item_id (FK)

Events Enabled

  • id (PK)
  • save_id (FK)
  • event_class
  • enabled (boolean)

Injuries Enabled

  • id (PK)
  • save_id (FK)
  • injury_type
  • enabled (boolean)

NPCs

  • id (PK)
  • save_id (FK)
  • name
  • npc_type (tribe, individual)
  • is_rival (boolean)
  • data (JSON for extensibility)
  • created_at

Class Hierarchy

Core Classes

  • Database: Singleton for SQLite access
  • User: User authentication and save management
  • Kobold: Individual kobold with stats, injuries, items, genetics
  • Tribe: Collection of kobolds, tribe-level management
  • Item: Items with stat modifications
  • Injury: Injury tracking with severity
  • NPC: Non-player characters/tribes

Event System

  • Event (abstract): Base class for all events
  • EventManager: 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 object
  • currentSave: Current save metadata
  • currentTribe: 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
1001. User registers/logs in via `/api/auth/`
1012. Server returns user object with token
1023. Token stored in localStorage
1034. Token sent with all subsequent requests
104
105### Game Creation
1061. User submits tribe name to `/api/game/generation`
1072. Server creates save record
1083. Server generates 20 random kobolds
1094. Returns kobold data to frontend
110
111### Game Load
1121. User clicks save to load
1132. Frontend calls `/api/game/load?saveId=X`
1143. Server loads tribe, kobolds, items, injuries
1154. Returns complete game state
116
117### Event Execution
1181. User initiates event via `/api/game/event`
1192. Server loads tribe state
1203. Event modifies tribe state
1214. Event returns narrative story
1225. Frontend displays story in modal
123
124### Month Progression
1251. User clicks "End Month"
1262. Server increments month/season
1273. Kobolds age
1284. Old-age injuries applied
1295. Random month-progression events occur
1306. Dead kobolds removed
1317. Story returned to frontend
132
133## Stat System
134
135### Stat Ranges
136All 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
1491. Get base stat value
1502. Apply item modifications
1513. Subtract injury severity total
1524. For non-adults, multiply by age progress percentage
1535. Clamp to 0-100
1546. 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
163Each event:
1641. Receives the current `Tribe` object
1652. Can read tribe state (kobolds, items, storage)
1663. Can modify tribe state
1674. Generates narrative story
1685. Returns story to display
169
170Example:
171```php
172class 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
197User 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
202Format: `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
2271. Create class extending `Event`
2282. Register in `EventManager::registerEventClasses()`
2293. No database changes needed
230
231### New Injuries
2321. Add injury type in events
2332. Ensure category is in injury type map
2343. Optional: add to `injuries_enabled` table
235
236### New Items
2371. Create items via API or events
2382. Set stat modifications
2393. Store in items table
240
241### New Stats
2421. Add to `Kobold::$statNames`
2432. Ensure database has column (migration needed)
2443. All stat systems auto-support new stat
245
246### New Age Tiers
2471. Modify age tier detection in `Kobold::getAgeCategory()`
2482. Update sprite selection
2493. May need new sprites in morphs