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

1025 lines
76 KiB
Markdown

Developer reference. The player guide is README.md. (Paths below are relative to the mod folder.)
# LonaCraft 1.0.0 (developer reference)
Crafting and base building for LonaRPG B.0.10.8.27 (also runs on B.0.10.8.26).
## What it adds
- 12 crafting materials: Plank, Hide, Leather, Bone, Iron Ingot, Cloth Bolt, Rope, Stone Block, Glass, Nails,
and the raw Iron Ore and Rough Stone that mining gives.
- Crafting is done at **stations** (see "Stations" below): **by hand** from the main menu (a short
starter list, Common quality only), Carpentry Bench, Furnace, Anvil and Tailor's Table. Each
station lists only its own recipes.
- The dark pots (inn pots and stoves, the pot placed with "Set Dark Pot") are the game's own again:
they only cook. LonaCraft no longer adds a Craft choice there.
- With RolePlayS: its Light, Medium and Fire arrows (bundles of 10) can be crafted (see "Recipes").
- Recipes can be changed without touching the mod's files, in `Config/Recipes.json` (see "Config").
- **Salvage** (Carpentry Bench, Anvil, Tailor's Table): each of these has a "Salvage" entry and a box
of its own. Put equipment in, choose "Break it down!". A station only breaks gear whose main
material is its own (wood at the bench, metal at the anvil, cloth or leather at the tailor's
table); other gear stays in the box. Wood gives Planks, metal Iron Ingots, cloth Cloth Bolts,
leather Leather (1 or 2 each). Only heavy metal gear (Metal tag 6 or more, e.g. a sabre or a
broadsword) also gives 2 Nails. Gold gives nothing yet. Costs 1 stamina per item.
Salvage never gives back more than a quarter of the item's price in materials (each material
counted at its own price). If it would, Nails are taken off first, then the item's most valuable
material, one at a time, until it fits. Cheap gear whose quarter-price is below one unit of
anything it is made of (rags, clubs, sickles, the short sword...) gives nothing and stays in the box.
- **Bases**: Palisade Walls (they join up), Plank Floors and Wooden Doors built on wilderness maps; a
map with something built on it stays that tile's map, with a marker on the world map and
"Destroy all bases" on the System page, see "Bases" below.
- 54 pieces of furniture and decoration (beds, storage, the four stations, stove, water trough, lights,
rugs, racks, banners...) to craft and place in a home you own or a base, see "Furniture" below.
- Wild boars, rabbits, dogs, wolves, horses and apes can drop Hide and Bone.
- Mining Crystal Ore, Saltpeter or Phosphorus: each ore that drops also has a 60% chance to drop
Rough Stone and a separate 35% chance to drop Iron Ore.
- **Loose stones** to pick up (no tool) and **boulders** (a pickaxe is needed) on wilderness maps give
Rough Stone, and **wood from trees needs an
axe**: the new **Hatchet** (bought or crafted), see "Boulders and the axe".
- The Noer blacksmith sells Iron Ingots; dress traders (Noer market and others) sell Cloth Bolts.
## Scripts
`loader.rb` loads the 27 files of `Scripts/` in this order (the order matters; the number in a name is
not the load position):
| # | File | What it holds |
|---|---|---|
| 1 | `0_Core.rb` | constants (materials, the Hatchet, drop table), item registration, load-order warning, ground-drop pictures |
| 2 | `05_Config.rb` | `Config/LonaCraft.json`: the debug, self-test, trace and viewport-guard switches |
| 3 | `10_Icons.rb` | the mod's icon sheet pasted below the game's `Iconset` |
| 4 | `15_Text.rb` | ENG fallback for missing LonaCraft texts |
| 5 | `20_Station.rb` | salvage at the bench, anvil and tailor's table (shared boxes); the dark pots only cook; the Cook of the Stove and Cooking Fire |
| 6 | `30_Process.rb` | processing recipes (Planks, Stone Blocks, Ingots, Nails, Rope...) |
| 7 | `40_Mining.rb` | Rough Stone and Iron Ore drops from mining nodes |
| 8 | `45_Nodes.rb` | boulders, loose stones, the axe and pickaxe in hand (spec `docs/SPEC_NODES_AXE.md`) |
| 9 | `50_Tiers.rb` | quality tiers: tier variants of every craftable weapon and armour |
| 10 | `55_Recipes.rb` | the recipe list (derived + overrides + `Config/Recipes.json`), the JSON parser |
| 11 | `25_Shops.rb` | the mod's items at the game's traders, the price floor, `Config/Shops.json` |
| 12 | `02_ViewportGuard.rb` | disposes sprites and windows left on a disposed viewport (the RGSS301.dll crash) |
| 13 | `60_Skill.rb` | crafting level 0-20 and experience |
| 14 | `70_Save.rb` | save registry: remaps the mod's item ids when the load order changes |
| 15 | `80_CraftScene.rb` | the crafting screen (`Scene_LonaCraft`) and its crash trace |
| 16 | `85_MenuCraft.rb` | the main menu's "Craft" row (crafting by hand) |
| 17 | `90_Furniture.rb` | furniture items, placement, persistence, chests |
| 18 | `100_Homes.rb` | the Old Shack, the Stone House, the Noer tavern room and the inn rooms |
| 19 | `110_Bases.rb` | bases: walls, floors, doors, build mode, pinned maps, markers, names |
| 20 | `120_Raids.rb` | night raids on a base, wall and door HP, the siege, `Config/Bases.json` |
| 21 | `130_Sewer.rb` | the Deep Sewer map, its vermin and raids (entrances off: `ENTRANCES_OPEN = false`) |
| 22 | `140_AwayRaids.rb` | raids on a base while Lona is elsewhere, worked out on the record; reports |
| 23 | `150_Mercs.rb` | the mercenary squad from the Noer guild receptionist |
| 24 | `160_Rest.rb` | rest tiers (ground, Bedroll, Bed inside walls), the chest meal and the bath |
| 25 | `170_Maid.rb` | the maid from Boss Mama: a base or house, wages, morning cooking |
| 26 | `95_Debug.rb` | numpad debug keys and god mode (Home), only with `"debug": true` |
| 27 | `98_SelfTest.rb` | start-up self-test, `UserData/LonaCraft_selftest.log`; keep it last |
`HCGframes/*.rb` are small redirect scripts the game runs through `$mod_load_script` (trees, boulders, loose stones,
inn keepers and their naps, Maani, the guild receptionist, Boss Mama); they call into the modules above.
## Where each material comes from
| Material | Price | Farm / buy | Made at (station) | Salvage |
|---|---|---|---|---|
| Plank | 60 | - | 1 Wooden Club (chop trees, needs an axe) -> 2 (by hand, Carpentry Bench) | wooden gear (bench) |
| Hide | 80 | hunting drops (boar, rabbit, dog, wolf, horse, ape) | - | - |
| Leather | 150 | - | 2 Hide -> 1 (Tailor's Table) | leather gear (tailor) |
| Bone | 30 | hunting drops | - | - |
| Iron Ore | 120 | mining nodes (35% per ore); boulders (15% per yield) | - | - |
| Iron Ingot | 400 | Noer blacksmith | 2 Iron Ore + 1 Wooden Club -> 1 (Furnace) | metal gear (anvil) |
| Cloth Bolt | 60 | dress traders (Noer market) | 4 plants/herbs -> 1 (Tailor's Table) | cloth gear (tailor) |
| Rope | 40 | - | 4 plants/herbs -> 1 (by hand, Tailor's Table); 3 Cloth Bolt -> 1 (Tailor's Table) | - |
| Rough Stone | 10 | **loose stones** on the same maps and the plains roads (one pick with the action key, no tool, 1 each); **boulders** on plains, badlands, mountains, pine forests and deserts (4 per boulder, pickaxe required); cave ore nodes (60% per ore) | - | - |
| Wooden Club (game item) | 100 | chop trees (**needs an axe** carried or equipped); weapon traders and many shops sell it | 2 Plank -> 1 (Carpentry Bench) | - |
| Stone Block | 30 | - | 2 Rough Stone -> 1 (Carpentry Bench) | - |
| Glass | 150 | - | 2 Crystal Ore + 1 Wooden Club -> 1 (Furnace) | - |
| Nails | 25 | - | 1 Iron Ingot -> 4 (Anvil) | metal gear with Metal 6 or more |
Prices are the items' own prices; shops sell at that price times the shop's markup.
"Plants/herbs" means any item tagged as a plant or herb for the dark pot (fruit, vegetables,
mushrooms, nuts, herbs; mixing is fine). The cheapest ones you carry are used first, and the
message says which. Wooden Clubs come from chopping trees, which needs an axe (see "Boulders and the axe").
Your crafting skill and the ids of crafted items, materials and furniture are stored in your save
file (see "Save data").
## Boulders and the axe
`Scripts/45_Nodes.rb` (spec: `docs/SPEC_NODES_AXE.md`). Switches at the top of the file:
`BOULDERS_ENABLED`, `PICKAXE_REQUIRED`, `AXE_REQUIRED` (all `true`).
**Boulders.** Every time you enter a wilderness map from the world map, a few boulders are placed on it
(new ones each visit, like the game's own ore nodes and plants):
| Family (map name) | Boulders per visit | Where on the map |
|---|---|---|
| r1 PlainField (incl. RolePlayS's r1_PlainField4) | 1-2 | open ground (map region 11) |
| r3 BadlandMountain | 1-4 | open ground (region 9) |
| r5 PineForest | 1-2 | open ground (region 9) |
| r6 BadlandForest | 1-3 | open ground (region 9) |
| r7 PineForestMountain | 1-4 | the rock faces beside the path, where the game puts Phosphorus (region 39) |
| r14 AbomDesert, r19 OrkDesert | 1-2 | open ground (region 9) |
| r16 PlainBadland, r28 OrkBadland | 1-3 | open ground (region 9) |
The first boulder is always there; each further one appears on the game's own roll for its nodes
(Wisdom and Survival help). Boulders never stand on a path tile, next to another event or near the
map's start point. Change the table in `LonaCraft::Nodes::BOULDER_MAPS`.
Mining a boulder (face it and press the action key, as with ore):
| | |
|---|---|
| Tool | **a pickaxe is required**, carried or equipped. Without one Lona only says "Need a pickaxe to break this." |
| Stamina per swing | 1 with the pickaxe equipped, 2 when it is only carried (the game's rule for ore nodes; with RolePlayS its own harvest cost, same numbers) |
| Hits | 9; every 3rd hit drops 1 Rough Stone on Lona's tile, the last one 2 (**4 Rough Stone per boulder**) |
| Iron Ore | 15% with each drop |
| Afterwards | the boulder is gone until the next visit |
Pickaxes are sold by the Noer blacksmith and the weapon traders (200 gold before markup).
**Loose stones.** On the same visits, 1-3 small stones lie on the ground of every boulder map and of the
plains roads (r11 RoadPlain, incl. RolePlayS's r11_RoadPlain4; map region 11; on r7 they lie on the path,
region 4). A loose stone is a small node like the boulder, not a dropped item: it stays on the map for
the whole visit (dropped items vanish after a while) and comes back fresh on the next visit. Face it and
press the action key: 1 Rough Stone at once, no tool, no stamina, then it is gone. You can walk over it.
They use the boulders' tile rule but may lie as close as 3 tiles to the start point. The picture is the
game's small rock (the thrown-rock drop); a 32 x 32 `Graphics/Characters/LonaCraft_LooseStone.png`
replaces it. Table:
`LonaCraft::Nodes::LOOSE_MAPS`; switch `LOOSE_ENABLED`.
**The axe.** Trees that give Wooden Clubs (the common trees, and the noble road's trees) need an axe
carried or equipped: the **Hatchet**, or with RolePlayS its Lumberjack Axe or Poleaxe. Without one Lona
only says "Need an axe to cut wood." and nothing happens. Stamina stays the game's (or RolePlayS's: the
Lumberjack Axe equipped makes chopping cheap). Fruit trees (apple, banana, nuts, areca) still give their
fruit by hand.
**Hatchet** (tool, 150 gold, not equipped): sold by the Noer blacksmith and the common weapon traders, or
made by hand or at the Carpentry Bench from 1 Wooden Club + 2 Rough Stone + 1 Rope (always Common,
skill 0). **Gold-free start**: pick up 2 loose stones, make Rope from plants, and craft the Hatchet by
hand with the Wooden Club Lona starts with. Or buy the Hatchet: the bench itself needs no stone.
How it hooks in: the tree scripts are redirected through `$mod_load_script` to `HCGframes/CommonTree.rb`
and `HCGframes/CommonTreeNoble.rb`, which check the axe and then run the script that was there before
(RolePlayS's copy when it is loaded, else the game's). Boulders are an EventLib event copied from the
game's Saltpeter node at start-up and placed when the map's start-up event runs. Nothing is saved:
boulders come and go with the visit. The placeholder picture is the game's `$_boulder`; put a 48 x 48
`Graphics/Characters/LonaCraft_Boulder.png` in the mod to replace it (prompt in `docs/ASSET_PROMPTS.md`).
## Stations
| Station | Where | Built from | Crafts there |
|---|---|---|---|
| By hand (main menu) | the **Craft** entry of the main menu, anywhere Lona can open it | - | **Starter list, always Common**: Wooden Club -> 2 Planks, 4 plants -> 1 Rope, the Carpentry Bench, the Bedroll (2 Hide, 1 Rope), the Cooking Fire (2 Plank, 4 Rough Stone), with RolePlayS Light Arrows x10 (1 Plank, 1 Bone). |
| Cooking pot | every dark pot, inn stove, the pot from "Set Dark Pot" | - | **Cook only** (the game's own pot, unchanged). No crafting. |
| Cooking Fire | furniture you place in your home | by hand or at the Carpentry Bench | **Cook only**, the same cooking as a dark pot. No crafting. |
| Carpentry Bench | craft one by hand (main-menu Craft) and place it | 6 Plank, 2 Rope (no nails) | Wooden Club -> Planks, 2 Rough Stone -> 1 Stone Block, **all furniture and decorations**, weapons and shields mostly of wood. Salvage of wooden gear. |
| Furnace | Noer smithy; or craft one | 6 Stone Block, 8 Rough Stone | 2 Iron Ore + 1 Wooden Club -> 1 Iron Ingot, Glass |
| Anvil | Noer smithy; or craft one | 3 Iron Ingot, 2 Plank | 1 Iron Ingot -> 4 Nails, weapons and armour mostly of metal. Salvage of metal gear. |
| Tailor's Table | beside the Noer market dress trader; or craft one | 4 Plank, 2 Rope, 3 Cloth Bolt | plants -> Cloth Bolt, plants or Cloth Bolt -> Rope, 2 Hide -> 1 Leather, armour and weapons mostly of cloth or leather. Salvage of cloth and leather gear. |
The station of a weapon or armour piece is decided by its **main material**: the largest of its
Wood, Metal, Cloth and Leather tags (ties go Metal, then Wood, then Cloth, then Leather). Wood ->
Carpentry Bench, Metal -> Anvil, Cloth or Leather -> Tailor's Table. A recipe file may name its
station(s) itself with `"station": "anvil"` or `"station": ["hand", "carpentry"]` (`"pot"`, the old
name, still means `"hand"`).
**By hand** shows only recipes that name the `hand` station, and everything made by hand is
**Common**: the hand station's tier cap is 1 (`Stations::MAX_TIER`, changeable in `Config/Recipes.json`).
The cap is applied to the roll and to the chances the screen shows, so a recipe moved to `hand` in the
config still rolls normally at its bench.
**Bootstrap path** (no gold needed): pick up loose stones -> craft a **Hatchet** by hand (start-kit Wooden
Club, 2 Rough Stone, 1 Rope; or buy one) -> chop trees for Wooden Clubs ->
from the main menu's **Craft** make Planks (from Wooden Clubs)
and Rope (from plants) -> craft the **Carpentry Bench** by hand and place it in your home -> at the
bench cut Rough Stone (buy a pickaxe, mine boulders) into Stone Blocks -> **Furnace** -> smelt Iron Ore into Iron Ingots -> **Anvil**
-> with Cloth Bolts (dress trader) build the **Tailor's Table**.
**Town stations.** So crafting works before you own a home, fixed stations stand in Noer:
| Station | Map | Tile (x, y) |
|---|---|---|
| Furnace | NoerBlackSmithShop (the smithy) | 20, 31: the smithy's own forge in the back room becomes the Furnace |
| Anvil | NoerBlackSmithShop | 19, 32 (back room, left of the forge's work spot) |
| Tailor's Table | NoerMarket | 50, 37 (two tiles left of the dress trader's spot; 2 wide x 1 high, covers 50-51 on row 37) |
There is no town Carpentry Bench: it is the first thing the player builds (by hand from the main
menu) and places in a home or a base.
They work like placed ones but cannot be picked up. To move one, change its row in
`LonaCraft::Furniture::TOWN_STATIONS` (`Scripts/90_Furniture.rb`): `[map name, x, y, kind]`, or
`[map name, x, y, kind, :existing]` to turn the map's own event on that tile into the station (used
for the smithy forge). A new station is skipped (console note) when any tile of its footprint has a
map event, a placed piece of furniture, or is not walkable.
## Crafting screen
Choose **Craft** at a station, or **Craft** in the main menu for the by-hand list. The screen looks
like the storage-box screen; the title at the top left is the station's name ("By hand" for the
main menu) and only that station's recipes are listed:
- **Left: recipes**, grouped **Processing**, **Weapons**, **Ammo**, **Armour**, **Furniture** and **Decorations**. Each row shows the result's
icon and name, how many one craft makes when it is more than one (Planks x2), and the crafting skill
it needs. Rows you can't afford yet are dimmed. Recipes above your crafting skill are not listed at
all; they appear as your skill grows (`LonaCraft::CraftUI::HIDE_LOCKED` in `Scripts/80_CraftScene.rb`
set to false shows them dimmed and marked **Locked** instead).
- **Right: details** of the selected recipe: the materials with have/need (red when short), the skill
needed against yours (and your crafting level), the chance of each quality tier (Common to
Legendary) as a coloured bar (after the station's and the recipe's tier cap: by hand always 100%
Common), and for weapons and armour what the Common version gives (ATK or DEF), which higher tiers
scale up.
- **Craft:** the OK key or a left click on a recipe. If you have the materials and the skill, the
materials are used and a window shows what you made and its tier. If not, you hear a buzzer and the
missing materials (or the skill line) blink red.
- **Leave:** Cancel/Esc, a right click, or click **Cancel** at the top right (back to the map, or to
the main menu when the screen was opened from there).
- Up/Down, Page Up/Down and the mouse wheel scroll the list; moving the mouse over a recipe selects it.
Processing recipes still work as before (1 stamina each, any plants or herbs for the plant-fibre ones)
and always give the plain material. Weapons and armour roll a quality tier based on your crafting skill.
**Crafting by hand (main menu).** The main menu has a **Craft** row right after **Items**. OK on it (or
a left click on its page) opens the crafting screen for the hand station: only the hand recipes, and
whatever you make is Common. Leaving the screen brings you back to the menu. It is blocked (buzzer, the
reason in red on the page) in combat, on the world map and when you are not playing Lona, and the row is
hidden whenever Items is (while you cannot move). Cocona's menu has no Craft row. With the Craft row a
full menu has 10 rows, so the rows move 1 px closer together (17 instead of 18) to keep the last one above
the stats block under the menu; with 9 rows or fewer nothing moves. With RolePlayS it works the same: the
row takes RolePlayS's menu font, the menu reopens on the Craft row, and the map HUD comes back as usual
when you close the menu. The crafting screen uses RolePlayS's window skin when RolePlayS is on.
## Tiers
Crafted weapons and armour come in five quality tiers. The item you already know is **Common**;
the mod adds Uncommon, Rare, Epic and Legendary versions of every craftable item when the game starts.
| Tier | Colour | Price | ATK/DEF of the item | Extra while equipped |
|---|---|---|---|---|
| Common | white | x1 | x1.0 | - |
| Uncommon | green | x1.5 | x1.1 | max stamina +5 |
| Rare | blue | x2.5 | x1.2 | max stamina +5, max health +5 |
| Epic | purple | x4 | x1.35 | max stamina +10, max health +5, ATK/DEF +1 |
| Legendary | yellow | x7 | x1.5 | max stamina +15, max health +10, ATK/DEF +2, move speed +0.1 |
- ATK is scaled on weapons, DEF on armour (a shield that only gives DEF scales DEF).
- Weight, icon, look on Lona, equip slot and skills are those of the Common item.
- Every craftable item shows its tier in its name, the plain one too: "Short Sword (Common)",
"Short Sword (Rare)". Only the displayed text changes; the item itself, shops, quests and tool
checks are untouched. The description ends with one line: the tier name in the tier colour, then
that item's actual ATK and DEF and its HP, STA and SPD bonuses (green when they raise the stat,
yellow when they lower it), e.g. "Rare ATK 2.4, HP +5, STA +5". Item names in lists are not
coloured yet.
- Craftable means: weapons and armour with wood, metal, cloth or leather in them (their dark-pot
tags), that have a price, are not key items, bondage gear, hair or Cocona's gear, and whose name
has none of Cuff, Collar, Chain, Rope, Bondage, Slave. The list is built at start from whatever
the game and the mods loaded before LonaCraft define, and printed to the console.
- Tools by their exact item (Lantern light, RolePlayS tool checks, quest checks) only recognise the
Common item.
## Recipes (derived + overrides + config)
Recipes come in three layers; a higher one wins, recipe by recipe:
1. `Config/Recipes.json`, your own changes, merged field by field (see "Config").
2. `Recipes/*.json`, the mod's recipe files (furniture, arrows, the two examples below).
3. Recipes worked out from each item's dark-pot tags (below) and the processing recipes in the code.
Every craftable item has a recipe built from its dark-pot tags, so new items from other mods get
recipes automatically:
| Tag in the item | Material |
|---|---|
| Wood x | Plank, half of x rounded up (at least 1) |
| Metal x | Iron Ingot, a third of x rounded up (at least 1) |
| Cloth x | Cloth Bolt, half of x rounded up (at least 1) |
| Leather x | Leather, half of x rounded up (at least 1) |
| Wood and Metal | + 1 Nails |
| Cloth and Leather | + 1 Rope |
Then, if those materials are worth less than a quarter of the item's price (count x each material's
own price), more of the material of the item's biggest tag is added (Metal: Iron Ingot, Wood: Plank,
Cloth: Cloth Bolt, Leather: Leather) until they are, but never more than 12 of any one material.
Expensive items therefore often end at 12 of their main material.
The skill it asks for is the square root of (price / 50), rounded, from 0 to 20 (price 50 asks 1,
200 asks 2, 1250 asks 5, 5000 asks 10, 20000 asks 20).
To change a recipe, put a JSON file in `LonaCraft/Recipes/` (any file name):
```json
{"output": "ItemMhShortSword", "inputs": {"ItemLonaCraftIronIngot": 2, "ItemLonaCraftLeather": 1}, "skill_req": 5}
```
It replaces the built recipe for that item. A file may also hold a list of such objects.
An override is used exactly as written (no topping-up to a quarter of the price).
`skill_req` can be left out (then the square-root rule is used). An item that is not craftable can be given a
recipe this way too; it is always made as Common. Two examples ship: Wooden Club (2 Planks) and
Short Sword (2 Iron Ingots + 1 Leather). Optional fields: `"station"`, `"category"` (`"furniture"`,
`"decoration"`, `"ammo"`, `"building"`), `"fixed_tier"`, `"amount"` (how many one craft makes), `"max_tier"` (best tier),
`"requires": ["ModId"]` (the recipe is skipped quietly unless that mod is on) and `"id"` (a second
recipe for the same item needs its own id; the by-hand Bedroll and Cooking Fire use
`"hand:ItemLonaCraftFurniturePottedPlant"` and `"hand:ItemLonaCraftFurnitureCampfire"`).
**Arrows (RolePlayS).** Three recipe files make RolePlayS's arrow bundles (10 arrows per craft, never
a tier, 1 stamina per material, 1 crafting exp like processing, listed under **Ammo**):
| Arrows | File | Materials | Skill | Station |
|---|---|---|---|---|
| Light Arrows (x10) | `Recipes/Arrows_Light.json` | 1 Plank, 1 Bone | 0 | by hand, Carpentry Bench |
| Medium Arrows (x10) | `Recipes/Arrows_Medium.json` | 2 Plank, 4 Nails | 3 | Anvil |
| Fire Arrows (x10) | `Recipes/Arrows_Fire.json` | 1 Light Arrows (x10), 1 Cloth Bolt, 2 Oil | 2 | Carpentry Bench |
They carry `"requires": ["RolePlayS"]`: without RolePlayS they are skipped without a console line and
nothing shows. RolePlayS must load before LonaCraft (see "Load order").
The processing recipes (Plank, Leather, Nails, Rope, Cloth Bolt, Glass, Iron Ingot, Stone Block) are in the same list, never
roll a tier and cost 1 stamina. Weapons and armour cost 1 stamina per material used. Crafting needs
stamina above 0, like cooking.
## Crafting skill
- Crafting level 0 to 20. Level n to n+1 needs 20 x (n+1) exp. Each weapon or armour you craft gives
5 + its skill requirement exp; each processing recipe gives 1. "Crafting skill up" pops up on level-up.
- **Effective skill** = crafting level + half of Lona's Survival trait (rounded).
- Tier roll: a random number 0-99, plus 8 x effective skill, minus 4 x the recipe's skill requirement.
170 or more is Legendary, 130 Epic, 95 Rare, 60 Uncommon, below that Common. The crafting screen
shows the exact chances. A recipe above your effective skill cannot be made and is hidden from the
list (see "Crafting screen").
- With RolePlayS, every craft also gives a little Survival attribute exp.
## Config
`Config/LonaCraft.json` (the debug switch and the self-test settings) is described under "Debug
switch and self-test" below. The rest of this section is about the recipe config.
`Config/Recipes.json` holds your changes to the recipes. The mod never writes it; it is read when the
game starts (testing build: **Numpad \*** on the map reloads all recipes). Each start the game also
writes `Config/Recipes_defaults.json` (only when it changed): every recipe that loaded, one line each,
with the item's display name in a `//` comment above it. Do not edit that one: copy a line from it
into the `"recipes"` list of `Config/Recipes.json` and keep only `"id"` and what you change.
Lines starting with `//` are comments. A mistake skips that entry (or, if the file cannot be read at
all, the whole file) with a line in the console; there is never a message box.
| Key | Type | Default | Meaning |
|---|---|---|---|
| `stations.<id>.max_tier` | 1 to 5 | hand 1, others none | best tier that station can give (1 Common .. 5 Legendary) |
| `recipes[].id` | text, required | - | the output's item name, `process:<Key>` for a processing recipe (Plank, Leather, Nails, RopeCloth, RopeFibre, ClothFibre, Glass, Smelt, CutStone), or a recipe file's own `id` |
| `enabled` | true / false | true | `false` removes the recipe everywhere |
| `station` | text or list | from the lower layer | `hand`, `carpentry`, `furnace`, `anvil`, `tailor` (`pot` = `hand`) |
| `skill` | 0 to 20 | from the lower layer | crafting skill needed |
| `inputs` | {item name: count} | from the lower layer | replaces the whole list; `*plant` = any plant or herb |
| `amount` | 1 or more | 1 | how many one craft makes |
| `max_tier` | 1 to 5 | none | best tier this recipe can give (1 = always Common) |
| `category` | gear / furniture / decoration / ammo / building | from the lower layer | the group it is listed in |
| `requires` | [mod id, ...] | [] | the entry counts only when those mods are on (no console line otherwise) |
An unknown key gives a console line and is ignored. An entry with an unknown id, input or station
is skipped with a console line. An id with no recipe yet makes a new one (an item name; then
`station` and `inputs` are needed). The file ships with only the `stations` block.
Example:
```json
{"stations": {"hand": {"max_tier": 1}},
"recipes": [
{"id": "ItemLonaCraftFurnitureCarpentryBench", "station": ["hand", "carpentry"], "skill": 1, "inputs": {"ItemLonaCraftPlank": 6, "ItemLonaCraftRope": 2}},
{"id": "ItemArrowsShortX10", "requires": ["RolePlayS"], "category": "ammo", "station": ["hand", "carpentry"], "skill": 0, "inputs": {"ItemLonaCraftPlank": 1, "ItemLonaCraftBone": 1}},
{"id": "process:RopeFibre", "station": ["hand", "tailor"]},
{"id": "ItemMhShortSword", "skill": 6}
]}
```
## Furniture
54 pieces of furniture and decoration are crafted at the **Carpentry Bench** (the bench itself, the
Bedroll and the Cooking Fire also by hand from the main menu, with their own materials). The crafting screen lists them under **Furniture** (pieces you can use)
and **Decorations** (pieces that only stand there, give light, or can be walked on). They never
roll a tier (always Common), cost 1 stamina per material like weapons and armour, and give crafting
exp like them (5 + skill requirement).
| Piece | Group | Sprite (file [index] direction/pattern) | Footprint | Use | Recipe | Skill | Weight | Price | Icon |
|---|---|---|---|---|---|---|---|---|---|
| Bed | furniture | grimdark64_01 [4] 8/1 | 1x2 | Sleep | 6 Plank, 4 Nails, 2 Cloth Bolt | 4 | 12 | 700 | 262 |
| Bed (dark wood) | furniture | grimdark64_01 [4] 8/0 | 2x2 | Sleep | 6 Plank, 4 Nails, 2 Cloth Bolt, 1 Leather | 4 | 12 | 880 | 262 |
| Bed (blue) | furniture | grimdark64_01 [4] 8/2 | 1x2 | Sleep | 6 Plank, 4 Nails, 3 Cloth Bolt | 4 | 12 | 770 | 262 |
| Storage Chest | furniture | !$_chest_4 [0] 2/1 | rule | Open | 5 Plank, 4 Nails, 1 Iron Ingot | 4 | 10 | 960 | 270 |
| Narrow Table | furniture | !_clutter2 [3] 2/1 | 1x2 | Open | 8 Plank, 6 Nails | 4 | 12 | 760 | 266 |
| Apothecary Table | decoration | grimdark64_01 [2] 8/2 | rule | - | 6 Plank, 4 Nails, 1 Glass | 4 | 10 | 730 | 266 |
| Carpentry Bench | furniture | grimdark64_03 [1] 6/0 | rule | Craft/Salvage | 6 Plank, 2 Rope | 1 | 12 | 530 | 331 |
| Furnace | furniture | grimdark128_01 [3] 2/1 | rule | Craft (light) (animated) | 6 Stone Block, 8 Rough Stone | 2 | 12 | 310 | 836 |
| Anvil | furniture | grimdark64_02 [3] 4/0 | 1x1 | Craft/Salvage | 3 Iron Ingot, 2 Plank | 3 | 12 | 1580 | 284 |
| Tailor's Table | furniture | grimdark96_01 [2] 2/1 | rule | Craft/Salvage | 4 Plank, 2 Rope, 3 Cloth Bolt | 2 | 10 | 600 | 321 |
| Stove | furniture | grimdark64_04 [1] 2/0 | rule | Cook (light) (animated) | 6 Stone Block, 1 Iron Ingot, 2 Plank | 4 | 12 | 840 | 271 |
| Wooden Tub | decoration | grimdark32_02 [0] 4/1 | rule | - | 6 Plank, 4 Nails, 1 Rope | 3 | 10 | 600 | 265 |
| Water Trough | furniture | grimdark64_02 [7] 6/2 | rule | Bathe | 5 Plank, 3 Nails, 4 Stone Block | 3 | 12 | 590 | 265 |
| Round Table | decoration | grimdark64_02 [4] 4/0 | rule | - | 4 Plank, 2 Nails | 2 | 8 | 350 | 266 |
| Long Table | decoration | grimdark64_04 [4] 2/1 | rule | - | 6 Plank, 4 Nails, 1 Cloth Bolt | 3 | 12 | 620 | 266 |
| Wooden Door | decoration | grimdark64_03 [4] 8/0 | rule | - | 3 Plank, 2 Nails | 1 | 6 | 280 | 151 |
| Chair (wooden) | decoration | !_clutter2 [1] 2/0 | rule | - | 2 Plank, 2 Nails | 1 | 4 | 200 | 151 |
| Armchair (red) | decoration | !_clutter2 [2] 2/0 | rule | - | 3 Plank, 2 Nails, 1 Cloth Bolt, 1 Leather | 3 | 6 | 530 | 151 |
| Shelf | decoration | grimdark64_03 [0] 2/1 | rule | - | 5 Plank, 4 Nails | 3 | 9 | 480 | 271 |
| Wine Barrel | decoration | grimdark32_01 [3] 2/2 | rule | - | 5 Plank, 3 Nails | 2 | 6 | 450 | 268 |
| Cloth Pile | decoration | grimdark32_01 [3] 2/0 | rule | - | 2 Cloth Bolt, 1 Rope | 1 | 2 | 190 | 260 |
| Bucket | decoration | grimdark32_01 [3] 8/1 | rule | - | 2 Plank, 1 Nails, 1 Rope | 1 | 2 | 220 | 265 |
| Cooking Fire | furniture | !_fire [4] 2/0 | rule | Cook (light) (animated) | 2 Plank, 4 Stone Block; by hand 2 Plank, 4 Rough Stone | 1 | 6 | 290 | 836 |
| Lamp Post | decoration | grimdark96_01 [4] 4/0 | 1x1 | - (light) | 1 Iron Ingot, 1 Glass, 1 Rope, 2 Plank | 5 | 8 | 850 | 272 |
| Candelabra | decoration | !_clutter [4] 8/0 | rule | - (light) | 1 Iron Ingot | 3 | 3 | 480 | 274 |
| Wall Torch | decoration | !_fire [0] 6/1 | 1x1 | - (light) (animated) (wall) | 1 Iron Ingot, 1 Plank, 1 Cloth Bolt | 2 | 2 | 620 | 836 |
| Wall Candles | decoration | grimdark64_02 [2] 2/0 | 1x1 | - (light) (wall) | 1 Iron Ingot, 1 Cloth Bolt | 2 | 2 | 550 | 274 |
| Hanging Lantern | decoration | grimdark96_01 [5] 4/0 | 1x1 | - (light) | 1 Iron Ingot, 1 Glass, 2 Plank | 3 | 6 | 800 | 272 |
| Torch Stand | decoration | !_fire [0] 2/1 | rule | - (light) (animated) | 1 Iron Ingot, 2 Plank, 1 Cloth Bolt | 2 | 4 | 700 | 836 |
| Rug (red) | decoration | grimdark32_02 [7] 2/0 | 1x1 | - (walkable) | 3 Cloth Bolt | 1 | 3 | 220 | 378 |
| Rug (patterned) | decoration | grimdark64_02 [2] 2/1 | 1x1 | - (walkable) | 4 Cloth Bolt, 1 Rope | 2 | 4 | 340 | 378 |
| Goods Table | decoration | grimdark64_01 [7] 2/0 | rule | - | 3 Leather | 3 | 5 | 540 | 451 |
| Bedroll | furniture | grimdark64_01 [6] 2/1 | 1x1 | Sleep (walkable) (occupies its tile) | 2 Stone Block, 1 Plank; by hand 2 Hide, 1 Rope | 1 | 4 | 140 | 309 |
| Flower Pot | decoration | !_clutter [7] 2/0 | rule | - | 2 Stone Block | 1 | 2 | 70 | 309 |
| Butcher Post | decoration | grimdark64_01 [2] 4/0 | rule | - | 2 Cloth Bolt, 1 Plank | 2 | 3 | 220 | 233 |
| Banner | decoration | grimdark96_01 [0] 4/0 | 1x1 | - (wall) | 3 Cloth Bolt, 2 Plank, 1 Rope | 2 | 5 | 410 | 233 |
| Painting | decoration | grimdark64_02 [3] 2/1 | 1x1 | - (wall) | 2 Plank, 2 Cloth Bolt | 3 | 3 | 290 | 233 |
| Deer Trophy | decoration | grimdark64_01 [6] 4/0 | 1x1 | - (wall) | 2 Plank, 1 Leather, 1 Nails | 3 | 4 | 350 | 451 |
| Sword Crate | decoration | !_clutter [6] 6/0 | rule | - | 4 Plank, 3 Nails, 1 Iron Ingot | 4 | 8 | 860 | 147 |
| Spear Rack | decoration | !_clutter [6] 6/1 | rule | - | 4 Plank, 3 Nails, 1 Iron Ingot | 4 | 8 | 860 | 154 |
| Deepone Trophy | decoration | grimdark64_02 [0] 4/2 | 1x1 | - (wall) | 3 Plank, 2 Nails, 1 Leather | 3 | 6 | 460 | 502 |
| Stacked Crates | decoration | grimdark64_01 [5] 4/0 | rule | - | 5 Plank, 4 Nails, 2 Glass | 4 | 10 | 840 | 271 |
| Shrine | decoration | !_clutter [4] 8/1 | 1x1 | - (wall) | 4 Stone Block, 2 Plank, 1 Cloth Bolt | 3 | 8 | 360 | 359 |
| Fancy Dining Set | decoration | grimdark64_04 [4] 4/1 | rule | - | 8 Plank, 6 Nails, 3 Cloth Bolt, 2 Leather | 6 | 12 | 1330 | 151 |
| Stone Idol | decoration | grimdark64_03 [5] 4/0 | rule | - | 10 Stone Block | 5 | 12 | 360 | 257 |
| Skull Relief | decoration | grimdark64_03 [2] 4/0 | 1x1 | - (wall) | 2 Cloth Bolt, 2 Plank, 1 Leather | 3 | 4 | 470 | 339 |
| Iron Cage | decoration | grimdark64_04 [4] 8/1 | rule | - | 3 Iron Ingot, 1 Plank | 5 | 12 | 1510 | 808 |
| Hay Pile | decoration | grimdark64_02 [7] 8/0 | rule | - | 2 Rope | 1 | 4 | 100 | 269 |
| Crate Stack | decoration | grimdark64_02 [7] 8/1 | rule | - | 3 Plank, 2 Nails | 1 | 5 | 280 | 151 |
| Log Pile | decoration | grimdark64_03 [7] 8/1 | rule | - | 6 Plank, 1 Rope | 1 | 10 | 480 | 331 |
| Skeleton Throne | decoration | grimdark96_01 [2] 2/1 | rule | - | 3 Plank, 2 Nails, 2 Cloth Bolt | 2 | 6 | 420 | 321 |
| Still | decoration | grimdark128_01 [2] 2/0 | rule | - (animated) | 2 Iron Ingot, 2 Glass, 2 Plank | 5 | 12 | 1460 | 271 |
| Market Stall | decoration | grimdark128_01 [6] 2/1 | rule | - | 8 Plank, 4 Nails, 4 Cloth Bolt, 2 Rope | 4 | 12 | 1080 | 267 |
| Tent | decoration | grimdark128_01 [2] 4/0 | rule | - | 6 Cloth Bolt, 3 Rope, 3 Plank | 3 | 12 | 790 | 262 |
Every piece also has Pick up / Cancel. The recipes are ordinary override files
(`Recipes/Furniture_*.json`, with `"category": "furniture"` or `"decoration"` and `"fixed_tier": 1`),
so they can be changed like any other recipe. A new piece is one row in `KINDS`
(`Scripts/90_Furniture.rb`), one `Item/Furniture_<Key>.json`, one `Recipes/Furniture_<Key>.json`
and its texts in `Text/<lang>/Furniture.txt`. The internal key (file names, item names such as
`ItemLonaCraftFurnitureFurRug`) stays fixed for saves even when the display name changes (that key
is now the Goods Table). Removed kinds (Brazier, Scroll Shelf, Crate, Fireplace, Lantern (small)):
their pieces in an old save are skipped with a console note.
**Placing.** Open the inventory and *use* the piece (the hotkey slots do not place furniture). The
menu closes and a see-through copy of the piece appears on the tile in front of Lona. Move it with
the arrow keys (up to 3 tiles from Lona in each direction), **OK** places it, **Cancel** stops
without using anything. The copy turns faint on a tile where it cannot go; pressing OK there gives a
buzzer and the game's "cannot place here" line. A spot is fine when every tile the piece covers
(its footprint, below) is free ground: inside the map, not Lona's own tile, no event (person, door,
object) on it, not water or bush, and walkable from all four sides. A rug does not count as taken
(a table can stand on it); the Bedroll does (`:occupy`). The piece is taken from the inventory only
when it is placed.
**Wall pieces** (Banner, Painting, Deer Trophy, Deepone Trophy, Shrine, Skull Relief, Wall Torch,
Wall Candles; `:wall` in `KINDS`) hang on the back wall: they can be placed only on an owned
back-wall tile (`LonaCraft::Homes.wall_allowed_at?`, windows excluded), never on the floor, and floor
pieces never go on those wall tiles. The ghost can be moved onto the wall for them. A wall piece is
1x1, has no blockers (the wall already blocks) and is drawn like "above characters" (`@forced_z`)
while keeping normal priority, so the action key still reaches it from the floor tile in front.
**Footprint.** A piece blocks the floor tiles under its picture. From the picture's cell size
(cw x ch pixels): width w = (cw - 16) / 32 rounded up, i.e. cw / 32 rounded half down (32 and 48 px
-> 1, 64 -> 2, 96 -> 3, 128 -> 4; at least 1), height h = ch / 64 rounded up (at least 1;
the top half of a picture is drawn "up the wall", not on the floor). The piece's own tile is the
bottom row, centre: odd widths cover the same number of tiles left and right; even widths are drawn
half a tile to the right, so a 2-wide piece covers its tile and the one to the right, a 4-wide one
(the Furnace, 128 px) one tile left and two right. Rows go up h - 1 tiles from the piece's tile.
So: 32 px pieces and the !_clutter and !_fire pieces (32 x 64, e.g. the Cooking Fire) 1x1, 64 px pieces (benches, tables) 2 wide x 1
high, 96 px pieces (Tailor's Table placeholder, Skeleton Throne) 3 x 2, 128 px pieces (Furnace,
Still, Tent, Market Stall) 4 x 2. A `KINDS` row in `Scripts/90_Furniture.rb` may set `:foot_w` and/or
`:foot_h` (tiles) to override the formula for that piece; then the half-tile shift follows `:foot_w`
(odd: drawn centred, even: half a tile right), otherwise the picture width. Overrides in use: the
single beds and the Narrow Table 1 x 2 (rows y-1..y), the dark-wood bed (a double) 2 x 2, the Anvil,
Lamp Post and Hanging Lantern 1 x 1. Invisible blockers stand on the extra
tiles; pressing the action key at one opens the piece's menu. Rugs cover only their own tile and can
be walked on. Blockers saved under an older rule are rebuilt on the next map load.
**Where.** In a home you own (`LonaCraft::Homes.furniture_allowed?(map)`, the homes script) or
wherever a base can be built out in the wild (`LonaCraft::Bases.furniture_map_ok?(map)`, see
"Bases"), never on the world map or during combat. Anywhere else the game says "You can only furnish
a home you own or a base of yours out in the wild". Without the homes and bases scripts nothing can
be placed. Another mod can allow more maps with
`LonaCraft::Furniture.allowed_maps = ["MapName", ...]`.
**Using a piece.** Walk up to it and press the action key (rugs: stand on them).
- **Sleep** (beds, Bedroll): exactly what the game's beds do (the usual sleep menu follows).
- **Open** (Storage Chest, Narrow Table): a storage box of its own, kept in the save. Two
pieces never share a box.
- **Craft** (stations): the crafting screen for that station. **Salvage** (Carpentry Bench, Anvil,
Tailor's Table): see "What it adds".
- **Cook** (Stove, Cooking Fire): the normal dark-pot cooking, same as at any pot.
- **Bathe** (Water Trough): the game's own bath, the same as at a water spot.
- Lights light the area around them (the game's KHAS lights, as the placed cooking pot):
`torch_weak` for Furnace, Stove, Cooking Fire, Wall Torch, Wall Candles, Torch Stand;
`lanternSM_item` for Lamp Post, Hanging Lantern, Candelabra. Furnace, Stove, Cooking Fire,
Wall Torch, Torch Stand and Still are animated.
- **Pick up:** removes the piece and puts the item back in the inventory. A storage piece with
anything in it refuses ("empty it first"). Town stations cannot be picked up.
**Owner sprites.** The Anvil, Carpentry Bench and Tailor's Table use placeholder art from the game
until their own pictures are in `LonaCraft/Graphics/Characters/`:
`LonaCraft_Anvil.png`, `LonaCraft_CarpentryBench.png`, `LonaCraft_TailorTable.png`
(`LonaCraft::Furniture::CUSTOM_SPRITES`; a `LonaCraft_Loom.png` entry is reserved for a later piece).
Format: **one PNG = one cell** (the Anvil is 48 x 48, the other two 64 x 64; other sizes work and
set the footprint), transparent background, the object standing on the bottom edge (the bottom centre of the picture sits on the tile's bottom
centre). No 3 x 4 sheet: the event uses the whole picture (the game's manual cell size,
`@manual_cw = 1`, `@manual_ch = 1`). If a file is missing, that piece keeps its placeholder.
**What is saved.** Each placed piece is one entry (number, map, x, y, item) in the game's own system
data in the save, plus a storage piece's box contents in the game's storage boxes. Pieces come back
every time the map is entered, after sleeping, and after loading. If LonaCraft is removed, the
pieces on the map you are standing on stay visible until you leave it but do nothing; the entries
stay in the save and come back if the mod is turned on again. If a furniture item is removed from
the mod, its pieces are skipped (console note) and kept in the save. The salvage boxes of the
stations are shared by every station of that kind (town or home).
**Known limits.**
- The footprint comes from the picture's cell size (lower half only), even where the art itself is
smaller or transparent; use `:foot_w` / `:foot_h` for exceptions.
- Pieces cannot be moved; pick up and place again.
- Pieces belong to a map number. If the game reuses one map for several places, the pieces show up
in each of them.
- Furniture item ids follow the material ids, so the load-order rule below applies to them too.
## Homes
`Scripts/100_Homes.rb`. Turn the whole feature off with `LonaCraft::Homes::ENABLED = false`
(then there is no door, no offer and furniture can be placed nowhere). Each place is one row of
`LonaCraft::Homes::LOCATIONS`; its texts are in `Text/<lang>/Homes.txt`.
| Place | Price | Sold by | Where |
|---|---|---|---|
| Old Shack (`noer_shack`) | buy, 5 Gold Coins | Maani, the bank clerk who keeps the storage | World map, bottom-left corner of Noer (tile 23,100) |
| Stone House (`noer_stonehouse`) | buy, 15 Gold Coins | Maani, the bank clerk who keeps the storage | World map, middle of Noer, two tiles left of the tavern (tile 31,100) |
| Upstairs Room (`noer_inn_room`) | rent, 2 Large Copper Coins a week | Boss Mama, the tavern keeper | Noer tavern, the room right of Cocona's (top-left) |
**Buying (the shack, the stone house).** While a house is not owned, Maani's menu has one more line
for it, "Buy shack 5 gold" and "Buy stone house 15 gold". It takes that many Gold Coins (only Gold
Coins count). Not enough: she refuses. Everything else in the menu is the game's own, unchanged.
**The Old Shack.** In this game Noer is the world map itself: each building is a point on it that
leads into its own map. The shack is a point like that (a small wooden house) in the bottom-left
corner of the city, far from the gates. Not owned: "Locked. The bank sells this house." Owned:
Enter / Leave. Inside is one empty wooden room, 6 x 4 tiles of weathered boards
(`Maps/NoerShack.rvdata2`, built from the middle room of the game's NoerTransHouse map); the
stairs at the bottom lead back out, as in every building of the game. Move the door by editing `:door` (map
name, x, y, picture) in the row.
**The Stone House.** Bigger and of better materials, 15 Gold Coins. Its door is a point like the
shack's (a big brown townhouse) in the middle of Noer, two tiles left of the tavern.
Locked / Enter / Leave as the shack. Inside is one empty room, 8 x 5 tiles of grey flagstone under
grey dressed-stone walls with two windows (`Maps/NoerStoneHouse.rvdata2`, laid out like the shack);
the stairs at the bottom lead back out.
**Renting (the tavern room).** Boss Mama's menu gets, at the end:
- not rented: "Rent room 2 LC a week" (LC = Large Copper Coin)
- rented: "Extend rent 2 LC a week" and "Rent status" ("The room is yours
for N more days")
- whenever she holds things of Lona's: "Collect belongings" (everything back at once)
Renting or extending asks 1 / 2 / 4 weeks / Cancel and takes 2 Large Copper Coins per week; not
enough coins: she refuses. The menu lines are kept short on purpose: the game's choice window
squeezes a line wider than its 608 px text area, and then also showed a dim copy under the selected
line; LonaCraft clears that row before the selected line is drawn (a small fix in 100_Homes.rb).
Paying while the rent still runs adds the weeks to its end. A week is 7
game days (the end is kept as the game's date count, two steps per day). The rent runs out when that
date has passed; this is checked every time a map loads, every time the date moves (each sleep) and
when Boss Mama's menu opens. Then the room is the game's own again at the next load (bed, bucket,
table, torch), and every piece Lona placed in it, with the contents of its chests, goes to Boss
Mama: the popup says "Your room rent ran out. Boss Mama is holding your belongings." Collect them
from her menu (an item that no longer exists is skipped, console note).
**The Upstairs Room while rented.** The room's own bed, water bucket, small table and the wall
torch above it are gone (the window stays); Lona furnishes it herself. Sleeping on her own bed in
the room is the inn's own paid sleep (night visitors as the inn has them, then the meal, bath and
full restore of a room key) without needing or using a key. The rest of the tavern still needs a
key as before, and Boss Mama's own room key still works as before. The room is worked out from the map each time it loads:
every walkable tile reached from `:room_seed` without crossing `:door_tiles` (the room's door and
the closed stair to the floor above), inside `:room_bounds`, plus the table's tile: 11 tiles. The
bed's and a scene point are moved just outside the door. The map file is never changed. Renting
while Lona stands in the tavern clears the room at once.
**Furniture** may be placed anywhere in an owned house and only on the room's tiles while the rent
runs (`LonaCraft::Homes.furniture_allowed_at?(map, x, y)`). Wall decorations go on the wall tile
just above the floor, except the windows (`LonaCraft::Homes.wall_allowed_at?(map, x, y)`): in the
shack (11,12), (13,12), (14,12), (16,12); in the stone house (11,12), (13,12) to (16,12), (18,12);
in the tavern room (31,28) to (34,28).
**Sleeping in a house** (the shack, the stone house) on a placed bed is the plain nap, the same as
sleeping in the field: no meal, stamina comes back from satiety and satiety goes down.
**Saved.** Which places are owned, the rent end, and what Boss Mama holds (game system data in the
save, no extra hook). If LonaCraft or homes are turned off while Lona is inside a house, leave it
first: the house maps are only known while the mod runs.
**Adding a place.** A house: a map file in `Maps/`, a row with `:door` and `:interior`, texts. A
room on a game map: a row with `:map`, `:room_seed`, `:room_bounds`, `:door_tiles`, `:keep`,
`:move_points`, `:tile_overrides`, `:remove_event_tiles`, `:floor_ref` and, for an inn,
`:nap_script`; `:mode => :rent` with `:price` and `:coin` per week. A new seller: one `SELLERS`
line and a two-line `HCGframes/<script name>.rb` like the existing ones.
## Bases
`Scripts/110_Bases.rb` (base building; design: `docs/RESEARCH_BASE_BUILDING.md` sections 2-4 and
9). Turn it off with `LonaCraft::Bases::ENABLED = false`.
**The pieces.** Three items, made at the Carpentry Bench or by hand from the main menu (group
"Building" in the crafting list, always Common):
| Item | Recipe | What it is |
|---|---|---|
| Palisade Wall | 2 Planks + 1 Rope | a log wall tile; walls next to each other join up (corners, ends, T and cross pieces) |
| Plank Floor | 2 Planks | a plank floor tile |
| Wooden Door | 3 Planks + 1 Rope | the game's own wooden door |
The wall and the floor are drawn with the map's own tiles, so they match the land: vertical logs
and planks from the tile sheet of that map (plains, roads, shore, forests, mountains, swamps,
wastelands, the Abandoned House maps). They are not events: walls block walking, sight and missiles
as the game's own walls do.
**Build mode.** Use any of the three pieces from the inventory while on a wilderness map (or pick
"Build mode" in the menu of a wall or floor you built): build mode opens with that piece selected.
A frame shows the cursor (yellow: it can go here, red: it cannot), the piece itself is drawn under
it, and a box in the top right corner shows the piece, its cost with how much of each material Lona
has, and how many she can build now.
| Key | In build mode |
|---|---|
| Arrow keys | move the cursor (up to 9 tiles left and right of Lona, 5 up and down) |
| L / R (Page Up / Page Down, or the mouse wheel) | previous / next piece: Palisade Wall, Plank Floor, Wooden Door |
| OK | build the piece here; hold OK while moving the cursor to build along a line |
| The game's "delete item" key (Space unless changed) | take down the piece under the cursor; its materials come back |
| Cancel | leave build mode |
A piece is built at once and paid at once: no crafting step, the materials of its recipe are taken
from the inventory (2 Planks + 1 Rope for a wall, 2 Planks for a floor, 3 Planks + 1 Rope for a door;
read from the recipe list, so `Config/Recipes.json` can change them). A ready-made piece in the
inventory (a crafted Palisade Wall, Plank Floor or Wooden Door) is used first, before materials.
Not enough of either: a buzz and "Not enough materials". Not allowed: the edge of the area ("Too
close to the edge of the area": the way out, the map's border, the outermost band of walkable ground
and the tiles against it, so there is always open ground outside the walls), the tile where Lona comes in and the tiles next to it, a tile with anything on it (an item on
the ground, an animal, a placed piece or furniture), water, bushes and tiles nobody can walk on; a
wall or a door not on Lona herself. A door may stand on a built floor. The first piece on a map
makes it a base (see below).
**Taking down outside build mode.** Face a wall or a floor piece and press the action key: "Take
down" gives the piece back as an item (crafted pieces are worth their materials) and the walls
around it join up again. When the last piece of a base comes down (and no furniture is left on it),
the base is gone and the tile is wild again.
**The door.** Closed, the action key opens it and Lona walks through. Open, the action key asks
Close / Take down / Cancel. Doors are closed again every time the area is entered and after
sleeping there. Companions and other people never open doors: a companion waits outside a closed
door, as in town, so leave it open for them. A door can go anywhere (the player's call); in a wall
gap it looks right. A door in a wall that runs up and down (walls above or below it, none left or
right) is a sideways door: closed it shows the door edge-on, opening turns it to face Lona, and
closing turns it back. In a wall that runs left and right, or with no wall next to it, it is the
front door. The way a door faces is worked out again whenever a wall next to it is built or taken
down and every time the area is entered.
**Furniture in a base.** Furniture, decorations, workbenches and storage can be placed anywhere a
base can be built, with the same tile rules as the pieces (not near the edge of the area, not where
Lona comes in). A piece of furniture counts as a building: placing one on a wild map makes it a base and pins
the map, and the base only ends when the last piece AND the last piece of furniture are gone. Wall
decorations hang on a palisade wall whose tile below is not a wall (the face Lona sees). Homes and
the inn room keep their own rules.
**Limits.** Wilderness areas are small (a plains area is 25 x 25 tiles, forest areas are mostly
narrow paths), so a base is as big as its area allows. Walls and doors have HP and raiders break
them: see "Raids".
Nothing can be built, and build mode does not open (it closes if one turns up), while an NPC
hostile to Lona is in the area (goblins, bandits, undead, guards that are after her; by the game's own
friendly / tri-state test) or anything, an animal too, is fighting her or her companions: "Not while
enemies are in the area." (owner 2026-10-08; before, any NPC blocked). Companions, mercenaries, the
maid, traders, wanderers, friendly guards and wild animals do not block. This keeps Lona from being
hit in build mode and walls from being used to trap or dodge enemies mid-fight.
**No spawns inside.** Every time a base map is set up, and after every piece built or taken down,
the mod works out which ground is shut in by walls and doors (a closed door counts as shut; a gap
in the wall does not) and keeps the game's animals, attackers, resources and night-time groups from
appearing there or on any built tile. They appear outside and can still walk in through an open
door or a gap. If a kind of spawn would have no place left at all, it uses the edge of the area.
The console shows "LonaCraft Bases: N tiles inside the walls kept clear of spawns". One exception
is the game's own capture scene (a group from an earlier night still standing when Lona sleeps
again): it places its attackers right next to Lona, wherever she is.
**Live picture.** A piece built or taken down shows at once: the mod hands the map picture a fresh
copy of the map (`LonaCraft::Bases::REDRAW = :table`). If a piece does not show until Lona leaves
and comes back, set `REDRAW = :spriteset` (the picture is rebuilt as after sleeping) and tell us.
Every time a base map is set up (entering it, sleeping there, loading a save made there) the console
(Console.bat) shows "LonaCraft Bases: map N painted W walls, F floors, D doors from record ID", and a
second line if walls or floors could not be drawn on that map's tiles.
**What a base is.** A world-map tile with buildings on it. Each time Lona enters a wilderness tile
the game picks one of that region's maps at random. Once something is built on the map she got,
that map is pinned to the tile: every later entry of that tile, by the region menu, an encounter or
falling asleep on the world map out of stamina, loads the same map. Resources, animals and the
weather still come back on every visit as the game rolls them. When the last building on it is
removed, the base is gone and the tile picks a random map again.
**Where a base may be.** On a world-map tile that can be entered (it has a region with field maps),
that has no point on it (towns, caves, quest places, the abandoned houses' doors), that is not
inside the walls of Noer and not in a settlement region (Slums, Rudesind Slope, Infected City
Ruins, Refugee Camp, Town and Streets of Noer, Fortress Ruins, Sybaris). The tiles of the Abandoned
House region are allowed. A base is only started on a map entered the plain way: not one entered
through a world-map event (an encounter, a refugee camp, a call for help). On OvermapMain 4,246
tiles qualify.
**The marker.** Every base shows a small fenced camp on its world-map tile. Standing on it, the
action key opens the tile's menu as before (Enter loads the base's map). The marker goes with the
base.
**Destroy all bases.** Main menu, System page, last line "Destroy all bases (N)". It asks first
(Confirm / Cancel). Yes removes every base: the tiles pick random maps again, the markers go and
the built pieces are not refunded; furniture placed on a base map comes back to the inventory, with
everything that was in its chest. With no base the line buzzes.
**Saved.** One entry per base (world-map tile, the pinned map, the pieces) in the game's own
system data. If LonaCraft is turned off while Lona stands on a base map, leave it first: the
pinned map is only known while the mod runs.
**Debug key.** Numpad / (only with `"debug": true` in `Config/LonaCraft.json`, `LonaCraft::Bases::DEBUG`): on a field map, adds an
invisible "debug" piece on Lona's tile (the first one makes the base and pins the tile), or
removes it when she stands on one (removing the last one ends the base). On the world map it tells
whether the tile under Lona is a base, allowed or refused (and why). Numpad 0 also gives 10 of
each building piece.
## Raids
`Scripts/120_Raids.rb` (design: `docs/RESEARCH_RAIDS.md`). Night raids on a base, with wall and
door damage. Raids only happen on a base map; nothing changes anywhere else.
**What triggers one.** Sleeping on a base map. The game's own danger roll for a night outdoors stays
(it grows each night, falls when a group is beaten, and Survival lowers it); a base adds a bonus to
it each nap: its value / 10, at most +10, value = walls + 2 per door + 3 per furniture piece. Which
group comes depends on where the base is:
| Scenario | World-map regions | Groups (weight) | Warning time |
|---|---|---|---|
| field | Plainfield (1) | Orkind 70, bandits 30, undead 20, wolves 20 | 8 s |
| road | Road, Blighted Road, Highway (11, 17, 23) | bandits 60, Orkind 20, common mobs 20 | 8 s (raiders favour the door) |
| forest | Rain Forest, Pine Forest, Mountain (4, 5, 7) | Orkind 70, bandits 20, undead 30, wolves 40 | 5 s |
| shore | Shore (2, 27) | Orkind 50, bandits 40, fish people 20 | 8 s |
| swamp | Swamp, Swamp Trail, Marsh, fish islands (8, 13, 15, 24, 25, 26) | Fishkind 70, Orkind 30, undead 20 | 8 s |
| wasteland | Infested Mountain, Dead Forest, Wasteland, Infested Creep, Polluted Land, Infected Terrain (3, 6, 14, 16, 19, 28) | abominations 40 + spiders 30, Orkind 30 | 8 s |
| house | Abandoned House (9) | bandits 60, common mobs 30, Orkind 10 | 8 s (raiders favour the door) |
Guards never raid a base. Every raid comes at night: if Lona slept at night and a raid was rolled,
she is woken in the same night instead of the morning.
**The warning.** When she wakes, a popup ("Something is moving out there in the dark...") and the
group's alert sound. The raiders appear at least 8 tiles from the base, about half of them on the
side of the door nearest Lona, and hold still for the warning time (8 s, forest 5 s; +5 s when
Lona has a dog with her, which growls first). Bigger bases draw bigger raids: +1 raider per 30
base value (at most +4), never more than 12 in all.
**The siege.** While Lona is shut in (walls all round, every door closed), each raider that can
break things walks to a wall or door between the outside and Lona, one raider per spot, and hits it
about once a second (every 1 to 1.5 s): damage = its attack - the piece's armour (at least 1), times
its kind's factor. Doors go first when they are near, being weaker. When a piece breaks it is gone
for good (no refund, no rubble; a door on a plank floor leaves the floor) and the raiders come in
with the game's normal fighting. Opening a door yourself does the same: they come for Lona. Walls
and closed doors stop sight, melee and arrows both ways, so the fight is at the door or the breach.
| Who | Breaks walls? | Factor |
|---|---|---|
| Orkind (orcs) | yes | 1.5 |
| goblins, humans, Fishkind | yes | 1.0 |
| undead | yes, slowly | 0.75 |
| abominations | yes | 1.25 |
| animals (wolves), anyone with attack below 3 (common mobs) | no, they prowl outside | 0 |
| archers and other ranged fighters | no, they wait a few tiles out | - |
A bandit spear (attack 20) breaks a door in about 22 s and a palisade in about 45 s, so the first
door of a bandit raid falls about 30 s after Lona wakes. Weak goblins, undead commoners, common mobs
and wolves cannot get through a closed palisade before they give up.
| Piece | HP | Armour |
|---|---|---|
| Palisade Wall | 600 | 3 |
| Wooden Door | 300 | 3 |
| building wall (later) | 1200 | 8 |
**Repair.** The action key on a wall or door (from either side) shows its HP ("Palisade wall, 420
of 600"); a damaged one offers "Repair (1 Plank)": +150 HP, takes 2 s and one Plank. Not while that
piece is being hit (it was hit in the last 3 s). A closed damaged door asks Open / Repair / Cancel.
In build mode, OK on a damaged piece of the selected kind repairs it. Damage stays until repaired,
also after leaving and coming back (it is kept in the base).
**The end.** The raid is over when every raider is down (dead or out of stamina; they drop their
loot as the game's groups do), or when they have besieged 180 s without breaking anything (they walk
off), or when Lona leaves the map. A base left with nothing standing ends after the raid.
**Sleeping during a raid** is refused ("Not now. They are still out there."). Building is blocked
anyway while raiders are in the area (the rule of "Bases").
**Saved.** Wall and door HP is saved with the base. A raid in progress is not saved: after a load
there is no raid; raiders still on the map are then the game's ordinary night group (sleeping with
them alive lets the game's capture scene run, as on any field map).
**Config.** `Config/Bases.json` (your changes, never written by the mod), with
`Config/Bases_defaults.json` written by the game listing every key and default. Same rules as
`Config/Recipes.json`: `//` comments, copy only the keys you change into the same section; a bad
entry is skipped and a broken file is not used, both with a console line.
| Key | Default | Meaning |
|---|---|---|
| `pieces.W.hp`, `pieces.W.armour` | 600, 3 | palisade wall |
| `pieces.D.hp`, `pieces.D.armour` | 300, 3 | wooden door |
| `pieces.A4.hp`, `pieces.A4.armour` | 1200, 8 | building wall (later) |
| `repair.item`, `repair.hp` | ItemLonaCraftPlank, 150 | what one repair costs and gives |
| `repair.frames`, `repair.blocked_after_hit_frames` | 120, 180 | repair time; no repair this long after a hit (60 frames = 1 s) |
| `raids.enabled` | true | false switches raids off |
| `raids.danger_per_value`, `raids.danger_cap` | 0.1, 10 | the base's bonus to the danger roll |
| `raids.night_only` | true | keep the night when a raid is rolled at night |
| `raids.grace_frames`, `raids.dog_extra_frames` | 480, 300 | warning time; extra with a dog |
| `raids.give_up_frames`, `raids.retreat_frames` | 10800, 1200 | siege time before they give up; time to walk off |
| `raids.swing_frames`, `raids.swing_rand` | 60, 30 | a hit every 60 + 0..30 frames |
| `raids.spawn_min_distance`, `raids.door_bias` | 8, 0.5 | spawn distance; share on the door side |
| `raids.extra_raider_per_value`, `raids.extra_raiders_max`, `raids.max_raiders` | 30, 4, 12 | bigger bases, more raiders |
| `raids.min_breach_atk` | 3 | weaker raiders do not hit walls |
| `raids.refuse_nap` | true | no sleeping during a raid |
| `raids.breach` | Orkind 1.5, Goblin 1, Human 1, Fishkind 1, Undead 0.75, Abomination 1.25 | {race: factor}; 0 or missing = cannot |
| `raids.scenarios.<name>` | the table above | `regions` [...], `groups` {group: weight}, `grace_frames`, `door_bias`; only the fields you change |
Groups: Orkind, OrkindPlayGround, Fishkind, FishPPL, BanditMobs, CommonMobs, UndeadWalking,
WolfGroup, AbomManager, AbomSpider. Example: `{"pieces": {"W": {"hp": 800}}, "raids": {"give_up_frames": 7200}}`.
**Console.** Every step prints a line starting "LonaCraft Raids:" (the nap roll and bonus, raid
armed, the group collected, spawn tiles, the siege plan, each raider's target, the first hit, every
break, the end and why). Turn raids off with `"raids": {"enabled": false}` in `Config/Bases.json`.
**Debug key.** Numpad . (only with `"debug": true` in `Config/LonaCraft.json`, `LonaCraft::Raids::DEBUG`) on a base map: pick a
scenario, then a group (or Any), and that raid starts at once, at any time of day, with no roll.
## Save data
- The crafting level and exp are kept in the game's own system data in the save.
- Crafted Uncommon to Legendary items are new item types, and their ids depend on the mods loaded
before LonaCraft. Each save also stores which id each crafted item had; when you load, items whose
id moved are put back on the right item (inventory, everything equipped, storage boxes). A crafted
item that no longer exists (its base item was removed) is dropped and noted in the console.
- Materials and furniture items are remapped the same way (save data version 2): each save stores
the id of every material and furniture item, and on load the counts in the inventory are moved
to this session's ids by item name, so adding, removing or reordering a mod loaded before
LonaCraft (e.g. moving RolePlayS above it) keeps them right. Storage boxes are fixed by item
name in every save, old or new. An item that no longer exists is dropped and noted in the
console; the console shows "LonaCraft Save: remapping N material and furniture item ids" when
ids moved and prints nothing when they did not.
- A save written by an older LonaCraft (save data version 1) has no material or furniture ids:
its inventory materials and furniture are left as they are (one console note). Load it once
with the same mods and order it was made with and save it again (that writes version 2), then
change the order.
- Bases keep their wall and door HP in their own record (damaged pieces only). A raid in progress
is not saved: after a load there is no raid ("Raids").
- Loading a save made before this version works: the skill starts at 0.
- If LonaCraft is turned off, a save with crafted Uncommon+ items in it may show empty or wrong
entries for them; materials have the same problem. Keep the mod on for that save.
## Load order (important)
Open the in-game **Mods** menu and put **LonaCraft at the bottom**, below RolePlayS and
Lona Big Booba, then restart the game. If it is above them, the game shows a warning at start.
Why: new items get their ids from the order mods load. Saves record items by id, so changing the
order later can swap items in an existing save. LonaCraft fixes its own items on load (see "Save
data"); other mods' items are not fixed. Pick the order once and keep it.
The mod manager cannot enforce this from LonaCraft's side: `"before"` in `_ModInfo.json` only
says "load me before X", and `"requires"` only checks that a mod is present (and would disable
LonaCraft for players without RolePlayS).
## Other mods: RolePlayS
RolePlayS must load **before** LonaCraft. In `UserData/GameMods.ini` give RolePlayS the smaller
`LoadOrder` (lower numbers load first), e.g. `[RolePlayS] LoadOrder = 1` and
`[LonaCraft] LoadOrder = 2`, and do not give them the same number. The Mods menu does the same:
RolePlayS above LonaCraft.
If RolePlayS loads after LonaCraft:
- Boars and rabbits drop no Hide or Bone (RolePlayS replaces those animals after LonaCraft added them).
- Maani's menu wrapper hides RolePlayS's Assessment screen, and the Assessment skill crashes.
- RolePlayS's own maps (GroveIdleness, its extra random field maps) get other map numbers, so a save
made inside one can open the wrong map.
- RolePlayS weapons and armour get no quality tiers, and the tiers of the gear it changes keep the
old stats.
In the right order, both drop: RolePlayS's quest skins (Wild Boar Skin, Rabbit Skin, only during
its guild quests, only for handing in) and LonaCraft's Hide and Bone (always).
If the order is wrong, LonaCraft writes one line to the console at start and shows the game's
message box ("LonaCraft should load after the mods listed below...") naming RolePlayS, the same check
it already makes for Lona Big Booba (`LonaCraft::LOAD_AFTER`, `Scripts/0_Core.rb`).
## Localization
- Texts live in `Text/<lang>/*.txt`, one folder per game language: ENG, CHT, KOR, RUS, UKR (the game lists
the folders of its own `Text/`; there is no other language code). Files: Bases, Craft, Furniture, Homes, Info,
Items, Maid, Menu, Mercs, Nodes, Raids, Sewer, Station, Tiers.
- Key format: `LonaCraft:<File>:<id>` reads block `<id>` of `Text/<lang>/<File>.txt`. A block is the key line,
the text lines, then a blank line; `#` lines are comments. No ASCII colon in text lines (the game reads
`a: b` as speaker `a`); `\optB[..]` lists keep the same number and order of entries as ENG. UTF-8, no BOM, LF.
- Fallback rule (`Scripts/15_Text.rb`): a LonaCraft key that is missing or empty in the chosen language, or
a language file that does not exist, shows the ENG text of the same file instead of the raw key or an
error box. One console line per missing key. Other mods' and the game's texts are not affected.
- Status: ENG is the original. CHT, KOR, RUS and UKR are machine-translated by Claude (every key,
marked by the first comment line of each file, not reviewed by native speakers); a reviewer edits the
text lines and deletes that comment line.
- Tier name template: `Tiers:Name/format` (`Text/<lang>/Tiers.txt`, default `%s (%s)`: item name, then tier
name) is read by `LonaCraft::Tiers.name_with_tier` (`Scripts/50_Tiers.rb`) for every displayed name
(variants and the Common base) through `$game_text`, so it has the ENG fallback; it needs exactly two
`%s`, otherwise the English shape is used. The description's tier line uses `Desc/header` (`%s` = tier name).
- Checker: `python tools/check_text.py [--lang CHT] [--quiet]` lists missing keys, extra keys, keys equal
to ENG (untranslated), text lines with a colon, CR characters and BOMs per language, and compares every
key with ENG for body line count, `\n`, `\narr`, `\}`, `\optB` lists and entry counts, `#{..}`
expressions, `\c[..]` codes, `%s`/`%d`, NUM, HP_NOW, HP_MAX and `[`/`]`/empty entries inside `\optB`.
It exits 1 when a key is missing or a control code differs.
## Compatibility
- Works with or without RolePlayS.
- LonaCraft no longer replaces `Data/HCGframes/Command_DarkPot.rb`. If another mod does, every pot
and the Cook of the Stove and the Cooking Fire run that mod's version, in any load order.
- Icons: the mod pastes `Graphics/System/Iconset_LonaCraft.png` below the game's icon sheet.
- Ground pictures: every item's ground-drop event (a clone of the game's `ItemRawMeat` drop, 0_Core.rb
`register_drop_events`) gets the item's own cell of `Graphics/Characters/LonaCraft_drops.png` (12 x 8
cells of 32 x 32, the 24 x 24 icon bottom-centred) from `LonaCraft_drops.json` (item_name -> [sheet,
index, direction, pattern]). The drop init `batch_itemDropitem` (480_EventCharacterBatch.rb:79-87) sets
only offset, mirror and z, so the page graphic is what shows. Both files are made by
`tools/build_drop_sheet.py` from `0_Core.rb` ITEMS cells and the furniture JSON `icon_index`; rerun it
after adding an item (one sheet holds 96; more go to `LonaCraft_drops2.png`). An item missing from the
table keeps the raw-meat picture and is listed in one console line. Drops already lying on a saved map
keep the picture they had until picked up.
To replace the placeholder icons, keep the file 384 px wide, 24 px per icon, icons in order
Plank, Hide, Leather, Bone, Iron Ingot, Cloth Bolt, Rope, Stone Block, Glass, Nails, Iron Ore, Rough Stone
(cells 0-11), Hatchet (cell 12).
## Debug switch and self-test
**Switch.** `Scripts/05_Config.rb` (loaded right after `0_Core.rb`) reads `Config/LonaCraft.json`
once per start with the strict `ConfigJSON` parser (`//` comments allowed): keys `debug`
(default `false`), `self_test` (default `true`), `self_test_log` (default
`"UserData/LonaCraft_selftest.log"`). The file loads before `55_Recipes.rb` (the parser), so the
first `LonaCraft::Config.get` / `LonaCraft.debug?` after that reads the file (`110_Bases.rb` at
its load, else `98_SelfTest.rb`, which calls `Config.load` when it loads), all before
`DataManager.load_mod_database`. A missing file = defaults; an unreadable file or a wrong value
= defaults plus a console line `LonaCraft Config: ...`; unknown keys get a console line. API:
`LonaCraft.debug?` (true only for `"debug": true`), `LonaCraft::Config.get(key, default)`,
`Config.status` (one line for the log), `Config.load(true)` reads it again. The developer build
ships `"debug": true`; the player default is `false` (the release script should flip it).
**Debug keys** (`Scripts/95_Debug.rb`): `LonaCraft::Debug.enabled?` = `LonaCraft.debug?` (was the
constant `LonaCraft::DEBUG`); `Debug.active?` adds the map conditions. `110_Bases.rb` (Numpad /)
and `120_Raids.rb` (Numpad .) take the same switch through their `DEBUG` constant
(`DEBUG = LonaCraft.debug?`, read at their load). On the map, with no message or event running:
| Key | Effect |
|---|---|
| Numpad 0 | +10 of every material (all 12, incl. Iron Ore and Rough Stone), of the Hatchet and of the three building pieces |
| Numpad 1 | +10 of every furniture and decoration item (incl. the four stations) |
| Numpad 3 | +10 Wooden Club, Crystal Ore, Apple, Herb Sta |
| Numpad 5 | own the shack and the stone house, rent the tavern room for 52 weeks |
| Numpad 9 or Numpad + | crafting level +1 |
| Numpad 7 or Numpad - | crafting level -1 |
| Numpad * | reload the recipes (`Recipes/*.json`, `Config/Recipes.json`; rewrites `Config/Recipes_defaults.json` if it changed) |
| Numpad / | bases: add or remove a debug piece on a field map, or tell about the world-map tile (`110_Bases.rb`, see "Bases") |
| Numpad . | raids: on a base map, pick a scenario and a group and start that raid now (`120_Raids.rb`, see "Raids") |
**Self-test** (`Scripts/98_SelfTest.rb`, loaded last). Its `DataManager.load_mod_database` alias
is the outermost LonaCraft one, so it runs once per start after every LonaCraft part (and every
mod before LonaCraft) has loaded its data, and only when `debug` and `self_test` are both true.
`$game_text` is up by then (`5_DataManager.rb:115`, `load_core_data`). Each check is
`check(group, name){ ... }`: `nil`/`true` = pass, a String = fail with that reason,
`skip("why")` = not applicable (not counted), `note("text")` = pass with a note; an exception
(StandardError, ScriptError, SystemStackError) is a failure with its text and first backtrace
line. The run itself is wrapped the same way, so the boot never stops.
| Group | What | Source of the expectation |
|---|---|---|
| methods | 85 rows: every saved original of a LonaCraft alias (the hook is installed) and every game method the mod calls, with the B.0.10.8.26 arity | `METHODS` rows cite `file.rb:line` in `Data/Scripts` |
| input / settings / globals | `Input` symbols (`KEYMAP`, `SYM_KEYS`, `InputUtils` lists), `System_Settings` z constants, `$data_*`, `$mod_load_script`, `$mod_manager` entry | the scripts that read them |
| items / npcs / eventlib / barters | item names (fixed list, `PROCESS_RECIPES`, mining, nodes, debug inputs, shop adds, base pieces; each `Recipes/*.json` whose `requires` are met), `HUNTING_DROPS` NPCs and their merged drops, EventLib templates and the events LonaCraft made, raid extra units, sewer population, shop entries merged | the mod's own tables, read at run time |
| sheets / tilesets | `Graphics/Characters` sheets the mod names, the mod's PNGs, the icon sheet cells, the game Iconset width and `ICON_BASE_FALLBACK`, the ground-drop table (every item has a picture, drop events use it), tilesets 1 / 19 / 22 names and sheets, `110_Bases.rb` WALL_KIND / FLOOR_TILE sheets | `TILESETS`, `10_Icons.rb`, `110_Bases.rb` |
| maps / files | map ids 2, 59, 53, 43, 62, 15, 195 by name (+ tileset), NoerTavern doors 54/55 `!Door4`, r-map families of `45_Nodes.rb`, the mod's `Maps/*.rvdata2`, home and Deep Sewer registration, the game scripts run or redirected (`$mod_load_script` points at the mod's wrapper), every `Data/Scripts` file cited in `METHODS` | `MAPS`, `MAP_EVENTS`, `GAME_FILES` |
| text / json / ids / places / save / loader | text keys named literally in the loaded scripts and `HCGframes` (`"LonaCraft:F:id"`, `text_key("id")` with the receiver's `TEXT`, `TextFallback.get`) exist in `Text/ENG`; every `Recipes/`, `Config/`, `Item/` JSON and `_ModInfo.json` parses; materials and furniture have ids; no duplicate item names; `TOWN_STATIONS` footprints free and walkable (or an event to hook); home door tiles event-free, room seed walkable; save registry; every `Scripts/*.rb` in `loader.rb`, order rules | `LOAD_ORDER` |
| runtime | recipes built and per station, tier variants, salvage recipes and plants, modules loaded, Bases/Raids answer, `RecipeConfig.defaults_text` and `Raids.defaults_text` parse, config status | `55_Recipes.rb`, `50_Tiers.rb`, `120_Raids.rb` |
Map data: `load_data` of maps 2, 43, 59, 62 (cached for the run, then dropped) and the mod's own
maps; nothing is drawn. Files on disk under `Data/` are skipped in a packed game
(`FileGetter::COMPRESSED`).
Report: `self_test_log` (overwritten, UTF-8, LF): date, `DataManager.export_full_ver_info` and
`$data_system.version_id`, mod version from `_ModInfo.json`, config status, mod load order, the
LonaCraft script order, the result line, FAILURES, then ALL CHECKS (pass / FAIL / skip with the
reason). On any failure: one `msgbox` "LonaCraft self-test: N of M checks failed. See <log>."
(the part after the colon is `LonaCraft:Info:SelfTest/failed`, `%d of %d ... %s`) and one
console line per failure; else one console line "LonaCraft self-test: M checks passed (K skipped,
T ms), log <path>". `LonaCraft::SelfTest.results` keeps the rows; `SelfTest.run` runs it again
(e.g. from the console).
Adding a check: one row in the matching table, or a new `check(...)` call in `run_checks`
(groups in the table above). Keep `98_SelfTest.rb` plain ASCII (the game evaluates it as binary
text) and the "where" column pointing at the file and line the expectation comes from.