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

76 KiB

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):

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

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