Release 0.0.1.8.8.7

This commit is contained in:
WorldBosse committed 2026-10-29 21:59:06 +04:00
1 parent 3c8a17aa78
commit c7beab414c
16283 files changed
+768761 -2

No files matched your search

@@ -0,0 +1,421 @@
# R4 Raids on a base (night raids, wall and door damage)
Board item R4 (owner, 2026-10-06). Research only: no mod or game file was changed. Every number is
PROPOSED with one recommendation; the owner settles them (section 10) before building.
Short forms: `F/` = `LonaRPG/Data/Scripts/Frames/`, `E/` = `LonaRPG/Data/Scripts/Editables/`,
`HCG/` = `LonaRPG/Data/HCGframes/`, `NPC/` = `LonaRPG/Data/NPCdata/`, `LC/` = `ModScripts/_Mods/LonaCraft/Scripts/`,
`CS/` = `ModScripts/_Mods/Campsites/Scripts/`, `RPS/` = `ModScripts/_Mods/RolePlayS/Scripts/`.
`LC/110_Bases.rb` line numbers are as of 2026-10-06 17:11 (another executor is editing that file).
Frame counts are at 60 fps (`F/102_00_Scene_Map.rb:97-104`; the fast-forward key runs 120 fps, so
timers kept in frames stay fair).
Dry run and render: `scratchpad/r3/r4_raid_plan.py` -> `scratchpad/r3/r4_raid_plan.png` (Map028,
the B2 sample base, a BanditMobs 0-25 group planned with the numbers below).
## 0. Summary
| Question | Finding | PROPOSED |
|---|---|---|
| Trigger | Every field map's NapEvent calls `region_map_wildness_nap`; the game rolls `WildDangerous` and, after the nap, its BIOS spawns the group on the outer regions (2.1) | Keep the game's roll (about 28 % a nap at steady state), plus a base-value bonus; scenario table per overmap region on base maps; every raid is a night raid |
| Spawn | Spawns read `$game_map.region_map`, already pruned of built and inside tiles by B2/R8a | Spawn tiles at least 8 tiles from the base; half the group on the side of the door nearest Lona; +1 raider per 30 base value (max +4, cap 12) |
| Can an NPC hit a wall or door with the game's skills? | No. A palisade tile and a closed door carry terrain tag 4: a skill's hit line ending on a tag-4 tile is blocked and its damage factor is `1 - 4 x 0.25 = 0` (3.1) | The mod keeps an HP table per piece and applies the damage itself when a raider swings at it (option B) |
| What does an NPC do with no path? | Greedy step, then a 25-ring BFS from the target, then random steps; it never targets an object by itself (3.1) | Siege AI: while Lona is enclosed, raiders are driven by the mod to stand tiles next to walls/doors and swing |
| HP | none in the game | Palisade 600 HP / armour 3, door 300 / 3, A4 wall (phase 2) 1200 / 8; a bandit spear breaks a door in 22 s, a palisade in 44 s; weak mobs and wolves cannot get in |
| Break | | piece removed from the record, tiles repainted, no refund, no rubble; the base never reverts during a raid |
| Repair | | action key: Repair, 1 Plank = +150 HP, 120 frames, not while that piece was hit in the last 3 s |
| End | | all raiders down, or 180 s of siege without a breach (they retreat), or Lona leaves the map; no nap during a raid |
| Build | | 4 items, about 730 Ruby lines, new `LC/120_Raids.rb` + `Config/Bases.json` |
## 1. What the game does today
### 1.1 The nap and the nap group
| Step | Evidence |
|---|---|
| Nap command: refused while `$game_map.threat`, else the map's nap event | `HCG/Command_Nap.rb:2`, `:9`; `F/31_Game_Map.rb:1300-1309` |
| `threat` = an NPC that tracks Lona within 8 tiles (recomputed every `NON_THREATEN_COUNT` frames); a raider hitting a wall is NOT a threat | `F/31_Game_Map.rb:951-968` |
| Every field map's NapEvent ends in `region_map_wildness_nap` (Map028 ev 32, Map045 ev 4, Map047 ev 4, Map030, Map107) | event dumps (`tools/home_evdump.py`) |
| `region_map_wildness_nap`: if a nap group from the last roll still lives (`check_enemy_survival?`) -> `RapeLoop` -> capture or death branch by race; else roll and `handleNap` | `E/34_Functions_RegionMap.rb:1645-1846`, capture branches `:1657-1828`, roll `:1832-1833` |
| Roll: `WildDangerous += clamp(rand(10) + WorldDifficulty/2 - survival*2, 10, 50)`; group if `WildDangerous >= rand(100) + survival`; group picked from a weighted list by the OVERMAP region (`OnRegionMap_Regid`) | `E/34_Functions_RegionMap.rb:237-246`, list `:248-337`, pick `:339-359`; `E/100_Game_Player_handle_on_move.rb:109` |
| `handleNap`: time shifts one segment (day <-> night, 2 segments a day), map set up again, non-`nappable` events deleted, map events re-initialised | `F/Game_InterpreterModifies/Game_Interpreter_Modifies_OM.rb:11-47`; `E/70_Game_Map_DayNightAndOvermap.rb:13-14`; `F/123_Game_Date.rb:198-201`, `:304-310`; `F/31_Game_Map.rb:165`, `:206`, `:359-372`; `F/39_Game_Event.rb:1957-1964` |
| The re-run BIOS (Map028 ev 1) sets the outer / inner spawn regions (`[4,9,10,11,12]` / `[3]`) and calls `region_map_wildness_spawn`, which reserves the group on `region_map[outer].sample` tiles and sets `RapeLoop = 1` | Map028 ev 1; `E/34_Functions_RegionMap.rb:361-1115`, `:1114`; `F/31_Game_Map.rb:1243-1246` |
| Group NPCs: `@nappable = false`, `summon_data[:WildnessNapEvent] = race`; `wildSpawnEnemy_setup` returns early after a nap (OverMapEvent_name 0), so they keep move type 1 (random walk) until they sense Lona | Map001 ev 384 (MobHumanRogueSpear); `F/39_Game_Event.rb:2351-2361` |
| On waking with a group alive: message `WildnessNapSpawn`; napping again with them alive = captured or killed | `E/34_Functions_RegionMap.rb:1844`, `:1647-1660` |
| So today walls do NOT protect a sleeping Lona: the second nap captures her whatever stands between | `:1848-1866` counts living group NPCs only |
Game quirks in the list: region 2 matches `when 2` (`:258`) before `when 2,3,6,14` (`:305`); regions 13
(Swamp Trail) and 16 (Infested Creep) fall to `else` (bandits and guards, `:329-335`).
### 1.2 Nap groups (difficulty 0-25 / 75+; `WorldDifficulty` bands), counted from `:361-1115`
| Group | Units 0-25 | Units 75+ | Can break a palisade (3.4)? |
|---|---|---|---|
| Orkind | 4 RandomGoblin | 5 Goblin, 1 Hobgoblin, 1 Orc | yes, slowly (goblins), fast (orc) |
| OrkindPlayGround | 3 Goblin, 2 Hobgoblin, 1 Orc | 4 Hobgoblin, 3 Orc, Butcher, Shaman | yes |
| Fishkind | 2 Charger, 2 Commoner | + 2 Spear, 2 Fat | yes |
| FishPPL | Deepone spear, bow, watcher | 7 | yes |
| BanditMobs | 3 RogueSpear, 2 RogueScout | 8 incl. warriors | yes |
| CommonMobs | 3 Commoner, Moot, PickAxe | 9 | no (atk 0-2) |
| UndeadWalking | 3 Commoner, 3 Sickle, Elite warrior, Elite spear | 14 | elites only |
| WolfGroup | 1 DireWolf | 1 | no (animal) |
| AbomManager / AbomSpider | 5 | 10 | yes |
| HumanGuard / NobleGuards | 4 | 7-8 | (not in base raids, 2.3) |
### 1.3 NPC AI facts that decide the design
| Fact | Evidence |
|---|---|
| An NPC picks targets only through its sensors; `sense_target` scans all characters, `process_target` needs `target.actor` | `F/281_Game_NonPlayerCharacter.rb:417-468`, `:550-570` |
| Map sensors ignore objects (`ignore_object? true`), so no NPC ever targets a `Game_DestroyableObject` on its own | `F/Modules/Sensors.rb:14`, `:97-109` |
| Sight: a line to the target; any tile with terrain tag 4 on it blocks (sight hp -1), tags 1-3 subtract | `F/Modules/Sensors.rb:161-172` |
| The palisade tile and a closed door have tag 4 (event tag overrides the tile's) | `docs/RESEARCH_BASE_BUILDING.md` 2.2; `F/31_Game_Map.rb:858-876`; door tag `LC/110_Bases.rb:890-895` |
| Skill hits: `hit_detection.scan` with a Battle_Sensor (hits objects, no friend check) but the same sight line, sight hp 10 | `F/Modules/BattleSystem.rb:382`; `F/Modules/Sensors_Battle.rb:12-13`; `E/301_Skill_RangeMap.rb:77-80` |
| Damage factor of the target's own tile: `max(1 - tag x 0.25, 0)` -> 0 on a tag-4 tile; RolePlayS keeps the same factor | `F/Modules/BattleSystem.rb:517-519`; `RPS/160_BattleSystem.rb:79`, `:250` |
| An NPC launches a skill only if its target is in range by the same sensor (`target_in_range?`), unless forced (`launch_skill(skill, true)`) | `F/Modules/BattleSystem.rb:58-69`, `:149-157` |
| Projectiles stop on tag >= 4 tiles | `F/33_Game_CharacterBase.rb:224-230` |
| Chasing: `move_toward_TargetSmartAI` = greedy step; on failure `createPath(target, 25)` (BFS from the target, 25 rings), follow it for `move_speed x 2` steps, then random steps | `F/39_Game_Event.rb:1211-1232`; `F/202_pathfinding.rb:330-418`; greedy `F/34_1_Game_Character.rb:258-280`; charge AIs `E/4000_Npc_Charge.rb:5-19`, `E/4000_Npc_OrkindCharge.rb:5-19` |
| With Lona enclosed the BFS floods only the inside and fails, so chasers jitter at the wall nearest her | same |
| Pathfinding passability: tiles (`check_passage`) and the first event on a tile (non-through, same-as-characters priority blocks) | `F/202_pathfinding.rb:470-482`; the last live `find_path` definition wins (`:484-518`; `:49-319` and `:535-604` are commented out) |
| `find_path` allocates a width x height array per call (Map028: 100 x 100 = 10,000 cells) | `F/202_pathfinding.rb:485` |
| "Go and look": `anomally = FakeTarget(x, y)` + alert 1 makes an NPC walk there with the SmartAI path | `E/480_EventCharacterBatch.rb:880-902`; `F/39_Game_Event.rb:1359-1388` |
| NPCs never use action-button events: only the player starts a door | `F/35_Game_Player.rb:604-614` |
| Doors: `doorEV_setup` swaps pages (open = through, closed = solid + tag 4), refuses to close on a living NPC | `E/29_Functions_417_Interpreter.rb:943-961` |
### 1.4 Breakable things in the game (none is a wall or a door)
| Object | How | Evidence |
|---|---|---|
| AbomWall0-3 / RandomAbomWall | event with `set_npc("NeutralHp1Sandbag")`: `Game_DestroyableObject`, health 1, def 200, fraction 9; the player breaks it | Map001 ev 606-618; `NPC/NeutralHp1Sandbag.json` |
| GobWatchTower | `NpcProtectTower`, health set to 4; collapse animation on death | Map001 ev 980; `NPC/NpcProtectTower.json` |
| SandBag, SandBagArmored, NeutralSandbagImmortal | training dummies (`Game_DestroyableObject` / `Game_SandboxObject`) | `NPC/SandBag.json`; `E/4000_Game_SandboxObject.rb`; `RPS/160_BattleSystem.rb:240-279` |
| AbomHiveHeart + AbomHiveHitBox | hit box event linked to its master (`hit_LinkToMaster`) | Map001 ev 564, 566 |
| AbomCreatureCocoon, Bomb_* , NeutralBBQ_rack, WildAnimalRattus | traps / destroyable objects | `NPC/*.json` (`ai` field) |
| MapBlockBox | invisible blocker, no HP | Map001 ev 230 |
| `Game_DestroyableObject` | NPC class with HP that never senses, never aggroes | `F/282_Game_DestroyableObject.rb:6-53` |
No siege, gate or barricade code exists (`grep -i "siege|barricade"` over `HCG/` and `Data/Scripts`: none).
### 1.5 Raid-like prior art
| What | How | Evidence |
|---|---|---|
| Campsites raid roll | per nap, `rand(100) < chance` by biome (5-35 %, default 15), sums one raid event at Lona's tile; the raid events file is missing | `CS/10_Campsites.rb:227-236`, hook `:305-316`; `Campsites/mod.cfg` BIOME_RAID_CHANCE |
| Mercenary camp raid waves (story) | wave NPCs `moveto` named invasion points (`InvadePTT/D/L/R`), move type 3 | `HCG/event/NFL_MerCamp_RaidWave3.rb:12-31` |
| rfuCAMP / OrkVsFish on Map002 | overmap encounters (refugee camp; orc vs fish fight on a tag map), not attacks on a structure | Map002 ev 20, 25; `HCG/encounter/OnMap_OrkVsFish.rb` |
| Abandoned House nap | capture by BanditMobs if a nap group lives | `HCG/event/AbanHouse1_Nap.rb:1-21` |
## 2. Trigger (PROPOSED)
### 2.1 Hooks (all in `GIM_ADDON`, `E/34_Functions_RegionMap.rb:51-1949`)
| Hook | What it does on a base map (`Bases.base_at_map?`) |
|---|---|
| alias `region_map_wildness_nap_stats` (`:237`) | adds the base-value danger bonus to `WildDangerous`, then the original roll |
| alias `region_map_wildness_nap_stats_create_race_list` (`:248`) | returns the scenario list (2.3) instead of the region list |
| alias `region_map_wildness_spawn` (`:361`) | original spawn, then marks a raid pending (race, base id) and reserves the extra raiders (3.2) |
| alias `region_map_wildness_nap` (`:1645`) | refuses the nap while a raid is active (buzzer + text), else original |
| alias `Game_Map#nap` (`E/70_Game_Map_DayNightAndOvermap.rb:13`) | skips the one `$game_date.shift` when a raid is pending and the nap would end in the day (2.2) |
Outside bases nothing changes.
### 2.2 Chance and time
| Option | For | Against |
|---|---|---|
| A. Game roll + base bonus (PROPOSED) | ties into WorldDifficulty and survival; clearing a raid lowers danger (-50, `:1859-1864`) | |
| B. Own roll per nap (Campsites style, flat % by biome) | simple to read | a second danger system beside the game's |
Base value = walls x 1 + doors x 2 + furniture pieces x 3 (floors 0). Bonus per nap = min(10, value / 10).
Simulated chance of a raid on nap 1..6 (40,000 runs, raid cleared = -50):
| WorldDifficulty / survival | bonus 0 (no base) | bonus 3 (value 30) | bonus 10 (value 100+) |
|---|---|---|---|
| 10 / 3 | 8 17 24 27 27 27 % | 11 23 30 32 32 32 % | 18 34 41 43 45 44 % |
| 30 / 5 | 7 17 24 28 28 28 % | 10 22 30 32 33 33 % | 17 34 42 44 46 46 % |
| 60 / 10 | 5 19 28 31 31 32 % | 9 24 34 35 37 39 % | 16 36 44 48 49 50 % |
Night: every raid happens at night (owner: "night raids"). Napping by day ends at night anyway; napping at
night with a raid rolled skips the time shift once, so Lona is woken in the same night. Nap effects
(`process_nap_change`) still apply, as in the game's own nap-spawn. Recommendation: **A, night always**.
### 2.3 Scenarios (by the base record's overmap `region`; `LC/110_Bases.rb` record 9.1)
| Scenario | Regions | Group weights (PROPOSED) | Flavour |
|---|---|---|---|
| Open field | 1 | Orkind 70, BanditMobs 30, UndeadWalking 20, WolfGroup 20 | from all sides; grace 8 s |
| Road | 11, 17, 23 | BanditMobs 60, Orkind 20, CommonMobs 20 | bandits; door bias 0.7 |
| Forest, mountain | 4, 5, 7 | Orkind 70, BanditMobs 20, UndeadWalking 30, WolfGroup 40 | ambush: grace 5 s |
| Shore | 2, 27 | Orkind 50, BanditMobs 40, FishPPL 20 | |
| Swamp, marsh | 8, 13, 15, 24, 25, 26 | Fishkind 70, Orkind 30, UndeadWalking 20 | |
| Wasteland, infested ("desert") | 3, 6, 14, 16, 19, 28 | AbomManager 40, AbomSpider 30, Orkind 30 | abominations: breach x 1.25 |
| Abandoned House | 9 | BanditMobs 60, CommonMobs 30, Orkind 10 | squatters; door bias 0.8 |
HumanGuard and NobleGuards are left out (guards do not siege a camp; in the game they only arrest a
Lona with morality < 30, `:1688-1704`). WolfGroup and CommonMobs stay in on purpose: a closed base
beats them (3.4), which is the reward for building. Recommendation: **this table**, editable in config.
### 2.4 Warning
| Point | PROPOSED |
|---|---|
| Wake-up | instead of `WildnessNapSpawn`: popup "Something is moving outside..." + the race's spot sound (`SndLib.sound_goblin_spot`, `FishkindSmSpot`, `dogSpot`, as `HCG/encounter/OnMap_OrkVsFish.rb:1`, `E/34_Functions_RegionMap.rb:1782`) |
| Grace | raiders hold their spawn tiles (move type 0) for 8 s = 480 frames (scenario value), so Lona can close doors, repair, arm |
| Dog companion (`NPC/CompDoggy.json`, follower record names in `E/99_Game_Player_follower.rb:491-510`) | barks first (`SndLib.dogSpot`), grace +5 s |
## 3. Spawn and attacker AI (PROPOSED)
### 3.1 Why the game's combat cannot break a wall
| Way | Blocked by |
|---|---|
| NPC targets a wall-HP event by itself | map sensors ignore objects (`Sensors.rb:14`, `:104-109`) |
| NPC skill hits an event standing on a palisade tile | the hit line ends on a tag-4 tile -> blocked (`Sensors.rb:168`) and the damage factor is 0 (`BattleSystem.rb:517-519`) |
| Set that event's terrain tag to 0 so it can be hit | the wall then stops blocking sight and missiles (`F/31_Game_Map.rb:858-876` takes the event's tag first) |
| Closed door event | same: its tag is 4 |
### 3.2 Spawn
| Point | PROPOSED | Dry run (Map028, B2 sample base) |
|---|---|---|
| Where | the game's own spawn (outer spawn regions, already without built and inside tiles, `LC/110_Bases.rb:1067-1091`, `:1109-1178`), then each raider is moved (`moveto`) to a tile at least 8 tiles from the base's bounding box | 402 outer tiles, 230 at >= 8 |
| Door side | DOOR_BIAS 0.5 of the raiders on tiles on the side of the door nearest Lona (dot product with base centre -> door) | 188 tiles |
| Size | the group as the game makes it, +1 raider (copy of the group's first unit) per 30 base value, at most +4, at most 12 raiders in all (the game's biggest group is 14, UndeadWalking 75+) | value 34 -> +1 |
| Marking | `summon_data[:LonaCraftRaid] = raid id` on every adopted NPC; `WildnessNapEvent` kept, so the game's bookkeeping (`:1848-1866`) still works | |
### 3.3 Options for wall damage
| | A. Wall-HP events | B. HP table + siege driver (PROPOSED) |
|---|---|---|
| How | an invisible `Game_DestroyableObject` event per wall / door tile while a raid runs | `rec["hp"]["x,y"]` per damaged piece; the mod moves each raider to a stand tile next to a breach tile; when it swings, the mod subtracts damage |
| Can raiders hit it | no without patching sensors, the hit line and the damage factor (3.1) | yes: the swing is cosmetic (`launch_skill(first melee skill, true)`), the damage is the mod's |
| Events | +1 per wall (a 9 x 7 ring = 30) | 0 |
| Side effects | ev tag change breaks sight blocking; patches touch the whole battle system (and RolePlayS's copy) | an alias of `Game_Event#update_self_movement` (`F/39_Game_Event.rb:962`) only for raid NPCs |
| Save | events in the saved map | plain numbers in the base record |
Recommendation: **B**.
### 3.4 Numbers
Damage per swing = max(1, NPC `atk` - armour) x race factor. A swing every 60 + rand(30) frames (mean 1.25 s).
| Race factor | Orkind 1.5 | Goblin 1.0 | Human 1.0 | Fishkind 1.0 | Undead 0.75 | Abomination 1.25 | Dog, Others, Animal 0 (do not breach) |
|---|---|---|---|---|---|---|---|
| Piece | HP | Armour | Repair |
|---|---|---|---|
| Palisade Wall (A3, built) | 600 | 3 | 1 Plank = +150 |
| Wooden Door (built) | 300 | 3 | 1 Plank = +150 |
| A4 building wall (phase 2) | 1200 | 8 | 1 Stone Block = +300 |
Time for ONE raider to break a piece (s), `atk` from `NPC/*.json` (dry run output):
| Unit | atk | Palisade | Door | A4 wall |
|---|---|---|---|---|
| GoblinCommoner | 5 | 375 | 188 | 1500 |
| Goblin, mean of RandomGoblin kinds | 10 | 107 | 54 | 750 |
| HobgoblinSpear | 20 | 44 | 22 | 125 |
| OrcCommoner | 20 | 29 | 15 | 83 |
| OrcButcher | 25 | 23 | 11 | 59 |
| MobHumanCommoner | 0 | 750 | 375 | 1500 |
| MobHumanRogueScout | 14 | 68 | 34 | 250 |
| MobHumanRogueSpear | 20 | 44 | 22 | 125 |
| FishkindCharger | 15 | 62 | 31 | 214 |
| FishkindFat | 23 | 38 | 19 | 100 |
| UndeadCommoner | 5 | 500 | 250 | 2000 |
| UndeadEliteWarrior | 18 | 67 | 33 | 200 |
| AbomCreatureSpider | 10 | 86 | 43 | 600 |
| AbomCreatureZombie | 15 | 50 | 25 | 171 |
| WildDireWolf | 20 | - | - | - |
With the give-up time of 180 s, goblin commoners, common mobs, undead commoners and wolves never get
through a closed palisade. One raider per stand tile, so raiders work on different pieces side by side;
the first breach is the strongest raider's time plus its walk.
Dry run, BanditMobs 0-25 (3 spears, 2 scouts) on the sample base, Lona inside (r4_raid_plan.png):
| Raider | From | Target | Walk (tiles) | Breach after |
|---|---|---|---|---|
| Spear | (55,53) | front door (44,42) | 21 | 28 s |
| Spear | (56,44) | side door (40,39) | 22 | 28 s |
| Spear | (56,47) | wall (48,42) | 12 | 47 s |
| Scout | (37,53) | wall (40,42) | 13 | 72 s |
| Scout | (59,41) | wall (48,41) | 10 | 71 s |
So about 8 s grace + 28 s before the first door falls.
### 3.5 Siege driver (in `LC/120_Raids.rb`)
| Step | How |
|---|---|
| Enclosed? | flood from the play-area edge and exit ring as `Bases.inside_tiles` (`LC/110_Bases.rb:1109-1178`) but with LIVE doors (open door = passable); Lona's tile not reached = enclosed. Run at raid start, after every break, and when a door's `through` changes (polled every 30 frames) |
| Breach candidates | wall / door pieces with an outside-reached 4-neighbour; stand tile = that neighbour (sample base: 28 candidates, 32 stand tiles, 562 reached tiles) |
| Pick | per raider: min(walk frames + break time) over free stand tiles; doors win by their lower HP; reserved, one raider per stand tile |
| Walk | BFS distance map per stand tile, cached until the next re-plan, raider steps down it (as `find_next_tag`, `F/202_pathfinding.rb:381-395`); blocked 60 frames -> re-pick |
| Swing | on the stand tile: face the piece; every swing interval `launch_skill(first killer skill, true)` (animation, sound); if launched: HP -= damage, damage popup (`$game_damage_popups.add`, as `F/Modules/BattleSystem.rb:549`), `SndLib.sys_KnockDoor` (wood_chop, `E/509_SoundsLibs.rb:315-319`) at distance volume |
| Roles | ranged AIs (`npc.ranged?`) wait 4-6 tiles out and shoot once Lona is in sight; race factor 0 (animals) circle near the walls; both leave at give-up |
| Not enclosed (door open, wall down) | the mod lets go; raiders without a target get `anomally` = Lona's tile every 120 frames (1.3), the game's charge AI takes over once they see her |
| Who is driven | adopted raiders, alive, `action_state` nil / `:none`, no target; never during skill, sex, grab, stun |
### 3.6 Break, persistence
| Point | PROPOSED |
|---|---|
| HP storage | `rec["hp"] = {"x,y" => hp}` only for damaged pieces (absent = full); taking down or rebuilding a piece deletes its entry |
| At 0 HP | `Bases.break_piece(map, x, y)`: piece out of `pieces` (a door on a floor leaves the floor, as `take_down` `LC/110_Bases.rb:1242-1276`), door event removed, `paint` + `repaint` + `orient_doors_near` + `refresh_spawn_lists`; `SndLib.stoneCollapsed`; no refund |
| Rubble | none (the ground shows); a rubble piece is a later option |
| Revert | a break never ends the base during a raid (the normal `on_piece_removed` would remove the record when the last piece goes, `:383-390`); `base_empty?` (`:1748`) is checked when the raid ends |
| Across visits | broken stays broken, damaged stays damaged: the record is the truth |
## 4. Lona's side (PROPOSED)
| Point | Finding / PROPOSED |
|---|---|
| Fight from inside | melee and missiles cannot cross a palisade or a closed door (tag 4, 1.3). The fight is at the door: open it and the raiders come through one tile |
| Shoot over walls | not with the palisade. Later piece "Low fence": impassable tile with terrain tag 2: sight and arrows pass (`Sensors.rb:168`, `F/33_Game_CharacterBase.rb:224-230`), both ways; needs a tile hunt per sheet |
| Repair mid-raid | yes: action key on a damaged wall / door (from either side): Repair / Take down / Cancel; 1 Plank = +150 HP, 120 frames; refused when the piece was hit in the last 180 frames ("It is being hit") |
| Build mid-raid | allowed (B4' build mode), but not within 3 tiles of a living raider |
| Nap mid-raid | refused (hook 2.1); otherwise the game's rule would capture her through the walls (1.1) |
| End | all raiders dead, stunned out or gone -> "The raid is over" + the game's clear (`WildDangerous` -50); 180 s (10,800 frames) of siege without a breach -> raiders walk to the exit ring and are deleted; Lona leaves the map -> raid dropped, damage kept |
| Rewards | the raiders' own `drop_list` drops, unchanged; no bonus |
| Defeat | the game's combat defeat and capture flow, unchanged |
## 5. Companions and doors
| Point | Finding / PROPOSED |
|---|---|
| Open door | page 1 through ON: anyone walks through (raiders too), pathfinding sees it as open (`F/202_pathfinding.rb:470-475`) |
| Closed door | blocks everyone; only Lona opens it (`F/35_Game_Player.rb:604-614`); raiders break it |
| Companions | spawned next to Lona after setup (`summon_companion`, Map028 ev 1; `E/99_Game_Player_follower.rb:491`), so inside after a nap; they fight at the door; outside ones wait. PROPOSED unchanged; "companions pass closed doors" would need a collision alias, later |
| Dog | early warning (2.4) |
## 6. Engine limits
| Limit | Fact | PROPOSED |
|---|---|---|
| NPC count | sensors scan all characters each tick (`F/281_Game_NonPlayerCharacter.rb:417-440`), cost grows with n x n; game groups 1-14 | cap 12 raiders |
| Path cost | `find_path` = width x height array + BFS per call (`F/202_pathfinding.rb:484-518`); enclosure flood on Map028: 841-tile play area, 562 reached, 2.3 ms in Python | flood only on events (start, break, door change); one distance map per stand tile, cached; largest allowed family Map107 (3,431 passable tiles) about 4x |
| Events | no hard cap (new id = max + 1, `LC/90_Furniture.rb:787-799`) | option B adds 0 events |
| Nap reload | the raid starts AFTER the nap (spawned by the re-run BIOS), so no running raid crosses a nap; nap during a raid refused | |
| Map change | raiders are summoned, not nappable: gone on any setup (`F/31_Game_Map.rb:359-366`) | raid state cleared in `after_setup` (`LC/110_Bases.rb:345-358`) when the map is not the raid's |
| Save / load mid-raid | `$game_map` with events and `summon_data` is in the save (`F/5_DataManager.rb:939`); not set up again on load (`:994-1000`) | `lonacraft_data["raid"]` = {"id", "base", "map_no", "race", "grace", "siege", "since_hit"} (frames, plain types); after load re-adopt by `summon_data[:LonaCraftRaid]`, re-plan; HP is in the record |
| Fast-forward | 120 fps doubles real speed (`F/102_00_Scene_Map.rb:97-104`) | all timers in frames |
| RolePlayS | no AI, sensor or pathfinding override (grep of `RPS/`); its `take_damage` keeps the tag factor | nothing to do |
## 7. Config (PROPOSED)
`Config/Bases.json` (user file, never written by the mod) + generated `Config/Bases_defaults.json`, read
by the strict `LonaCraft::ConfigJSON` reader (`LC/55_Recipes.rb:585-596`), same rules as
`Config/Recipes.json` (`//` comments, a mistake = a console line). One file per feature, as Recipes;
pieces and raids both belong to bases. Recommendation: **`Config/Bases.json`** over a shared
`Config/LonaCraft.json`.
```json
{
"pieces": {
"W": {"hp": 600, "armour": 3, "repair_item": "ItemLonaCraftPlank", "repair_hp": 150},
"D": {"hp": 300, "armour": 3, "repair_item": "ItemLonaCraftPlank", "repair_hp": 150},
"A4": {"hp": 1200, "armour": 8, "repair_item": "ItemLonaCraftStoneBlock", "repair_hp": 300}
},
"repair": {"frames": 120, "blocked_after_hit_frames": 180},
"raids": {
"enabled": true,
"danger_per_value": 0.1, "danger_cap": 10,
"night_only": true,
"grace_frames": 480, "dog_extra_frames": 300,
"give_up_frames": 10800,
"swing_frames": 60, "swing_rand": 30,
"spawn_min_distance": 8, "door_bias": 0.5,
"extra_raider_per_value": 30, "extra_raiders_max": 4, "max_raiders": 12,
"no_build_near_raider": 3,
"refuse_nap": true,
"breach": {"Orkind": 1.5, "Goblin": 1.0, "Human": 1.0, "Fishkind": 1.0, "Undead": 0.75, "Abomination": 1.25},
"scenarios": {
"field": {"regions": [1], "groups": {"Orkind": 70, "BanditMobs": 30, "UndeadWalking": 20, "WolfGroup": 20}, "grace_frames": 480}
}
}
}
```
`repair_item` = the mod's item names (`LC/0_Core.rb:37`, `:44`).
As built (2026-10-06): repair keys moved to their own `"repair"` section (`item`, `hp`, `frames`,
`blocked_after_hit_frames`), plus `raids.retreat_frames` and `raids.min_breach_atk`; the full key list is
in README "Raids" and `Config/Bases_defaults.json`.
## 8. Work breakdown (PROPOSED)
| Item | Scope | Files | Ruby lines | Needs the owner's numbers |
|---|---|---|---|---|
| R4-1 HP, break, repair | `rec["hp"]`, `Bases.break_piece` (no revert mid-raid), repair entry in the wall / door menus, HP in the menu text, Config/Bases.json loader + defaults file | `LC/110_Bases.rb` (~90, after the R8 executor is done), `LC/120_Raids.rb` (config ~60), `Text/<5 langs>/Bases.txt` (+5 keys) | 150 | HP, armour, repair cost and time |
| R4-2 Trigger, scenarios, spawn, end | the 5 hooks of 2.1, scenario table, value bonus, extra raiders, spawn move and door bias, warning + grace, adoption, end checks, give-up retreat, nap refusal, raid state + save/load | `LC/120_Raids.rb` (new), `loader.rb` (1 line), `Text/<5 langs>/Raids.txt` (~10 keys) | 250 | chance model, night rule, scenario table, guards, end rules |
| R4-3 Siege driver | live enclosure flood, candidates, pick + reservation, cached distance maps, `update_self_movement` alias, swing + damage, roles, release + `anomally` hunt | `LC/120_Raids.rb` | 260 | race factors, swing interval |
| R4-4 Debug, docs, dry run | debug key "raid now" (a free numpad key; `LC/95_Debug.rb` and `LC/110_Bases.rb:58` hold 0 1 3 5 7 9 + - * /), console lines, README "Raids", Python port of the planner as a static check | `LC/120_Raids.rb`, README, `scratchpad/r3/r4_raid_plan.py` | 70 | none |
Total about 730 lines. Order R4-1 -> R4-2 -> R4-3 -> R4-4. R4-1 can start once the piece numbers are
set; R4-2 needs the trigger and scenario choices; R4-3 the race factors.
## 9. Not covered
Raiders damaging furniture or stations; a rubble piece; the low fence; companions passing closed
doors; raids on bases the player is not on (off-screen damage). All later options.
## Change 2026-10-08: every hostile sieges, the side-wall breach
Owner bug report 2026-10-08 (in game): after a nap the game's own wilderness group came, did not
attack the base at all; one that Lona aggroed lost her when she went in and shut the door.
| Finding | Evidence (game B.0.10.8.27, LC = Scripts/ before the change) |
|---|---|
| Only the mod's raiders were driven: the movement hook ran for `summon_data[:LonaCraftRaid]` only, set by `adopt_scan` for a group whose race the mod's own roll had armed | LC/120_Raids.rb:1735-1739 (alias), :956-974 (adopt), :779-797 (`after_spawn` returns unless `@armed` and race match) |
| A nap group the mod did not arm is never adopted: the overmap-encounter race overrides the roll (`OnRegionMapEncounterRace`), a re-entry spawns the remembered group again, a raid that already ended | E/34_Functions_RegionMap.rb:353-358; LC/120_Raids.rb:742-753 (`after_roll` "the game's group comes instead") |
| The game's nap group random-walks until it senses Lona (move type 1); inside walls it never sees her | research 1.1; F/Modules/Sensors.rb:161-172 (tag 4 ends the sight line) |
| Even adopted raiders went back to the game's AI once they had a target | LC/120_Raids.rb:1303 (`drive` returns false), :1468 (`update_swings` skips) |
| De-aggro: no target drop on "no path"; the drop is on lost sight. `sense_target` with a target (mode 3) finds nothing through a tag-4 wall top or closed door, counts `targetLock_HP` (10) down per sensor tick, then `process_target_lost` (target nil, alert 0, ai :none) | F/281_Game_NonPlayerCharacter.rb:417-468 (456-463), :490-504; sensor tick F/39_Game_Event.rb:698-707; chasing without a path F/39_Game_Event.rb:1211-1232 |
| Side-wall breach: `face_at` drew the face of the wall above on any tile under a wall that is not a piece, so a broken piece in a wall running up and down became a (solid) face | LC/110_Bases.rb:1340-1347 (before) |
Change (LC/120_Raids.rb, LC/110_Bases.rb):
| Point | Now |
|---|---|
| Who joins | every 30 frames on a base map while Lona is shut in: an NPC outside the enclosure that targets Lona's side (Lona, followers, mercenaries, maid) while that target is shut in ("aggro"), or the game's nap group of the map (`summon_data[:WildnessNapEvent] == OnRegionMapSpawnRace`, not the sewer's own population) that would attack Lona by the game's own test (`friendly?` false and `check_ai_state` killer / fucker / assaulter, as F/35_Game_Player.rb:355) ("nap group"). Not: projectiles, traps, objects, Lona's side, idle wanderers, non-hostile NPCs, anyone while Lona is not shut in |
| State | no raid running: a siege state of its own (`:hostile`), siege at once, no warning, no extras, no relocation; a raid in its siege phase: they join it (`r[:joined]` by event id, never tagged) |
| Driver | the same: roles, stand tiles, swings, damage `max(1, atk - armour) x breach factor x damage_mult`, breaks, re-plan, give-up and retreat; a unit with a target is driven while that target is shut in, the game's AI as soon as it can reach it |
| Target kept | alias `Game_Event#update_npc_sensor` (F/39_Game_Event.rb:698): before the game's sensor tick, a unit in the siege phase whose target is Lona's side, alive and shut in gets `targetLock_HP = 10`, so `sense_target` never reaches `process_target_lost` |
| End of `:hostile` | units down, or Lona not shut in (released, the game's AI), or give-up (they walk off); no popup, no `check_enemy_survival?` |
| Not doubled | the game's own spawn on a base map that the mod did not arm only gets a console line; its units join |
| Config | `raids` `"hostiles": true` (false: only the mod's raiders) |
| Trace | `siege: <name> targets <piece> at (x,y), reason no path / breach (...)` and `siege: <name> released, reason ...` in UserData/LonaCraft_trace.log (debug + trace on) and the console |
| Breach | `face_at`: no face on a tile under a wall when the tile below it is a wall or a door, unless both walls run left and right (two walls with one row between keep their face); `around` repaints the rows that depend on it; a rebuilt piece paints its top again |
Breach check (Python port of `paint` / `face_at` / `update_block` on Map028, ring (50,47)-(54,52),
inside 3 x 3, `scratchpad/r20/breach_check.py`, renders `scratchpad/r20/shots/breach_*.png`):
| Case | north piece (52,47) | its face (52,48) | east piece (54,50) | outside reaches inside |
|---|---|---|---|---|
| intact | blocked | blocked | blocked | no |
| east broken, old rule | blocked | blocked | blocked (face) | no |
| east broken, new rule | blocked | blocked | walkable | yes |
| north + east broken, new rule | walkable | walkable | walkable | yes |
| both rebuilt, new rule | blocked | blocked | blocked | no (tiles equal the intact map) |
## 10. Choices for the owner
| # | Choice | Options | PROPOSED |
|---|---|---|---|
| 1 | Chance | A game roll + base bonus / B own flat roll per nap | A, bonus min(10, value / 10) a nap |
| 2 | Time of day | night only (skip the shift once when napping at night) / any nap | night only |
| 3 | Scenarios | table 2.3 / the game's region lists unchanged | table 2.3 (no guards; wolves and mobs kept) |
| 4 | Bigger bases, bigger raids | +1 raider per 30 value (max +4, cap 12) / none | +1 per 30 |
| 5 | Warning and grace | 8 s (forest 5 s), dog +5 s / none | 8 s, dog +5 s |
| 6 | Spawn | >= 8 tiles from the base, half on the door side / the game's spawn | >= 8, half on the door side |
| 7 | Damage model | B HP table + siege driver / A wall-HP events | B |
| 8 | HP and armour | palisade 600 / 3, door 300 / 3, A4 1200 / 8 | as listed |
| 9 | Who breaches | race factors 3.4, animals 0, ranged wait | as listed |
| 10 | Break result | piece gone, no refund, no rubble / rubble piece / 50 % refund | gone, no refund |
| 11 | Repair | 1 Plank = +150 HP, 2 s, not while hit / rebuild only | 1 Plank = +150 |
| 12 | Raid end | all down / 180 s give-up / leave the map | all three |
| 13 | Nap during a raid | refused / the game's capture rule | refused |
| 14 | Build during a raid | allowed except within 3 tiles of a raider / allowed / blocked | allowed except near |
| 15 | Rewards | drops only / a bonus loot sack | drops only |
| 16 | Config | `Config/Bases.json` / a `raids` section in a new `Config/LonaCraft.json` | `Config/Bases.json` |