BlueGit

blue-star tribegen

Files

tribegen / web / docs / FOOD_SYSTEM.md

FOOD_SYSTEM.md

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

Food System Implementation

Overview

The food system has been added to TribeGen. Food is stored at the tribe level and consumed each month after random progression events. Kobolds with insufficient food develop the "malnourished" injury, which is automatically cured when they have enough food again.

Storage Location

Food is stored in the saves table as a food_count integer column. This represents the tribe's total food supply, not given to specific kobolds.

Items not given to kobolds are stored separately in the items table (linked to a save but not to a specific kobold via the junction table).

Food Requirements by Age Tier

Each kobold requires a portion of food based on their age:

Age TierFood Required
Egg0.0 (don't eat)
Baby (0-3)0.5 portions
Adult (4-34)1.0 portions
Old (35-59)0.6 portions
Very Old (60+)0.4 portions

These values are configurable in the Tribe class $foodRequirements array.

How Food Consumption Works

On Month Progression

1. Random events occur first (handled by EventManager) 2. Food consumption begins (called from Tribe::endMonth()) 3. Kobolds are fed in priority order:

  • Malnourished kobolds are fed first (highest priority)
  • After that, younger kobolds are fed before older ones

4. Kobolds without food get injured:

  • First starvation: Receive "malnourished" injury (severity 1)
  • Future starvations: Remain malnourished

5. Recovery: When malnourished kobolds have enough food next month, injury is automatically removed

Example Scenario

Tribe has 10 food, 6 kobolds:

  • 1 malnourished baby (0.5 required) - FED FIRST
  • 1 young adult (1.0 required)
  • 2 older adults (1.0 each)
  • 1 old kobold (0.6 required)
  • 1 very old kobold (0.4 required)

Consumption Order: 1. Malnourished baby: 0.5 food consumed (9 left) ✓ Healed 2. Baby adult: 1.0 food consumed (8 left) ✓ 3. First adult: 1.0 food consumed (7 left) ✓ 4. Second adult: 1.0 food consumed (6 left) ✓ 5. Old kobold: 0.6 food consumed (5.4 left) ✓ 6. Very old kobold: 0.4 food consumed (5.0 left) ✓

All fed! No new injuries.

Implementation Details

New Methods in Tribe Class

// Get current food count
$tribe->getFoodCount()

// Add food to storage
$tribe->addFood($amount)

// Remove food from storage
$tribe->removeFood($amount)

// Calculate total food needed for all alive kobolds
$tribe->calculateFoodNeeded()

// Get food requirement for specific kobold
$tribe->getFoodRequirement($kobold)

// Consume food at end of month (returns story)
$foodStory = $tribe->consumeFood()

// Get end-of-month food and aging story
$tribe->endMonth() // Now returns combined story

Malnourished Injury

  • Category: malnourished
  • Cure: Automatic when food available (not by medicine)
  • Severity: 1 (contributes to total injury severity for death calculation)
  • Behavior:
  • Added when kobold can't be fed
  • Removed automatically next month if fed

Database Changes

Table: saves - Added column:

food_count INTEGER DEFAULT 0

Food Requirement Configuration

Modify in Tribe class constructor:

private $foodRequirements = [
    'egg' => 0,        // Current: 0
    'baby' => 0.5,     // Current: 0.5
    'adult' => 1.0,    // Current: 1.0
    'old' => 0.6,      // Current: 0.6
    'very_old' => 0.4  // Current: 0.4
];

Integration Points

From Events

Events can add food to the tribe during play:

// In an event
$tribe->addFood(5); // Add 5 food portions from successful hunt

$story = "The hunting party returned with 5 portions of food!\n";
$this->tribe->addFood(5);
return $story;

From API

The endMonth API endpoint will include food consumption story:

// In src/api/game.php endMonth endpoint
$foodStory = $tribe->endMonth();

// Include in response narrative
$monthStory = $foodStory . "\n\n" . $otherEvents;

Displaying Food Count

Frontend can show food in game screen:

// In app.js when rendering game
const food = data.tribe.foodCount;
document.getElementById('foodDisplay').textContent = food;

Special Cases

Eggs

  • Don't require food (food requirement = 0)
  • Won't get malnourished injuries
  • Can't die from starvation

Babies Transitioning to Adult

  • At age 4, requirement increases from 0.5 to 1.0 portions
  • If food is tight, newly adult kobolds might go hungry their first adult month

Death by Starvation

  • Starvation indirectly causes death through repeated malnourished injuries
  • A kobold with malnourished injury (severity 1) + other injuries might reach vitality threshold
  • Or repeated starvation months could stack multiple injuries

Events and Food

Hunting Event Example

class HuntingEvent extends Event {
    public function execute() {
        $this->story = "The hunting party set out...\n\n";
        
        $success = 0;
        foreach ($this->tribe->getAliveKobolds() as $kobold) {
            if ($kobold->checkStat('fighting')) { // Actually hunting skill
                $success++;
            }
        }
        
        // 0-3 food based on hunters
        $foodFound = max(0, $success - 1);
        
        if ($foodFound > 0) {
            $this->tribe->addFood($foodFound);
            $this->story .= "The hunters returned with {$foodFound} portions of food!";
        } else {
            $this->story .= "The hunt was unsuccessful.";
        }
        
        return $this->story;
    }
}

Farming Event Example

class FarmingEvent extends Event {
    public function execute() {
        $this->story = "The farmers worked the fields...\n\n";
        
        $totalCrafting = 0;
        foreach ($this->tribe->getAliveKobolds() as $kobold) {
            $totalCrafting += $kobold->getStat('crafting');
        }
        
        // Average crafting skill determines harvest
        $avgCrafting = $totalCrafting / max(1, count($this->tribe->getAliveKobolds()));
        $harvest = (int)($avgCrafting / 20); // Scale to 0-5
        
        if ($harvest > 0) {
            $this->tribe->addFood($harvest);
            $this->story .= "The fields yielded {$harvest} portions of food!";
        } else {
            $this->story .= "The crops failed this season.";
        }
        
        return $this->story;
    }
}

Testing

Manual Test

1. Create a tribe with 6 kobolds 2. Give it 5 food (6 × 1.0 = 6 needed) 3. End the month 4. One kobold should get malnourished injury 5. Next month, add more food 6. Malnourished kobold should recover

Test Prioritization

1. Create malnourished baby and normal adults 2. Set food to exactly 0.5 portions 3. End month 4. Baby should be fed, adult should be malnourished 5. Verify story says baby was healed

Configuration & Customization

Adjusting Food Requirements

In src/Classes/Tribe.php, change the $foodRequirements array:

private $foodRequirements = [
    'egg' => 0,
    'baby' => 0.3,    // Babies eat less
    'adult' => 1.5,   // Adults eat more
    'old' => 0.8,     // Old eat more
    'very_old' => 0.6
];

Adjusting Starvation Severity

In Tribe::consumeFood(), change the injury severity:

// Currently severity 1
$kobold->addInjury('malnourished', 'malnourished', 1);

// Could be 2 for more serious
$kobold->addInjury('malnourished', 'malnourished', 2);

Seasonal Food Modifiers

Could be added to events:

// In farming event, modify based on season
$harvest = ...;
if ($season === 'summer') {
    $harvest *= 1.5; // Better harvest in summer
} elseif ($season === 'winter') {
    $harvest *= 0.5; // Poor harvest in winter
}

Files Modified

  • src/Classes/Tribe.php - Added food system methods
  • src/Database/Database.php - Added food_count to saves table
  • src/Classes/Injury.php - Added malnourished to cure map
  • src/Utilities/GameHelper.php - Added malnourished to injury helper

Summary

The food system is now fully integrated:

  • ✅ Stored at tribe level (in saves.food_count)
  • ✅ Consumed each month after random events
  • ✅ Prioritizes malnourished, then younger kobolds
  • ✅ Automatically applies and removes malnourished injury
  • ✅ Events can add food (via hunting, farming, etc.)
  • ✅ Ready for configuration and balance tuning
Source
1# Food System Implementation
2
3## Overview
4
5The food system has been added to TribeGen. Food is stored at the tribe level and consumed each month after random progression events. Kobolds with insufficient food develop the "malnourished" injury, which is automatically cured when they have enough food again.
6
7## Storage Location
8
9**Food is stored in the `saves` table** as a `food_count` integer column. This represents the tribe's total food supply, not given to specific kobolds.
10
11Items not given to kobolds are stored separately in the `items` table (linked to a save but not to a specific kobold via the junction table).
12
13## Food Requirements by Age Tier
14
15Each kobold requires a portion of food based on their age:
16
17| Age Tier | Food Required |
18|----------|---------------|
19| Egg | 0.0 (don't eat) |
20| Baby (0-3) | 0.5 portions |
21| Adult (4-34) | 1.0 portions |
22| Old (35-59) | 0.6 portions |
23| Very Old (60+) | 0.4 portions |
24
25These values are configurable in the `Tribe` class `$foodRequirements` array.
26
27## How Food Consumption Works
28
29### On Month Progression
30
311. **Random events occur first** (handled by EventManager)
322. **Food consumption begins** (called from `Tribe::endMonth()`)
333. **Kobolds are fed in priority order**:
34 - Malnourished kobolds are fed **first** (highest priority)
35 - After that, **younger kobolds are fed before older ones**
364. **Kobolds without food get injured**:
37 - First starvation: Receive "malnourished" injury (severity 1)
38 - Future starvations: Remain malnourished
395. **Recovery**: When malnourished kobolds have enough food next month, injury is automatically removed
40
41### Example Scenario
42
43Tribe has 10 food, 6 kobolds:
44- 1 malnourished baby (0.5 required) - **FED FIRST**
45- 1 young adult (1.0 required)
46- 2 older adults (1.0 each)
47- 1 old kobold (0.6 required)
48- 1 very old kobold (0.4 required)
49
50**Consumption Order:**
511. Malnourished baby: 0.5 food consumed (9 left) ✓ Healed
522. Baby adult: 1.0 food consumed (8 left) ✓
533. First adult: 1.0 food consumed (7 left) ✓
544. Second adult: 1.0 food consumed (6 left) ✓
555. Old kobold: 0.6 food consumed (5.4 left) ✓
566. Very old kobold: 0.4 food consumed (5.0 left) ✓
57
58All fed! No new injuries.
59
60## Implementation Details
61
62### New Methods in `Tribe` Class
63
64```php
65// Get current food count
66$tribe->getFoodCount()
67
68// Add food to storage
69$tribe->addFood($amount)
70
71// Remove food from storage
72$tribe->removeFood($amount)
73
74// Calculate total food needed for all alive kobolds
75$tribe->calculateFoodNeeded()
76
77// Get food requirement for specific kobold
78$tribe->getFoodRequirement($kobold)
79
80// Consume food at end of month (returns story)
81$foodStory = $tribe->consumeFood()
82
83// Get end-of-month food and aging story
84$tribe->endMonth() // Now returns combined story
85```
86
87### Malnourished Injury
88
89- **Category**: `malnourished`
90- **Cure**: Automatic when food available (not by medicine)
91- **Severity**: 1 (contributes to total injury severity for death calculation)
92- **Behavior**:
93 - Added when kobold can't be fed
94 - Removed automatically next month if fed
95
96### Database Changes
97
98**Table: `saves`** - Added column:
99```sql
100food_count INTEGER DEFAULT 0
101```
102
103### Food Requirement Configuration
104
105Modify in `Tribe` class constructor:
106
107```php
108private $foodRequirements = [
109 'egg' => 0, // Current: 0
110 'baby' => 0.5, // Current: 0.5
111 'adult' => 1.0, // Current: 1.0
112 'old' => 0.6, // Current: 0.6
113 'very_old' => 0.4 // Current: 0.4
114];
115```
116
117## Integration Points
118
119### From Events
120
121Events can add food to the tribe during play:
122
123```php
124// In an event
125$tribe->addFood(5); // Add 5 food portions from successful hunt
126
127$story = "The hunting party returned with 5 portions of food!\n";
128$this->tribe->addFood(5);
129return $story;
130```
131
132### From API
133
134The `endMonth` API endpoint will include food consumption story:
135
136```php
137// In src/api/game.php endMonth endpoint
138$foodStory = $tribe->endMonth();
139
140// Include in response narrative
141$monthStory = $foodStory . "\n\n" . $otherEvents;
142```
143
144### Displaying Food Count
145
146Frontend can show food in game screen:
147
148```javascript
149// In app.js when rendering game
150const food = data.tribe.foodCount;
151document.getElementById('foodDisplay').textContent = food;
152```
153
154## Special Cases
155
156### Eggs
157- Don't require food (food requirement = 0)
158- Won't get malnourished injuries
159- Can't die from starvation
160
161### Babies Transitioning to Adult
162- At age 4, requirement increases from 0.5 to 1.0 portions
163- If food is tight, newly adult kobolds might go hungry their first adult month
164
165### Death by Starvation
166- Starvation indirectly causes death through repeated malnourished injuries
167- A kobold with malnourished injury (severity 1) + other injuries might reach vitality threshold
168- Or repeated starvation months could stack multiple injuries
169
170## Events and Food
171
172### Hunting Event Example
173
174```php
175class HuntingEvent extends Event {
176 public function execute() {
177 $this->story = "The hunting party set out...\n\n";
178
179 $success = 0;
180 foreach ($this->tribe->getAliveKobolds() as $kobold) {
181 if ($kobold->checkStat('fighting')) { // Actually hunting skill
182 $success++;
183 }
184 }
185
186 // 0-3 food based on hunters
187 $foodFound = max(0, $success - 1);
188
189 if ($foodFound > 0) {
190 $this->tribe->addFood($foodFound);
191 $this->story .= "The hunters returned with {$foodFound} portions of food!";
192 } else {
193 $this->story .= "The hunt was unsuccessful.";
194 }
195
196 return $this->story;
197 }
198}
199```
200
201### Farming Event Example
202
203```php
204class FarmingEvent extends Event {
205 public function execute() {
206 $this->story = "The farmers worked the fields...\n\n";
207
208 $totalCrafting = 0;
209 foreach ($this->tribe->getAliveKobolds() as $kobold) {
210 $totalCrafting += $kobold->getStat('crafting');
211 }
212
213 // Average crafting skill determines harvest
214 $avgCrafting = $totalCrafting / max(1, count($this->tribe->getAliveKobolds()));
215 $harvest = (int)($avgCrafting / 20); // Scale to 0-5
216
217 if ($harvest > 0) {
218 $this->tribe->addFood($harvest);
219 $this->story .= "The fields yielded {$harvest} portions of food!";
220 } else {
221 $this->story .= "The crops failed this season.";
222 }
223
224 return $this->story;
225 }
226}
227```
228
229## Testing
230
231### Manual Test
232
2331. Create a tribe with 6 kobolds
2342. Give it 5 food (6 × 1.0 = 6 needed)
2353. End the month
2364. One kobold should get malnourished injury
2375. Next month, add more food
2386. Malnourished kobold should recover
239
240### Test Prioritization
241
2421. Create malnourished baby and normal adults
2432. Set food to exactly 0.5 portions
2443. End month
2454. Baby should be fed, adult should be malnourished
2465. Verify story says baby was healed
247
248## Configuration & Customization
249
250### Adjusting Food Requirements
251
252In `src/Classes/Tribe.php`, change the `$foodRequirements` array:
253
254```php
255private $foodRequirements = [
256 'egg' => 0,
257 'baby' => 0.3, // Babies eat less
258 'adult' => 1.5, // Adults eat more
259 'old' => 0.8, // Old eat more
260 'very_old' => 0.6
261];
262```
263
264### Adjusting Starvation Severity
265
266In `Tribe::consumeFood()`, change the injury severity:
267
268```php
269// Currently severity 1
270$kobold->addInjury('malnourished', 'malnourished', 1);
271
272// Could be 2 for more serious
273$kobold->addInjury('malnourished', 'malnourished', 2);
274```
275
276### Seasonal Food Modifiers
277
278Could be added to events:
279
280```php
281// In farming event, modify based on season
282$harvest = ...;
283if ($season === 'summer') {
284 $harvest *= 1.5; // Better harvest in summer
285} elseif ($season === 'winter') {
286 $harvest *= 0.5; // Poor harvest in winter
287}
288```
289
290## Files Modified
291
292- `src/Classes/Tribe.php` - Added food system methods
293- `src/Database/Database.php` - Added `food_count` to `saves` table
294- `src/Classes/Injury.php` - Added malnourished to cure map
295- `src/Utilities/GameHelper.php` - Added malnourished to injury helper
296
297## Summary
298
299The food system is now fully integrated:
300- ✅ Stored at tribe level (in `saves.food_count`)
301- ✅ Consumed each month after random events
302- ✅ Prioritizes malnourished, then younger kobolds
303- ✅ Automatically applies and removes malnourished injury
304- ✅ Events can add food (via hunting, farming, etc.)
305- ✅ Ready for configuration and balance tuning