Change params with a rowlist · Team Cereus tooling wiki

A stage never ships a whole regulation.bin. It ships a rowlist: a text file that says which cells change, from what, to what. The release applies every stage's rowlist in order with Polish. This page covers the rowlist format, Polish, and the small tools around it.

Checked against code: all of Polish (Program.cs read in full), and the usage headers and command switches of RegQ, TableRows, BndSet, InvTool and MimicOpen. Not checked: the bodies of InvTool's commands. Nothing was run.

EB means py -3.12 -I -B S:/eclipse-build/eb.py. Shared tools only: ../build/use-shared-tools.md.

What you need

Polish: EB tool build polish. It is a dll: run it as dotnet <folder>/Polish.dll .... EB tool env prints the path (--tool=polish=).
EB_PARAMDEFS set to the Nightreign paramdef folder. EB tool env gives it. Without it Polish and RegQ fall back to a Smithbox folder under a Downloads path.
The regulation you start from, and absolute paths for everything.

Rowlist format

One change per line. Fields are separated by a TAB. A line that starts with # and a blank line are skipped. The usual header line is:

# op	param	row	field	old	new	note

Line	Columns	What Polish does
set a cell	`SET <Param> <row id> <field> <old> <new> <note>`	If the cell already equals `new`: counted as already-applied. If it equals `old`: set to `new`. Anything else: the line is skipped and reported.
add a row	`ADDROW <Param> <new id> copy=<source id>`	Copies the source row to the new id. If the id exists: already-applied.
delete a row	`DELROW <Param> <id>`	Removes every row with that id. If none exists: already-applied.

Details that matter:

Polish only tests the first column for ADDROW and DELROW. Any other word is treated as a set line. Write SET.
field is the paramdef's internal field name.
Values compare equal as text, or as numbers within a relative 0.0001 when at least one side is not a whole number.
A set line needs columns up to new. The note column is for people.
An ADDROW only copies. Put SET lines after it to change the new row's fields.
A skipped line prints SKIP <param> <id> <field>: is <cur>, list expects <old> -> <new>; not changed. A missing row or field is also a skip.
Because already-applied lines are fine, a rowlist can be applied twice. That is how the release verifies a build.

Apply a rowlist

dotnet <Polish.dll> apply <in regulation.bin> <rowlist.tsv> <out regulation.bin>

It prints one line per touched param (<Param>: row size <n> ok, rows <count>), every SKIP, and a summary: set N, already-applied N, rows added N, skipped N; rows deleted N; wrote <out>.

Exit codes: 0 clean; 2 when at least one line was skipped (the output file is still written); 1 when a param's row size changed (nothing written). Treat 2 as a failure. The output is encrypted when the input was.

Apply a chain of rowlists

dotnet <Polish.dll> apply-chain [--steps <dir> [--first <n>]] <in.bin> <out.bin> <list1> <list2> ...

Same result as one apply per list, but the regulation is decrypted and encrypted once.
After each list it prints list <k> <file>: <summary>.
It stops at the first list that skips a line and writes nothing to <out.bin>.
--steps <dir> also writes the regulation after every list as <dir>/stepNN.bin. --first <n> sets the first number (default 1).
Last line: apply-chain: <n> lists; wrote <out>.

AGENTS-GUIDE.md records that on the 0.0.86 chain this was byte-identical to 12 separate applies, in 20 s instead of 56 s.

Verify that rowlists are applied

dotnet <Polish.dll> verify-chain <in.bin> <list1> <list2> ...

Runs the lists on one decrypted regulation and writes nothing. It is meant for lists that are all applied already. It stops at the first list that skips a line (exit 2).

The regulation IV

Polish and TableRows read EB_REG_IV when they encrypt:

Value	Result
unset	a random IV, so two runs give different files
`content`	an IV made from the content, so the same content gives the same file
32 hex digits	that IV, to reproduce a published file byte for byte

Other Polish commands

Command	Arguments	What it does
`dump`	`<reg> <Param> <id>...`	every cell of those rows
`plist`	`<reg>`	the param names in the regulation
`diffreg`	`<regA> <regB>`	which params differ, with row size and row count
`npcn`	`<reg> <name regex>`	NpcParam rows whose name matches
`scan`	`<reg>`	NpcParam rows that use a CharaInit row
`ci`	`<reg>`	CharaInitParam rows for NPCs

names, emevd, where, genlist and compare are left over from the Boss Arena work. They use hard-coded paths. Do not use them.

