Two kinds of patch live here:
- Text patches: the app's Patches feature. A
.patch.tomlfile that fixes or adds to a string in the game'sglobal.ini. You can keep one for yourself or send it upstream as a built-in patch. - Code patches: changes to this repo, sent as a pull request.
Rules for both: no game prose in the repo, no game files, no real player data (AGENTS.md).
A TOML file named <id>.patch.toml with schema = 1. The format and its reasons are in
docs/decisions/own-patch-format.md; the parser and engine
are crates/starorg-core/src/patch.rs.
Top level:
| Key | Required | Notes |
|---|---|---|
schema |
yes | Must be 1 |
id |
yes | Letters, digits, -, _. Must equal the file name without .patch.toml |
title |
yes | Shown in the Patches screen |
description, reference |
no | Free text |
builds |
no | game_min, game_max (e.g. "4.10.0", from Data.Branch), change_min, change_max |
[[data]] |
no | Changes one field of one record before generators run |
[[loc]] |
no | Changes one output string after generators run |
[[loc]] entries: key (matched without regard to case), op, optional id, and:
op |
Needs | Does |
|---|---|---|
set |
value |
Replaces the value |
append / prepend |
value |
Adds text at the end / start |
replace |
find, value |
Swaps find, which must occur exactly once |
append_from |
from, plus requires or expect_sha256 |
Appends a part of another key (from_part: generated (default), stock, final) after separator |
Optional on any [[loc]] entry: expect_sha256 (SHA-256 of the stock value; on a mismatch the
entry is skipped as target-changed), requires (the id of a [[data]] entry in the same
file), optional = true (a key missing from the build is not-needed, not a warning).
[[data]] entries: id, exactly one of record (short record name) or guid, optional
contract (then record is the generator), field, expect (the loc key it has now) and
set. field is one of name_key, short_name_key, desc_key, title_key,
description_key.
Strings in TOML: a line break in global.ini is the two characters \n, so write "\\n".
- Files over 256 KiB, files that are not UTF-8, unknown keys, a wrong schema, a bad id or a missing required key are refused with an error. The other patches still load.
- Every entry gets one outcome and never fails the apply:
applies,not-needed(CIG fixed it, or the result is already there),target-changed,nothing-to-add,missing,out-of-range,conflict(two enabled entries write one key),disabled,no-data.target-changed,missingandconflictmake the apply "applied with warnings". - Each patched value goes through the same rules as every other edit
(
crates/starorg-core/src/validate.rs). A value that breaks them is dropped with a warning. - Built-in patches are compiled in (
BUILTINinpatch.rs). User patches load from the app data folder:- Linux:
$XDG_DATA_HOME/starorg-codex/patches/(default~/.local/share/starorg-codex/patches/) - Windows:
%APPDATA%\StarOrg Tools\Codex\data\patches\
- Linux:
- Switching a patch off is per channel: its id goes into
[patches] disabledin that channel'sprofile.toml. Changing patches marks the channel as needing a re-apply.
Patches -> Add patch writes a one-entry loc patch (set, append, prepend or replace)
into the folder above. Import patch file reads a .patch.toml; Export saves one of
your own patches to a file (built-in ones cannot be exported). For [[data]] entries, append_from or guards, write the file by hand and
import it or drop it in the folder.
Worked example. It uses a scratch app folder, so your real settings and the game are not touched.
cargo build --locked -p starorg-cli
R=$PWD/.tmp/patch-example
mkdir -p "$R/data/starorg-codex/patches"
cat > "$R/data/starorg-codex/patches/my-first-fix.patch.toml" <<'EOF'
schema = 1
id = "my-first-fix"
title = "Example: add a note to one text key"
[[loc]]
id = "note"
key = "Example_Item_desc"
op = "append"
value = "\\n\\nExample note."
EOF
XDG_CONFIG_HOME=$R/config XDG_DATA_HOME=$R/data XDG_CACHE_HOME=$R/cache \
target/debug/starorg-codex patchesOutput: the three built-in patches, then
my-first-fix enabled Example: add a note to one text key. A file whose name does not match
its id is listed as error in <file>: file name <file> does not match id <id>. Add --json
for the full list with errors.
To see outcomes against a real build, copy the file into your real patch folder and run
starorg-codex patches --channel LIVE or starorg-codex apply --channel LIVE --dry-run, or
open the Patches screen. patches reads only a cached extraction, which an earlier real
apply leaves behind (a real apply does write global.ini into the game install).
patches and apply --dry-run do not write to the game.
A loc-only built-in patch must guard every entry with expect_sha256 (test
builtin_patches_parse). Hash the exact stock value, the text after = on the key's line,
with \n as two characters:
printf '%s' 'Old Name' | sha256sum-
Add
crates/starorg-core/patches/<id>.patch.toml. Start with a comment saying which build you checked it against and how. Keys, record names and our own hint text only: no CIG prose. -
Add it to
BUILTINincrates/starorg-core/src/patch.rs. -
Add a test in the
testsmodule ofpatch.rs. It runs the patch against a synthetic stock file and covers both cases: the guard matches (applies) and CIG changed the text (target-changed).quest_items_pack_applies_and_skips_changed_textis the model. A minimal one, using the module's helpers:#[test] fn my_first_fix_applies() { let s = snap(); // synthetic stock; has `name_a=Old Name` let sha = fsutil::sha256_hex(b"Old Name"); let set = set_of(&[&format!( "{HDR}id = \"my-first-fix\"\n[[loc]]\nid = \"note\"\nkey = \"name_a\"\nop = \"append\"\nvalue = \" (fixed)\"\nexpect_sha256 = \"{sha}\"\n" )]); let (edits, outcomes, _) = run(&set, &GameData::default(), &s, None); assert_eq!(outcomes[0].entry, "loc:note"); assert_eq!(outcomes[0].state, EntryState::Applies); assert_eq!(edits[0].value, "Old Name (fixed)"); }
Run it with
cargo test --locked -p starorg-core --lib patch::. -
Bump
OUTPUT_VERSIONincrates/starorg-core/src/lib.rsand add a history line: a new built-in patch changes the generated text. -
Commit as
feat(patches): ...and open a PR (below).
Not sure it is a CIG bug, or no way to write the guard? Open an issue with the key and the build instead.
- Fork
voidput/starorg-codexand branch frommain. One topic per branch. - Make the change. Read AGENTS.md for the layout and the rules that are easy to miss.
- Run the gates (CONTRIBUTING.md; the full CI list is in AGENTS.md).
- Commit with signed Conventional Commits (
fix(app): ...,feat: ...,docs: ...). No AI attribution trailers. - Open a PR against
mainand fill in the template (.github/pull_request_template.md): what and why, the linked issue, how you tested it, and the checklist.
Review: CI must pass (ci.yml runs on every PR; security.yml too). A maintainer reviews
and merges. Unsigned commits cannot land on main, so sign them before you ask for review.
Licence: no CLA or DCO sign-off. By contributing you agree your work is under the MIT License (CONTRIBUTING.md). Security problems go to SECURITY.md, not a PR or issue.