Files
LonaRPG-Online-Games/ModScripts/_Mods/LonaCraft/docs/RESEARCH_RAIDS.md
T
2026-10-29 21:59:06 +04:00

34 KiB

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.

{
 "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