Known hazard: duplicate row ids

ADDROW re-sorts the param with an unstable sort after it adds a row. Nine vanilla params keep several rows under one id (ItemTableParam, SwordArtsTableParam, AttachEffectTableParam, MagicTableParam, NPCBotTableParam, MenuPropertyLayoutParam, BuddyStoneParam, Ceremony, RandomAppearParam), and the sort can swap such rows. ADDROW also cannot add a second row to an id that exists. For those params use TableRows. tools/README.md lists this as an open hazard in Polish.

TableRows

EB tool build tablerows. Adds rows to params that keep several rows under one id, without sorting.

TableRows append <in regulation.bin> <rows.tsv> <out regulation.bin>
TableRows check <base regulation.bin> <out regulation.bin> [Param...]
TableRows rows <regulation.bin> <Param> <id>...
TableRows counts <regulation.bin>
TableRows fmg <msgbnd.dcx> <id>[-<id>]...

rows.tsv lines, tab separated, # comments:

APPEND <Param> <id> <template id>[#occurrence] <field=value;field=value;...> <note>
SETW   <Param> <id> <key field>=<key value> <field> <old> <new> <note>

APPEND clones the template row (its n-th copy, the first by default), sets the id and the fields, and inserts it right after the last row with that id. A line whose finished row already exists counts as already-applied.
SETW sets one field of the one copy of <id> whose key field has the key value. No match or more than one match fails.
check proves that every base entry is still in the output, unchanged and in order. Exit 1 if not.

RegQ

EB tool build regq. Read only. It never writes a regulation.

Command	Arguments	Prints
`cells`	`<regA> <regB>`	every differing cell and every added or removed row
`dump`	`<reg> <Param> <id>...`	`VAL` lines for every cell of those rows
`find`	`<reg> <value> [Param...]`	every cell whose value text equals `<value>`
`table`	`<reg> <Param>`	a header line, then one tab-separated line per row
`order`	`<reg> <Param> <id>`	the row index and name of each row with that id

RegQ's own usage line only names cells and dump. Use cells to turn two regulations into the facts for a rowlist, and order to check duplicate-id rows.

BndSet

EB tool build bndset. Replaces entries of a binder by file name.

BndSet <in binder> <out binder> <entry file name>=<replacement file>...

Ids, names and flags stay. It writes DCX_KRAK and reads back: every other entry identical, each replaced entry equal to its new file, entry count unchanged.

InvTool

EB tool build invtool. Builds the Eclipse invasions layer and has general probes. Usage from Program.cs:

build   <config dir> <out dir>
common  <config dir> <vanilla common.emevd.dcx> <out> [--empty]
pdump   <regulation> <Param> [ids]
pscan   <regulation> <lo> <hi> [params]
evdump  <emevd> [event ids]
evscan  <lo> <hi> <emevd|dir>...
fmg     <msgbnd> <fmg name part> [ids]
fmgfind <msgbnd> <regex>
msb     <msb>
reward  <config dir> <invader key> <in emevd> <out emevd>
msgadd  <in msgbnd> <out full> <out partial> <fmg>[,<fmg>] <id>=<text>...

build makes the staged package (maps, rowlist, text) from config/*.tsv. pscan and evscan find ids in a range, which helps when you pick free ids. msgadd adds FMG entries and writes both a full binder and an additive partial one. The code also has tae, with no usage text. The config files are described in scripts/tools/eclipse-invasions/README.md in souls-script-kt, not read here.

MimicOpen

EB tool build mimicopen. Gives a seed's mimic chest (the c9880 part of one variation) the Open prompt.

MimicOpen <msb in> <msb out> <emevd in> <emevd out> <variation> <entity> <event> <flag> <actionButton> <markSpEffect>

It sets the entity id on the part and adds two events, <event> and <event>+1, started from event 0. Running it on its own output fails because the event ids exist. Always start from the CastleVariants output.

CritFix

CritFix edits animation binders, not params. It is on port-a-ds3-or-er-character.md.

What goes wrong

SKIP ... list expects: the regulation you applied to is not the one the list was written against. Rebase the list; do not edit old by hand without checking why it moved.
Exit 2 from apply with an output file on disk: the file lacks the skipped lines. Delete it.
Two builds differ only in regulation.bin: set EB_REG_IV=content.
Relic vessel rows. Dated note (memory nr-relic-vessel-limit): never add chalice rows. The save file's relic block has a fixed size and 0.0.78 wiped players' presets this way.