Files
LonaRPG-Online-Games/ModScripts/_Mods/LonaCraft/README.md
T

914 lines
62 KiB
Markdown
Raw Normal View History

2026-10-29 21:59:06 +04:00
## LonaCraft 1.1.0 — кооператив на уровне мода (game_online 2026-10-09)
Добавлен `Scripts/180_OnlineSync.rb`: синхронизация мебели и строительных плиток на одной
сетевой карте через уже существующий `deistvia`, объявление новой базы и запрос состояния
при входе. Все игроки должны установить одну и ту же версию мода. Полноценные серверные
сохранения, содержимое сундуков, крафт/инвентарь других игроков и рейды не синхронизируются.
Это тестовый P2P-слой поверх клиентского ретранслятора; серверной гарантии нет.
**Русская инструкция с ограничениями: `ONLINE_RU.md`.**
## Ruby 3.1.0 / game_online compatibility update (1.0.3)
- The mod loads the game's `Ruby310Compat` compatibility module at startup
(`Scripts/01_Ruby310Runtime.rb`) and reports a clear error if it is absent.
- Ruby 3.1 keyword arguments and blocks now pass through the Game_Date hooks
(Homes, AwayRaids, Mercs, Maid) and the main-menu content hook.
- Keeps the `Scene_Menu#create_contents` / `create_menu` fix from 1.0.2.
- Supports RUS2 -> RUS -> ENG localization.
- **Game.exe is not provided** in the source game archive. This mod cannot
install or switch the embedded Ruby runtime. Use a Ruby 3.1.0-enabled
mkxp-z game executable to run these scripts. Ruby 3.10 is not the same
version string as Ruby 3.1.0.
## Online build / RUS2 / Ruby 3.1.0 patch (1.0.2)
This revision fixes startup on the 2026-10-09 online build: its
`Scene_Menu` no longer provides `init_contents`. LonaCraft now hooks both
`create_menu` and `create_contents` to insert the Craft command and matching
page after Items, while keeping compatibility with LonaPaletteStudio.
`Menu_LonaCraft#initialize` also now matches the game's zero-argument
`Menu_ContentBase#initialize`. `Text/RUS2` translations are included.
These are script compatibility changes for the game's Ruby 3.1.0 integration,
not a replacement of the Ruby runtime.
# LonaCraft 1.0.1 — game_online 2026-10-09 / Ruby 3.1.0 / RUS2
A crafting and building mod for LonaRPG (tested on B.0.10.8.27, also runs on B.0.10.8.26). Lona
gathers materials, crafts weapons, armour and furniture in five quality tiers, buys a house in Noer
or rents an inn room, and builds a walled base out in the wild that raiders may attack at night;
mercenaries can guard it and a maid can keep it. You can start with no gold at all: pick up
stones, twist rope from plants, make a hatchet by hand and work your way up from there.
## Online build compatibility
For the provided `game_online(20261009-013431)` data build, the LonaCraft
Russian translation is now also provided under `Text/RUS2/`. Text lookups
fallback from RUS2 to RUS, then ENG if a key or file is absent. This mod
uses the game's existing `Ruby310Compat` (Ruby **3.1.0**) layer and does not
ship or replace Ruby binaries. Existing multiplayer/NoerHome scripts are not
overwritten by this package. Syntax and text checks were performed offline;
full runtime and server-side persistence have not been verified.
## Requirements and install
- LonaRPG **B.0.10.8.27** (tested; B.0.10.8.26 works too; the mod asks for game version 0.990 or newer).
- Optional: **RolePlayS** (arrows, axes and drops work together, see "Compatibility").
1. Unzip the release zip straight into your game folder (the folder that holds `Game.exe`), so
you get `ModScripts/_Mods/LonaCraft/_ModInfo.json`. (By hand: put the `LonaCraft` folder in
`ModScripts/_Mods/`.) `INSTALL.txt` in the zip has the same steps. Updating: delete the old
`ModScripts/_Mods/LonaCraft` folder first (keep your own `Config/*.json` changes); saves keep working.
2. Start the game, open the **Mods** menu and enable **LonaCraft**.
3. **Load order: LonaCraft goes last.** RolePlayS and Lona Big Booba must load *before* it. In the
Mods menu, move LonaCraft to the bottom, then restart the game. (In `UserData/GameMods.ini`
this means LonaCraft has the highest `LoadOrder` number; never give two mods the same number.)
If RolePlayS or Lona Big Booba loads after LonaCraft, a console line and a message box at start
say "LonaCraft should load after the mods listed below. Open the Mods menu, move LonaCraft to the
bottom and restart the game." and name them. In the wrong order animals can stop dropping Hide and
Bone, RolePlayS gear gets no tiers and Maani's menu can break. Pick the order once and keep it.
## Compatibility
- **Game:** tested on LonaRPG B.0.10.8.27; B.0.10.8.26 works too. A later game update can break
what the mod hooks into: the self-test (see "Debug and self-test") lists what changed.
- **RolePlayS** (optional, tested with 0.7.8.8): its Light, Medium and Fire arrows become
craftable, its Lumberjack Axe and Poleaxe chop trees, the Hatchet borrows its axe picture and
swing, its gear gets quality tiers and recipes, and animals drop both mods' hides. Details in
"Other mods".
- **Lona Booba Graphics** (listed as "Lona Big Booba" in the Mods menu): works; load it before
LonaCraft.
- **Load order:** LonaCraft last, below RolePlayS and Lona Big Booba. Gear from other mods gets
recipes and tiers when they load before LonaCraft.
## Languages
LonaCraft ships English, Traditional Chinese, Korean, Russian (RUS and RUS2) and Ukrainian and always uses the language chosen in the game's own settings (title Options, first-time setup, or the System page of the in-game menu); it has no language setting of its own. After a switch, every LonaCraft screen opened from then on is in the new language; close and reopen the main menu to refresh its row names, and restart the game when it asks you to, as it does for its own texts and fonts. If you pick a language LonaCraft does not ship (for example a community translation of the game), LonaCraft shows its English texts. There is no error box, and the rest of the game stays in your language. The non-English texts are machine translations and have not been reviewed by native speakers.
## Quick start (no gold needed)
1. On the plains, roads and other wild maps, look for **loose stones** on the ground. Face one and
press the action key: 1 Rough Stone, no tool needed. Collect 2.
2. Open the main menu, choose **Craft** (right under Items). This is crafting *by hand*.
Make **Rope** from 4 plants or herbs (fruit, vegetables, mushrooms, nuts, herbs, mixed is fine).
3. By hand, make a **Hatchet** from 1 Wooden Club (Lona starts with one), 2 Rough Stone and 1 Rope.
4. Equip the Hatchet in your main hand (it is a weak weapon) and chop trees: they give Wooden Clubs.
5. By hand, turn each Wooden Club into **2 Planks**, and make more Rope.
6. By hand, make the **Carpentry Bench** (6 Planks, 2 Rope). Place it in a home or a base
(see "Furniture" and "Bases").
7. From the bench, build up: cut Rough Stone into Stone Blocks, build a **Furnace**, smelt Iron
Ore into Iron Ingots, build an **Anvil**, and with Cloth Bolts build a **Tailor's Table**.
Before you own a bench, Noer has a free **Furnace** and **Anvil** in the blacksmith's back room
and a **Tailor's Table** beside the dress trader in the market.
## Crafting
**By hand.** Main menu, **Craft**. The hand list is short and everything made by hand is
Common: Planks, Rope, the Hatchet (always plain, no quality tiers), the Carpentry Bench, the Bedroll, the Cooking Fire, the three
base pieces (Palisade Wall, Plank Floor, Wooden Door) and, with RolePlayS, Light Arrows.
It is refused in combat ("Not now, there are enemies nearby"), on the world map ("Find a place
to sit down first") and when you are not playing Lona ("Only Lona can craft").
Crafting by hand costs a little more than at a bench: every material is multiplied by 1.25 and
rounded up (a recipe that takes 6 Plank and 2 Rope at the Carpentry Bench takes 8 Plank and 3 Rope
by hand). The crafting screen shows the amounts for the place you are crafting at, with a note in
the Materials line when they are raised. Processing counts too: by hand 2 Wooden Clubs (not 1) make
2 Planks, so planks go twice as far at a bench. Building a base piece on the spot (Bases) pays the
bench amounts. Change the number with `stations.hand.cost` in `Config/Recipes.json` (1 = no
surcharge).
**Stations.** Walk up to a station, press the action key and choose **Craft**. Each station only
lists its own recipes.
| Station | Built from | What it makes |
|---|---|---|
| By hand (main menu) | - | the starter list above, always Common |
| Carpentry Bench | 6 Plank, 2 Rope | Planks, Stone Blocks, all furniture and decorations, base pieces, wooden weapons and shields; salvages wood |
| Furnace | 6 Stone Block, 8 Rough Stone | Iron Ingots, Glass |
| Anvil | 3 Iron Ingot, 2 Plank | Nails, metal weapons and armour; salvages metal |
| Tailor's Table | 4 Plank, 2 Rope, 3 Cloth Bolt | Cloth Bolts, Rope, Leather, cloth and leather gear; salvages cloth and leather |
Gear goes to the station of its main material (wood, metal, or cloth and leather); gear from the
game and from mods loaded before LonaCraft gets a recipe automatically from what it is made of.
Bows (the Long Bow and every other bow weapon, not crossbows) also take 1 Rope for the string, on
top of their Planks.
The game's dark pots and stoves, and the Stove and Cooking Fire furniture, only **cook**.
**The crafting screen.** The left side lists recipes grouped as Processing, Weapons, Ammo, Armour,
Building, Furniture and Decorations; dimmed rows are ones you cannot afford yet. The right side shows
the materials (have / need, red when short; "By hand, materials x1.25" shows when the amounts are
raised), the skill needed against yours, the chance of each
quality tier, and for gear what the Common version gives.
| Key | Crafting screen |
|---|---|
| OK, or left click on a recipe | craft it |
| Cancel / Esc, right click, or "Cancel" at the top right | leave |
| Up / Down, Page Up / Page Down, mouse wheel | scroll the list |
Crafting costs stamina (1 per material for gear and furniture, 1 per processing recipe; counted on
the bench amounts, also by hand) and needs stamina above 0 ("Lona is too tired to work.").
**Quality tiers.** Crafted weapons and armour roll a tier. Names show it: "Short Sword (Rare)".
| Tier | Colour | Price | ATK / DEF | 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 |
Furniture, materials, base pieces and arrows are always Common.
**Crafting skill.** Level 0 to 20. Every craft gives experience (gear and furniture more than
processing); "Crafting skill up" pops up on a level-up. Half of Lona's Survival is added to your
level. Higher skill means better tier chances. Recipes above your skill are hidden until you reach
them. With RolePlayS each craft also gives a little Survival experience.
**Salvage.** The Carpentry Bench, Anvil and Tailor's Table have a **Salvage** choice with a box of
their own: "Add/Remove equipment", then "Break it down!". Each station only takes apart gear of its
own material (wood, metal, or cloth and leather); the rest stays in the box. You get Planks, Iron
Ingots, Cloth Bolts or Leather (heavy metal gear also gives Nails), never more than a quarter of the
item's price. Very cheap gear gives nothing. 1 stamina per item. The salvage box is shared by every
station of the same kind.
## Materials
| Material | Where it comes from |
|---|---|
| Rough Stone | loose stones (no tool); boulders (pickaxe); a chance when mining ore |
| Iron Ore | a chance when mining ore and boulders |
| Wooden Club (game item) | chopping trees (needs an axe in hand); shops |
| Plank | 1 Wooden Club -> 2 (by hand, Carpentry Bench); salvaging wooden gear |
| Stone Block | 2 Rough Stone -> 1 (Carpentry Bench) |
| Iron Ingot | Noer blacksmith; 2 Iron Ore + 1 Wooden Club -> 1 (Furnace); salvaging metal gear |
| Nails | 1 Iron Ingot -> 4 (Anvil) |
| Glass | 2 Crystal Ore + 1 Wooden Club -> 1 (Furnace) |
| Hide, Bone | hunting: boars, rabbits, dogs, wolves, horses, apes |
| Leather | 2 Hide -> 1 (Tailor's Table); salvaging leather gear |
| Cloth Bolt | dress traders (Noer market); 4 plants -> 1 (Tailor's Table); salvaging cloth gear |
| Rope | 4 plants -> 1 (by hand, Tailor's Table); 3 Cloth Bolt -> 1 (Tailor's Table) |
| Hatchet (main-hand weapon) | Noer blacksmith and weapon traders (198 before markup, the price floor); by hand or at the bench |
"Plants" means any plant or herb the dark pot knows; the cheapest ones you carry are used first.
Most materials can also be bought, a few at a time, see "Shops".
## Shops
The game's traders sell LonaCraft's materials, the base building pieces and two pieces of furniture,
a few units at a time: the amount is drawn when the trader restocks (every few days, after a nap), so
gathering stays worth it. A trader asks the base price times the game's difficulty markup
(x1.00 to x1.10), like the game's own rows. The base price is the item's own price, but never less
than what its inputs cost (price floor, below). Bone is never sold (hunting only); the other furniture is
crafted only. The general traders are the carriage receptionists (their "Barter": food, the Wooden
Club, travel tickets), one at every hub.
| Trader (barter name) | Sells: units per restock (base price) |
|---|---|
| Carriage receptionists at the Noer relay, Noer dock, Pirate's Bane, Doom Fortress, Fish Town ferry, south front line, north front-line dock and bridge bunker (`RelayEmp_*`) | Plank 4-8 (60), Rope 3-6 (40), Nails 5-10 (110\*), Rough Stone 5-10 (10), Bedroll 1-2 (220\*), Storage Chest 1 (1210\*) |
| Noer relay only (`RelayEmp_Noer`), as well | Palisade Wall 1-3 (176\*), Plank Floor 1-3 (132\*), Wooden Door 1 (242\*), Stone Wall 1-2 (300) |
| Noer blacksmith (`NoerBlackSmithShopTrader`) | Iron Ingot 2-5 (400), Hatchet 1 (198\*), Iron Ore 3-6 (120), Nails 5-10 (110\*), Glass 3-5 (572\*), Stone Block 4-8 (30) |
| Dress traders: Noer market and other towns (`CommonDressTrader`), south front line (`SFL_CommonDressTrader`) | Cloth Bolt 3-8 (60), Hide 3-6 (80), Leather 3-5 (176\*) |
| Fish Town leather trader (`FishTownLeather_Trader`) | Hide 3-6 (80), Leather 3-5 (176\*) |
| Weapon traders: Noer market, wandering merchants, north front-line dock (`CommonWeaponTrader`, `NorthFL_Dock_WeaponTrader`), Fish Town (`FishKindWeaponry`) | Hatchet 1 (198\*) |
\* raised by the price floor (with the game's own item prices; another mod that changes an input's
price changes the floor too).
**Price floor.** A built item is never cheaper at a trader than what goes into it: an item that
has a recipe is never sold below its input cost x 1.10. The input
cost is that of the cheapest recipe making it, at the bench amounts (not the x1.25 by hand): each
input at its own price, or at what its own inputs cost when that is higher (a Nail is a quarter of
an Iron Ingot, 100, not its own 25); plants count 0; a Plank counts as half a bought Wooden Club.
Only the trader's price changes: what an item sells for, and its salvage, stay as they were. At
start the console names every raised item (`LonaCraft Shops: ItemLonaCraftGlass price floored to
572 (inputs 520)`) and the count. `"price_floor_margin"` in `Config/Shops.json` sets the factor
(default 1.1, from 1 to 10; 0 turns the floor off); it also applies to rows of your own, so a
`"price"` below the floor is raised.
The rows are added to each trader's list, never in place of it: the game's own stock and RolePlayS's
additions stay, and a row whose item the trader already sells is skipped (console line). A trader
keeps its stock until it restocks, so in a running save the new rows show after that.
**`Config/Shops.json`** changes the rows (see "Config files"); the table above is the default.
## Boulders, loose stones and the axe
**Loose stones** lie on the ground of the plains, roads, badlands, forests, mountains and deserts,
1 to 3 per visit, fresh every time you enter from the world map. Face one, press the action key:
1 Rough Stone. You can walk over them.
**Boulders** stand on the same wild maps (not the roads), 1 to 4 per visit. They need a **pickaxe**
held in the main hand; in the bag it does not count ("Need a pickaxe in hand to break this."). Each
swing costs 1 stamina; 9 hits break a boulder for 4 Rough Stone in all, with a 15% chance of Iron Ore on each drop. Pickaxes
are sold by the Noer blacksmith and the weapon traders.
**The axe rule.** Trees that give wood need an axe held in the main hand: the Hatchet, or with
RolePlayS its Lumberjack Axe or Poleaxe. An axe in the bag does not count. Without one Lona says
"Need an axe in hand to cut wood." Fruit trees still give fruit by hand.
**The Hatchet** is a main-hand weapon, the weakest axe: ATK +1, Weak -4, Sexy -5. In Lona's hand
it shows RolePlayS's Lumberjack Axe picture and swing when RolePlayS is loaded, else the Wooden
Club's picture and swing (the game has no axe picture). Its stats stay the same either way.
A Hatchet carried in a save from before this change becomes the weapon when the save loads.
## Homes
| Home | Cost | From | Where |
|---|---|---|---|
| Old Shack | buy, 5 Gold Coins | Maani, the bank clerk | Noer, bottom-left corner of the city |
| Stone House | buy, 15 Gold Coins | Maani, the bank clerk | Noer, middle of the city, two tiles left of the tavern |
| Upstairs Room | rent, 2 Large Copper Coins a week | Boss Mama, the tavern keeper | the Noer tavern, the room right of Cocona's |
| Pirate's Bane Room | rent, 3 Large Copper Coins a week | the innkeeper | Pirate's Bane inn, the right one of the three bedrooms at the top |
| Doom Fortress Room | rent, 2 Large Copper Coins a week | the innkeeper | Doom Fortress inn, the middle bedroom at the top |
| Fish Town Room | rent, 4 Large Copper Coins a week | the Deepone innkeeper | Fish Town inn, the bottom-left room |
| Camp Room | rent, 8 Copper Coins a week | the guard who keeps the inn | the south front-line camp's inn, the top-left room |
| Coastal Fortress Room | rent, 1 Large Copper Coin a week | the innkeeper | Coastal Fortress inn, the right one of the three bedrooms at the top |
**Buying.** Maani's menu gets "Buy shack 5 gold" and "Buy stone house 15 gold" until you own them
(Gold Coins only). The house is then a door on the Noer map: before you buy it, "Locked. The bank
sells this house."; after, Enter / Leave. Both are empty rooms for you to furnish. Sleeping on your
own bed there is the inn's rest at home: full health and stamina, a meal from a chest of cooked
dishes and a bath from a trough or tub in the house (see "Rest").
**Renting.** Boss Mama's menu gets "Rent room 2 LC a week", then 1 / 2 / 4 weeks. While rented
she also offers "Extend rent" and "Rent status" ("The room is yours for N more days"). The room's
own bed and things are cleared and you furnish it yourself. Sleeping on your bed there is the
inn's full paid sleep (meal, bath, full restore) without a key. When the rent runs out you see
"Your room rent ran out. Boss Mama is holding your belongings."; get everything back with
"Collect belongings" in her menu.
**The other inns.** Every inn of the game rents its paid bedroom the same way: the keeper's menu
gets "Rent room <price> a week", then 1 / 2 / 4 weeks, "Extend rent", "Rent status" and "Collect
belongings". While rented, the inn's own bed, bucket, table and torch are gone and the room is
yours to furnish (furniture on the room's floor, wall decorations on its back wall); sleeping on
your bed there is that inn's paid sleep without a key. When the rent runs out the inn's furniture
is back and the keeper holds your pieces. Each inn's own dangers stay (slavery and low morality are
still punished as in the game).
- **Pirate's Bane** (3 Large Copper a week): the right one of the three small bedrooms at the top of
the inn, behind the curtained door; 6 tiles.
- **Doom Fortress** (2 Large Copper a week): the middle bedroom at the top, its door at the bottom
of a short passage; 8 tiles.
- **Coastal Fortress** (1 Large Copper a week): the right bedroom at the top; the wall torch above
the table goes; 8 tiles.
- **South front-line camp** (8 Copper Coins a week, "8 CC a week"): the top-left room of the camp's
inn; its carpet stays, the torch stand goes; 8 tiles.
- **Fish Town** (4 Large Copper a week): the bottom-left room of the inn; the Deepone keeper only
serves Lona when she is not a slave; 9 tiles.
## Furniture
54 pieces: beds, a bedroll, chests, tables, chairs, the four stations, a stove, a cooking fire, a
water trough, lamps, torches, rugs, racks, banners, trophies and more. Most are made at the
Carpentry Bench; the bench, the Bedroll and the Cooking Fire can also be made by hand.
**Where.** In a home you own (the shack, the stone house, a rented inn room while the rent
runs) or in a base out in the wild. Anywhere else: "You can only furnish a home you own or a base
of yours out in the wild." Never on the world map or in combat.
**Placing.** Open the inventory and *use* the piece (hotkey slots do not place furniture). A
see-through copy appears in front of Lona.
| Key | Placing furniture |
|---|---|
| Arrow keys | move it (up to 3 tiles from Lona) |
| OK | place it here (a buzzer where it cannot go) |
| Cancel | stop; nothing is used |
The piece needs free floor under all its tiles. A rug can lie under a table. Wall pieces
(banners, paintings, trophies, the shrine, wall torches and candles) hang on a back wall of a
home (not on windows) or on the outer face of a palisade wall.
**Using.** Walk up to a piece and press the action key: **Sleep** (beds, Bedroll; the game's own
sleep), **Open** (Storage Chest, Narrow Table; each has its own box), **Craft** / **Salvage**
(stations), **Cook** (Stove, Cooking Fire), **Bathe** (Water Trough, Wooden Tub). Lamps, torches, the Furnace,
the Stove and the Cooking Fire give light. **Pick up** puts a piece back in your inventory (empty a
chest first). The town stations in Noer cannot be picked up.
## Bases
**Where you can build.** On a wild world-map tile you entered the plain way (not through an
encounter or an event): plains, roads, forests, mountains, swamps, shores, wastelands and the
Abandoned House area. Not in Noer, not in towns, camps or other settlements, not on a tile with a
place on it. Otherwise: "Lona can only build out in the wild, on a map she walked into from the
world map."
**Names.** Every base gets a name when it is founded, from its land: "Plains camp", "Forest
camp", "Mountain camp", "Desert camp", "Swamp camp", "Roadside camp", "Abandoned house", "Deep
Sewer" and so on; a second base with the same name gets its world-map tile added ("Plains camp
31-92"). To rename one, stand on its world-map tile (or use its marker) and pick "Rename base" in
the tile menu; in the Deep Sewer the line is on every ladder. The game's name-entry screen opens;
at most 16 letters, and commas, brackets and colons are left out. The names show in the
mercenary menus and in the away-raid reports.
**The pieces** (by hand or at the Carpentry Bench; the Stone Wall at the bench only):
| Piece | Cost | What it is |
|---|---|---|
| Palisade Wall | 2 Planks, 1 Rope | a wooden wall; walls side by side join up |
| Stone Wall | 3 Stone Blocks, 1 Rope (Carpentry Bench) | a stone wall, twice the palisade's HP; stone joins stone, palisade joins palisade |
| Plank Floor | 2 Planks | weathered boards, the same as the floor of Lona's shack |
| Wooden Door | 3 Planks, 1 Rope | a door that opens with the action key, in a palisade or a stone wall |
**Build mode.** Use any of the four pieces from the inventory on a wild map (or choose "Build mode"
on a wall or floor you built). A yellow frame means the piece can go there, red means it cannot. A
box at the top right shows the piece, its cost and how many you can build now. Pieces are built and
paid at once: ready-made pieces in your bag are used first, then raw materials. Stone Walls are
made at the Carpentry Bench, so build mode places only the ones in your bag ("made at the bench" in
the box) and gives them back when taken down.
| Key | Build mode |
|---|---|
| Arrow keys | move the cursor (up to 9 tiles left and right, 5 up and down) |
| L / R (Page Up / Page Down, mouse wheel) | previous / next piece: Palisade, Stone, Floor, Door |
| OK | build here; hold OK while moving to build a line |
| the game's "delete item" key (Space unless changed) | take down the piece under the cursor, materials back |
| Cancel | leave build mode |
Outside build mode, face a wall or floor and press the action key for its menu (its HP, Take down,
Build mode, Repair when damaged).
**How walls look.** Walls are drawn like the game's own buildings: a wall tile shows the top of
the wall, and the tile below it shows the wall's face, so every wall that runs left and right is
**two rows deep** (top, then face) and the room inside starts below the face of the north wall. A
wall that runs up and down shows only its top and ends in a face at its bottom end. Walls of the
same kind join up as you build, in every direction. You cannot walk on the top or through the face.
Every land type, the Deep Sewer included, shows the same two walls: pale planks for the Palisade
and plain grey blocks for the Stone Wall.
**Wall and floor sheets (for modders).** The mod ships its own copy of each wall sheet (A4) and
floor sheet (A5) the bases use, `Graphics/Tilesets/LonaCraft_<sheet>.png`, with the two walls and the
shack's two floor boards painted into tiles no game map uses; `Graphics/Tilesets/LonaCraft_walls.json`
says which tiles (wall top + face for the wood and the stone, two board tiles for the floor). A map
with a base (and the Deep Sewer) shows those copies; every other map keeps the game's sheets. Repaint
those tiles in the PNGs to change how walls and floors look; `tools/build_wall_sheets.py` builds them
again from the game's sheets (developer copy only, not in the release zip). A wall needs open ground below it for its face ("No
room below for the face of the wall.").
**Refusals.** "Too close to the edge of the area" (room is kept outside your walls), "Not where
Lona comes into the area", "Something is already built here", "Not enough materials." and **"Not
while enemies are in the area."**: no building while an NPC that is hostile to Lona is on the map
(goblins, bandits, undead, abominations, fish people, guards that are after her) or while anything,
an animal too, is fighting her or her companions; companions, mercenaries, the maid, traders, wanderers,
guards that leave her alone and wild animals (rabbits, rats, boars, wolves) do not stop her. Build mode
closes by itself when such an enemy turns up.
**Doors.** A door goes into the **face** of a wall that runs left and right: build the wall first,
then put the door on a face tile; Lona walks under the wall above it. In a wall that runs up and
down, leave a gap in the wall and put the door there: it becomes a **sideways door**, edge-on when
closed, swinging to face Lona when opened. Anywhere else: "A door goes into the face of a wall, or
into a wall that runs up and down." Closed: the action key opens it. Open: Close / Take down /
Cancel. In the Deep Sewer (and on any sewer or tomb map) the same Wooden Door shows as an **iron
gate** that drops shut and lifts open. Doors close again each time you enter and after you sleep. Companions never open doors, so
leave one open for them.
**Pin and revert.** Each visit to a wild tile normally gives a random map. Once something is built,
that map is pinned to the tile and you get the same map every time. Resources, animals and weather
still come back as usual. Furniture, stations and chests can be placed anywhere you can build and
count as buildings. When the last piece and the last furniture are gone, the tile turns wild
again ("Nothing is left standing here. The land is wild again."). Every base shows a small fenced
camp **marker** on the world map.
**No spawns inside.** Ground shut in by your walls and closed doors (a gap does not count) never gets
animals, enemies, resources or night groups. They appear outside and can walk in through an open
door or a gap. One exception: if enemies from an earlier night are still on the map when Lona
sleeps, the game's capture scene puts them right next to her.
**Destroy all bases.** Main menu, System page, "Destroy all bases (N)", then Confirm. Every base is
removed, tiles turn wild, built pieces are not refunded; furniture comes back to your inventory with
the contents of its chests.
## Raids
Sleeping in a base can bring a night raid. The game's own danger roll for sleeping outdoors stays;
a bigger base (walls, doors, furniture) adds to it, and bigger bases draw more raiders (at most 12).
Who comes depends on the land: orcs, bandits, undead, wolves, fish people, abominations or spiders.
Guards never raid.
**The warning.** Lona wakes in the night: "Lona wakes with a start. Something is moving out there in
the dark..." The raiders appear at least 8 tiles away and wait 8 seconds (5 in forests; 5 more if
your dog companion growls first).
**The siege.** While Lona is shut in, raiders walk up to the walls and doors between them and her
and hit them about once a second. When a piece breaks it is gone for good ("They have broken
through!") and the fight is on. Walls and closed doors block sight, melee and arrows both ways.
Wolves, weak common mobs and ranged fighters do not break walls; they wait outside.
**Any enemy, not only raiders.** Any hostile that cannot reach Lona through the walls attacks them:
an enemy chasing her when she shuts the door, or the game's own night group after a nap, walks to the
nearest wall or door in its way and hits it as the raiders do (same HP, armour and difficulty), and
keeps after her while it works instead of losing interest. Enemies that have not noticed her keep
wandering; traders, wanderers and guards who leave her alone are never involved. A broken piece of
any wall, also one running up and down, leaves a gap that Lona and enemies walk through; a rebuilt
piece closes it again.
| Piece | HP | Armour (taken off every hit) |
|---|---|---|
| Palisade Wall | 600 | 3 |
| Stone Wall | 1200 | 8 |
| Wooden Door | 300 | 3 |
| Wooden Door set in Stone Walls | 600 | 6 |
Raiders pick the piece that is quickest to reach and break (walking time plus HP divided by their
damage after armour), so they go for doors and palisade before stone.
**Repair.** The menu of a damaged wall or door offers "Repair (1 Plank)": +150 HP, takes 2 seconds.
A stone wall takes "Repair (1 Stone Block)": +300 HP.
Not while that piece is being hit ("Not while it is being hit."). In build mode, OK on a damaged
piece of the selected kind repairs it. Damage stays until repaired. Sleeping during a raid is
refused: "Not now. They are still out there."
**The end.** "The raid is over." when every raider is down; "The raiders give up and slink off into
the night." after 3 minutes without a breach; or when Lona leaves the map.
If she leaves the map once the warning has come (or while any enemy is besieging her walls), the
raiders still standing carry on at once as an away raid, from the damage already done (see Away raids).
## Difficulty
One level for every base system, set in `Config/Bases.json` and read when the game starts (restart
after editing). It does **not** follow the game's own HARD / HELL / DOOM mode: pick it yourself.
The names only read like the game's modes. The game's HELL and DOOM add danger of their own on top
(about +30 to the danger roll of the first nap after arriving at night, and World Difficulty falls
less after a capture), so a HELL game with the mod on Hell is harder than either alone.
```
"difficulty": {"level": "hell"}
```
- **Hard** (the default): every number as described in the other sections.
- **Hell** and **Doom**: more and earlier raids, more raiders, harder blows, more away raids that
smash and take more, a busier Deep Sewer, dearer mercenaries and maid, rougher nights on the ground.
The console names the level at start: `LonaCraft difficulty: Hell (Config/Bases.json)`. An unknown
name falls back to Hard with a console line.
| What it scales | Knob | Hard | Hell | Doom |
|---|---|---|---|---|
| Danger added to every nap on a base | `roll_add` | 0 | +4 | +8 |
| Base-value bonus to that roll, and its cap | `danger_mult` | x1 (cap 10) | x1.5 (cap 15) | x2 (cap 20) |
| Base value for one extra raider | `extra_per_value_add` | 30 | 25 | 20 |
| Extra raiders at most | `extra_raiders_add` | 4 | 5 | 6 |
| Raiders at most | `max_raiders_add` | 12 | 14 | 16 |
| Wall and door damage a hit | `damage_mult` | x1 | x1.25 | x1.5 |
| Warning before they move | `grace_mult` | 8 s (forest, sewer 5) | x0.85 | x0.7 |
| Siege time before they give up | `give_up_mult` | 3 min | x1.33 | x1.67 |
| Away-raid chance a night | `away_chance_mult` | x1 | x1.5 | x2 |
| Away raid: safe days after founding / after a raid | `away_grace_days_add`, `away_cooldown_days_add` | 1 / 2 | 1 / 2 | 1 / 1 |
| Away raid: blows and strength against the mercenaries | `away_power_mult` | x1 | x1.25 | x1.5 |
| Away raid: smash chance (crafting station) | `smash_add`, `smash_station_add` | 25 % (10 %) | 30 % (12 %) | 40 % (15 %) |
| Away raid: pieces smashed at most | `smash_cap_add` | 3 | 4 | 5 |
| Away raid: share of a chest taken | `loot_add` | 50 % | 60 % | 75 % |
| Deep Sewer nap raid chance, day / night | `sewer_day_add`, `sewer_night_add` | 35 / 60 % | 40 / 70 % | 50 / 80 % |
| Deep Sewer rats, roaches, hobos, goblins | `sewer_pop_mult` | x1 | x1.25 | x1.5 |
| Mercenary contract, 1 / 3 / 7 / 14 days | `merc_price_mult` | 1 / 3 / 7 / 14 | 2 / 4 / 9 / 18 | 2 / 5 / 11 / 21 Large Copper |
| Maid's hire fee | `maid_fee_add` | 5 | 7 | 8 Copper |
| Maid killed when an away raid reaches her | `maid_kill_add` | 50 % | 60 % | 75 % |
| Ground nap: danger added | `ground_danger_add` | 10 | 15 | 20 |
| Ground nap: chance of feeling sick | `ground_sick_add` | 10 % | 15 % | 20 % |
| Bed inside walls: danger kept for the roll | `bed_roll_add` | x0.75 | x0.85 | x0.90 |
The numbers are for the default config. Each level is a table in the same section: a knob ending in
`_add` is added to the number it scales (it may be negative), one ending in `_mult` multiplies it.
`Config/Bases_defaults.json` lists all of them. Change one with, for example,
`"difficulty": {"level": "hell", "hell": {"roll_add": 2}}`. The maid's daily pay, crafting costs,
rents and house prices never change with the level. A contract already paid keeps its days; an
extension costs the price of the level the game started with.
**Danger of one base.** The world-map tile menu of a base has "Danger (Normal)" beside "Rename
base", and so do the Deep Sewer ladders when the sewer has a base. Picking it steps Normal -> Higher
-> Lower -> Normal, with a popup ("This base draws more notice now. More raiders will come."). Not
while raiders are at that base's walls. It stacks with the level:
| Danger | Nap danger | Away-raid chance | Extra raiders at most | Deep Sewer nap chance |
|---|---|---|---|---|
| Lower | -4 | x0.67 | -1 | -10 points |
| Normal | 0 | x1 | 0 | 0 |
| Higher | +4 | x1.5 | +1 | +10 points |
Higher is a pure choice: more raiders mean more drops and kills. Houses and inn rooms have no Danger
line (they are never raided). Saves from before have every base on Normal. The steps are
`"base_danger": {"lower": {...}, "higher": {...}}` in the same section.
Live-raid chance per nap on a base (simulated, World Difficulty 30, survival 5, base value 30, naps
1 to 6 in a row; the first nap after arriving from the world map at night is far riskier, see
`docs/RESEARCH_DIFFICULTY.md`):
| Level | Lower | Normal | Higher |
|---|---|---|---|
| Hard | 7 16 23 26 27 26 % | 10 23 30 32 33 34 % | 14 30 37 39 40 41 % |
| Hell | 11 24 32 34 34 35 % | 15 32 39 40 42 42 % | 19 38 44 47 48 49 % |
| Doom | 17 35 41 44 46 45 % | 21 40 47 50 52 52 % | 25 47 54 57 60 59 % |
## Rest
How well Lona sleeps out in the wild or at home depends on what she sleeps on.
| Where she sleeps | Stamina and health | Mood | Other | Night raid roll |
|---|---|---|---|---|
| Bare ground (the nap skill with no bed) | stamina gain x0.6 and at most 80 % of full; health gain halved | -10 ("Lona slept badly on the bare ground.") | dirt +15; 1 in 10 she feels sick | danger +10 (it stays) |
| Bedroll, the game's camp bed, a Bed outside walls | a plain nap | plain | plain | plain |
| Bed inside walls, or any Bed in a home she owns | full health and stamina, as at the inn | +10 ("Lona slept well in her own bed.") | the meal and the bath below | danger x0.75 for that night |
"Inside walls" is a tile of a base that the outside cannot reach with the doors shut (the same test
that keeps spawns out); in the Old Shack and the Stone House the whole house counts.
**A meal from the chest.** Sleeping in a Bed inside walls, Lona eats one meal from a chest or wardrobe
that is also inside the walls (never from her bag): 30 points of cooked dishes, the smallest single
dish that covers it (a Good Soup before a Meat Salad), else several from the largest down (two Meat
Soups). She wakes fed as at the inn ("Lona ate a meal from the chest."). Cooked dishes are what the
dark pot cooks: Meat Salad 80, Good Soup 32, Smoked Meat 26, Meat Soup 16, Plant Soup 16, Dry Food 16.
Raw food, bread, cheese, sausage, fruit and junk food do not count, nor mystery-meat or human-meat
dishes (`Config/Bases.json` `"rest"` can allow those two). Fewer than 30 points of dishes: nothing is
eaten and there is no refill.
**A bath.** A Water Trough or a Wooden Tub (it now has "Bathe" too) inside the walls: sleeping in the
Bed there washes Lona as the inn does ("Lona washed before bed."), with no scene.
The rented tavern room keeps the inn's own paid sleep; the Deep Sewer keeps its own raid roll.
## Away raids
While Lona is somewhere else, her bases can be raided too. Each game night every base she is not
sleeping on has a chance: 10 % plus up to 10 % more for a big base, x1.5 by a road, in a house
field or in the sewer, half as likely with the mercenaries posted there. A new base is safe its first
day, and a raided base gets two quiet days.
A raid Lona runs from counts as that night's away raid, worked out with the raiders still standing
when she left, and its report starts "You left during the raid. They had the place to themselves."
**What raiders want.** They come for what is inside: chests with something in them, and furniture to
wreck. A base with no furniture and no full chest is left alone ("They found nothing worth taking and
moved on. The walls are untouched."), and walls that enclose nothing are never hit. They break a wall
or a door only to get at something behind it: the cheapest piece of each ring on the way (a door
first), one breach per ring. Their strength is a number of blows for the night (about 24 hits of
their best fighter, more for a bigger band, +-25 %); when it runs out before the next ring opens they
go home with what they have, and the piece they were on keeps its damage.
**Inside.** From each chest they reach they take half its worth, the most valuable things first (coins
go first), as much as they can carry (1,500 a raider, in item value). Each other piece they reach is
smashed one time in four (a crafting station one time in ten), at most 3 pieces a raid; chests are
never smashed. Goblins, orcs, bandits, vagrants and fishkind steal; the undead, wolves and
abominations only smash.
| Door | HP | Armour |
|---|---|---|
| Wooden Door in palisade | 300 | 3 |
| Wooden Door set in Stone Walls (a stone wall above it, or stone above and below a sideways door) | 600 | 6 |
A deeper base is safer: an inner room behind a second ring costs a second breach. A stone keep with
its doors set in stone holds off goblins and most bandit bands.
**Telling Lona.** A raided base's marker on the world map shows a "!" until she reads the report.
Entering the base: "Raiders came here while you were away.", then a report: who came, how long
ago, what broke, what was taken, what was smashed. Broken pieces are gone; damaged ones keep their
damage until repaired. A base with nothing left turns wild.
## Mercenaries
The Mercenary Guild's receptionist in the Noer tavern hires out a squad of three: a captain (great
helm, Noer tabard) and two swords (leather armour, painted shields). Her "anything else" menu gets a
line "Hire mercenaries (1 Large Copper Coin a day)": pick 1, 3, 7 or 14 days, then the base they
guard (by name, newest first, at most 6; with more bases, the 6 she visited last), paid up front. No
base yet: the receptionist sends her to build one first. While hired the line shows the contract
and adds days.
- The squad posts at the chosen base at once and is there the next time Lona arrives, near its
main door (the door nearest where she comes in), never on or beside a door and never against a
wall: each stands at least 2 tiles from every piece of the base and off the three tiles straight
out of each door (a clearing too small for that: the free tile farthest from the door). Build next
to a post and that man picks a new one. They are made again each time she enters or sleeps there.
If that base is gone, they wait at the guild and the receptionist asks for a new post.
- They go after every enemy on the map, not just what they see: anything hostile to Lona (the same
rule that stops building; wild animals only when they attack her side) and anything Lona hits,
animals, traders and guards included, until it dies or she leaves the map. With nothing left they
walk back to their posts and face out. They take no companion slot, ignore the follower calls and
never stop Lona from building.
- Talk to the captain: how the men are, add days (same price), move post (pick another base from
the same list; they march there at once), dismiss (no refund).
- One that falls is down for a day, never dead. Away raids: a posted squad halves the chance of a raid
and fights the raiders first (squad strength 220 against the band's): they win, "The mercenaries
drove them off. Nothing was lost."; they lose, all three are down for a day and the raid goes on
weaker.
- A popup one day before the contract ends, and when it ends; then they are gone.
## Maid
Boss Mama in the Noer tavern can send one of her girls to keep a base or a house Lona owns: her menu
gets "Hire a maid 5 Copper Coin". (While Boss Mama is away from the tavern, the guild receptionist
offers the same line.) Pick the place by name: the list shows your bases, then your houses (the Old
Shack, the Stone House; a rented inn room is not offered). The place needs a Bed or a Bedroll inside its
walls (in a house: anywhere in the house), or Boss Mama says "There is nowhere for her to sleep." and
nothing is paid. She costs 5 Copper Coins to hire and 1 Copper Coin a day, which she takes herself from a chest or
wardrobe inside the walls each morning. After 3 days without wages she leaves ("<name> left. No wages
for 3 days."). Only one maid at a time.
- **At the base.** She is there whenever Lona arrives: in the room with the Stove or Cooking Fire (else
by a bed), never more than 3 tiles from it. She does not fight: when something hostile comes within
6 tiles, or a night raid starts, she runs to the corner of her room farthest from its doors.
- **In a house.** To post her to a house, place a Bed, Dark Bed, Blue Bed or Bedroll in it, then pick
the house at hire or with "Move to another camp or house". The whole house counts as inside the walls:
she takes her wages from its chests and cooks on its Stove or Cooking Fire like at a base. She stands
by the fire (else by a bed) and keeps off the stairs; her hiding corner is the one farthest from the
way out. Raids never come to a house (towns are safe), away raids included.
- **Cooking.** Each morning, with a Stove or Cooking Fire inside the walls, she cooks up to 2 dishes
from the food in the chests inside the walls into the pantry (the chest nearest the fire), the best
the food allows, as the dark pot would: Meat Salad, Good Soup, Smoked Meat, Meat Soup, Plant Soup or
Dry Food. She never cooks human or mystery meat and stops while 6 cooked dishes are inside the
walls. On waking: "<name> cooked Good Soup x2." The Bed's meal from the chest (see "Rest") eats
these dishes, so a maid and a chest of raw food keep Lona fed.
- **Danger.** She is gone for good if she dies: raiders who break in during a night raid can kill her,
and an away raid that reaches her room kills her one time in two (the report says so; mercenaries
that drive the raiders off protect her too). Hire another at Boss Mama.
- **Talk to her:** how things are (days paid, dishes cooked, cooked dishes in the chests, where she
is: "I look after Old Shack."), move to another base or house (the same list, the same bed rule:
"There is nowhere for me to sleep there."), dismiss.
## Deep Sewer
Under Noer lies a sewer of LonaCraft's own, built like the game's sewer: narrow walkways along
channels of sewage that bend, join and end in dead ends, bridges where a walkway needs one, a flooded
basin, and nine sunken pockets (3x3 to 5x4 tiles) behind a ditch and a stair, with room for a bed, a
chest, a bench and a few walls. There are no large open spaces. **In this version you cannot get
in**: the map ships, but its entrances are switched off (see "Ways in").
**Ways in.** None for now. The four grates (slum house, docks, market, back streets) are
switched off in this version (`ENTRANCES_OPEN = false` in `Scripts/130_Sewer.rb`) while the sewer gets
more work; a save made inside can still climb any ladder, which comes out on the world map.
Nothing to buy, nobody owns it.
**What lives there.** Rats, roaches and giant rats (the game's abomination rat) anywhere on the
walkways; 2-4 hobos in the homeless camp (bedrolls, a small fire, barrels and crates) and 2-4 goblins
in the goblin den (stakes, totems, bones, a fire pit, loot sacks). Both lie at least 6 tiles of walkway
from Lona's pockets. Everyone is placed again each time Lona comes down and after each sleep, never
inside her walls.
**Building with others around.** The Deep Sewer is the only place where Lona can build while other
people or animals are on the map. She cannot build while she is in combat or while a hostile (alive,
not her companion) is within 8 tiles: "Not now, something is close." Build mode closes by itself the
moment that happens. Everywhere else the base rule holds ("Not while enemies are in the area.").
The same rule holds for furniture, which goes in the pockets only, not on the walkways, the camp
or the den. Walls and doors that would cut the walkway (or the camp or the den) in two are refused ("That would cut the walkway in two.");
floors go anywhere. Nothing on the tunnel mouths or within 2 tiles of them, nor on or next to a
ladder's landing tile. Palisade and stone walls (mossy sewer stone). The whole sewer is one base: no world-map marker, and
"Destroy all bases" clears it like any other.
**Danger.** When Lona sleeps down there, something comes out of the tunnel mouths 35% of the time
by day and 60% at night: hobos (weight 50), breedlings (30), a pack of giant rats (30) or the walking
dead (10). With a base it is a raid as above (5 seconds of warning); without one they simply come for
her. `Config/Bases.json` scenario "sewer" changes the groups.
**No water.** There is no water down there; bring your own.
**For modders.** Six reserved quest points, a quest spawn region and `on_enter` / `on_setup` /
`on_nap` callbacks let a repeatable quest use the sewer without changing the map: see
`docs/SEWER_QUESTS.md`.
## Config files
Three files in `Config/` hold *your* changes. The mod never writes them. (A fourth,
`Config/LonaCraft.json`, holds the debug switch, see "Debug and self-test".) Restart the game after
editing (or press Numpad * on the map to reload the recipes while debug keys are on).
- **`Config/Recipes.json`**: change any recipe (station, skill, inputs, amount, best tier, group),
switch a recipe off, add a new one, or set what a station does: the best tier it can give
(`stations.<id>.max_tier`, by hand 1 = Common) and its material multiplier
(`stations.<id>.cost`, 1 to 10, by hand 1.25, every other station 1.0; each material is
`ceil(count x cost)`). `"rules": {"bow_rope": 1}` sets the Rope in the automatic bow recipes
(0 = none, up to 5; a bow with Wood 6 or more takes double). Example entry: `{"id": "ItemLonaCraftFurnitureTent", "enabled": false}`.
- **`Config/Bases.json`**: wall and door HP and armour, repair cost and time, and every raid number
(switch raids off with `"raids": {"enabled": false}`, raid chance, warning time, siege time, raider
counts, who can break walls, which groups come where), the away raids (`"away"`) and the
mercenaries (`"mercs"`: price, days, strength), the rest tiers (`"rest"`), the maid (`"maid"`)
and the difficulty level with its tables (`"difficulty"`, see "Difficulty").
- **`Config/Shops.json`**: what the traders sell of the mod's items (see "Shops"). Under
`"traders"`, per barter name, rows `{"item": "ItemLonaCraftPlank", "amount": [4, 8], "price": 60}`
(`amount` a number or `[min, max]` per restock, `price` optional, the base price before the
difficulty markup). A row for an item the defaults already sell there changes only the fields it
gives (`"amount": 0` removes it); a new item is added; `"<trader>": null` removes all the mod's rows
at that trader; `"enabled": false` removes them everywhere. Unknown traders or items are skipped.
`"price_floor_margin": 1.1` is the price floor (see "Shops"): no item with a recipe is sold below
its input cost times that; 0 turns it off.
Each file starts with `//` comment lines explaining every key. At start the game writes
**`Config/Recipes_defaults.json`**, **`Config/Bases_defaults.json`** and **`Config/Shops_defaults.json`**:
every recipe, every setting and every shop row with its current value. Do not edit those; copy only the lines you want to change into your
own file. The parser is strict: a mistake skips that entry (or the whole file, if it cannot be read)
with a line starting "LonaCraft" in the console (`Console.bat`), never a message box.
## Debug and self-test
Everything here is controlled by one switch, `"debug"` in **`Config/LonaCraft.json`**
(read once when the game starts; restart after changing it). **The release ships with
`"debug": false`**: no debug keys, no god mode, no self-test, no crash trace. To turn them on,
open `Config/LonaCraft.json`, change `"debug": false` to `"debug": true` and restart the game.
```json
{
"debug": false,
"self_test": true,
"self_test_log": "UserData/LonaCraft_selftest.log"
}
```
| Key | Default | Meaning |
|---|---|---|
| `debug` | `false` | turns on the numpad debug keys below and, with `self_test`, the start-up self-test |
| `self_test` | `true` | run the self-test at start (only when `debug` is `true`) |
| `self_test_log` | `"UserData/LonaCraft_selftest.log"` | where the self-test writes its report, relative to the game folder |
| `trace` | `true` | with `debug`, the crash trace of the crafting screen (below) |
| `trace_log` | `"UserData/LonaCraft_trace.log"` | where the crash trace is written, relative to the game folder |
| `viewport_guard` | `true` | the viewport guard (below); works with `debug` off too |
A missing file means the defaults (debug off). A file that cannot be read, or a wrong value,
means the default for it plus one line starting "LonaCraft Config" in the console.
**Debug keys** (with `"debug": true`; on the map, with no message or event running):
| Key | Effect |
|---|---|
| Numpad 0 | +10 of every material, the Hatchet and the three base pieces |
| Numpad 1 | +10 of every furniture and decoration piece |
| Numpad 3 | +10 Wooden Club, Crystal Ore, Apple, Herb Sta |
| Numpad 5 | own both houses, 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 and `Config/Recipes.json` |
| Numpad / | bases: add or remove an invisible test piece; on the world map, tell whether the tile can hold a base |
| Numpad . | raids: on a base map, choose a raid and start it now; anywhere else, an away raid on a chosen base now, hire the squad for 3 days free, or hire a maid free |
| Home | god mode on / off (popup "God mode ON" / "God mode OFF", not saved, off at every start): building, single placement, furniture placement, repairs and crafting by hand or at any station take no materials and pass every "not enough" check (the crafting level still applies; coins for rent, mercenaries and the maid are still paid); Lona takes no damage from hits, and her health, stamina and satiety stay at their maximums, naps included. Off again: nothing is refunded or charged afterwards. Home because the numpad keys are all taken and Numpad Enter is the same key as Enter |
**Self-test** (with `"debug": true` and `"self_test": true`): at every start, after all mods
have loaded their data, LonaCraft checks several hundred things it relies on and that a game update
could break: the game methods it hooks or calls (and their arguments), input keys, game items,
NPCs, library events, shops, pictures, tilesets, maps and map events, game script files, plus
its own text keys, JSON files, item ids, town station and door tiles, save registry, script
order and recipe results. It never stops the game:
- all fine: one console line `LonaCraft self-test: M checks passed (...)`;
- something broke: one message box `LonaCraft self-test: N of M checks failed. See <log path>.`
and one console line per failure.
Either way the report is written to `UserData/LonaCraft_selftest.log` (overwritten each start):
game version, mod version, date, the mod load order, the failures with the reason and where the
expectation comes from, then every check (pass, FAIL or skip). Skips are checks that do not
apply (a part switched off, a mod not loaded) and are not counted.
**Crash trace** (with `"debug": true` and `"trace": true`, the default): the crafting screen
writes one line per step to `UserData/LonaCraft_trace.log`, as `HH:MM:SS.mmm step`, and closes the
file after every line, so a crash that closes the game without an error box (like the two
`RGSS301.dll` access violations of 2026-10-06) cannot lose it. It lists opening from the menu,
every window and bitmap the screen makes (size, and `addr_ok` or `ADDR_BIGNUM` from the game's
1 GB memory failsafe), each list row drawn, list and detail refreshes, cursor moves, mouse hover
and clicks, crafts, the result popup, leaving, memory at open and close, an `alive` line every
300 frames, and Ruby errors. The first line of each game run starts a new file and keeps the last
run's as `UserData/LonaCraft_trace.prev.log`, so restarting after a crash does not lose it (send
the `.prev` file if the crafting screen was opened again since). After a crash read the last
lines: the last line is the last step that ran; a `begin` line with no `end` after it names the
call that crashed, and a last line that is an `end` or `alive` line means the crash came later,
in the game's own frame update (drawing or sound). To turn it off set `"trace": false` in
`Config/LonaCraft.json` (or `"debug": false`, which turns off everything in this section).
**Viewport guard** (`"viewport_guard": true`, the default, with or without `debug`;
`Scripts/02_ViewportGuard.rb`): the crafting-screen crashes of 2026-10-06/07 (`RGSS301.dll`
access violation at offset `0x111a1c`) come from a sprite or window left alive on a viewport that
was already disposed; when the garbage collector later frees it the engine reads freed memory. The
guard remembers which viewport every sprite, plane, window and tilemap is drawn in, and when a
viewport is disposed it first disposes whatever is still on it. Each such catch writes
`viewport guard: <class> still alive on a disposed Viewport, made at <where>; disposed it` to the
crash trace (with the trace on, `<where>` is the script lines that made it) and, once per class
per game run, to the console: that line names the culprit. `"viewport_guard": false` turns it off.
**Adding a check (modders):** open `Scripts/98_SelfTest.rb`. Most checks are one row in a table
at the top: `METHODS` (`["Game_Map", :i, :setup, 1, "where it comes from"]`, `:s` for a module
method, the arity the game has now), `INPUT_KEYS`, `SETTINGS`, `GLOBALS`, `ITEM_LISTS` and
`EVENTLIB_LISTS` (a label, a source and a `lambda` returning names), `MAPS`, `MAP_EVENTS`,
`TILESETS`, `GAME_FILES`, `LOAD_ORDER`. A new kind of check is one
`check("group", "name"){ ... }` in `run_checks`: return `nil` to pass, a text to fail with that
reason, `skip("why")` to skip or `note("text")` to pass with a note. Exceptions are caught and
reported as failures.
## Other mods
**RolePlayS** (load it before LonaCraft):
- Its Light, Medium and Fire arrows (bundles of 10) can be crafted: Light by hand or at the bench
(1 Plank, 1 Bone), Medium at the Anvil (2 Plank, 4 Nails), Fire at the bench (Light Arrows,
1 Cloth Bolt, 2 Oil). Without RolePlayS these recipes simply do not show.
- Its Lumberjack Axe and Poleaxe count as axes for chopping trees.
- The Hatchet takes its Lumberjack Axe's picture in Lona's hand and its swing (stats unchanged).
- Animals drop both RolePlayS's quest skins (during its quests) and LonaCraft's Hide and Bone.
- Its weapons and armour get quality tiers and recipes; the crafting screen and the Craft menu row
use its look.
- Not integrated: RolePlayS's own cooking-pot recipes (arrows, bombs) stay at the pot, apart from
LonaCraft's crafting screen; its chest loot has no LonaCraft materials; its tool and quest checks
only accept the Common version of an item.
**Lona Booba Graphics** ("Lona Big Booba" in the Mods menu): load it before LonaCraft. **Other mods**: their gear gets recipes and tiers if
they load before LonaCraft. A mod that replaces the dark pot script also changes the Stove and
Cooking Fire's cooking.
## Localization
Texts are in `Text/<language>/` for the game's languages: ENG, CHT, KOR, RUS, UKR. English is the
original. CHT, KOR, RUS and UKR are machine-translated by Claude and have not been reviewed by native
speakers; the first comment line of each file says so ("Machine-translated by Claude on ..., not
reviewed by a native speaker"). Any text missing in your language falls back to English (one console
line), never a raw key.
To review or improve a translation, edit the text lines in your language's folder, keeping each key
line as it is and changing only the text under it. When a file has been reviewed, delete its first
comment line. Keep `\optB[...]` lists with the same number of entries (no ASCII comma or bracket
inside an entry), keep `\n`, `\narr`, `\}`, `\c[..]`, `%s`, `%d`, `NUM`, `HP_NOW`, `HP_MAX` and the
`#{...}` expressions as they are, use no ASCII colon (`:`) in text lines, and save as UTF-8 without
BOM, LF line ends.
The tier suffix is a text key too: `Tiers:Name/format` (in `Text/<lang>/Tiers.txt`) builds the shown
name, first `%s` the item name, second `%s` the tier name; the English text is `%s (%s)`. A language
can reorder or reword it, for example tier first or with a word like "quality". Every craftable
shows its tier, Common included.
Check your files with `python tools/check_text.py` (Python 3, from the mod folder or anywhere).
`--lang RUS` checks one language only and `--quiet` leaves out the detail lines. Per language it
lists missing, extra and untranslated (same as ENG) keys, text lines with a colon, CR characters and
byte order marks, and then compares every key with the English one: number of body lines, `\n`,
`\narr`, `\}`, `\optB` lists and their entries, `#{...}` expressions, `\c[..]` codes, `%s`/`%d`,
and the words NUM, HP_NOW, HP_MAX. It exits with 1 when a key is missing or a control code differs.
## Save notes
- Stored in your save: crafting level and experience, owned homes and rent, what Boss Mama holds,
placed furniture and chest contents, every base with its pieces and damage.
- New items get their ids from the load order. LonaCraft fixes its own items by name when you load,
so adding, removing or reordering mods keeps them right. Other mods' items are not fixed.
- A save made with LonaCraft 0.1.0: load it once with the same mods and order it was made with,
save again, and only then change the load order.
- A raid in progress is not saved: after loading there is no raid.
- If you turn LonaCraft off, saves with its items may show empty entries. Leave a house or base map
before turning it off. Turn it back on and everything returns.
## Known limits
- The CHT, KOR, RUS and UKR texts are machine-translated and not reviewed by native speakers
(see "Localization"); fixes are welcome.
- The Deep Sewer map ships, but its entrances are switched off in this version (see "Deep Sewer").
- The debug tools (numpad keys, god mode, self-test, crash trace) are off by default (see "Debug
and self-test").
- Furniture cannot be moved, only picked up and placed again.
- Boulders and loose stones use the game's own rock pictures. Item names in lists are not coloured by tier.
- Pieces belong to a map: if the game reuses one map for several places, the pieces show up in each.
- Wild areas are small, so a base is as big as its map allows. Build mode has no main-menu entry.
- Salvage boxes are shared by all stations of the same kind. Gold gear gives nothing yet.
- Companions do not open doors. The game's capture scene can put enemies next to Lona inside walls.
## Report a problem
Please send: the exact text of any error box (a screenshot is fine), your game version (such as
B.0.10.8.27), your mod list in load order, and `UserData/LonaCraft_selftest.log` and
`UserData/LonaCraft_trace.log` from the game folder. Those two logs are written only with debug on:
set `"debug": true` in `Config/LonaCraft.json`, start the game, do what went wrong once more, then
send them (the trace's previous run is kept as `UserData/LonaCraft_trace.prev.log`). Say what you
did just before it happened.
### NoerHome compatibility (1.1.2)
When both mods are active, Maani's **Buy house** opens a submenu with available properties: **Private house** from NoerHome, **Old shack** and **Stone house** from LonaCraft. Bought houses do not appear. When all three are owned, Buy house disappears from Maani's main menu. Ownership is kept separately in NoerHome `NoerHouseBought` and LonaCraft save data; the respective original purchase routines do not change. Normal bank, inn rental, crafting, furniture, bases and multiplayer features remain available. Works regardless of which mod loads first. When NoerHome is disabled, LonaCraft uses its normal two direct bank offers.