lanyi
e0b8dedc04
Preserve edittext channels, alpha/color transforms, inactive placement fields, zero ratio/clipping and null ClipAction presence. Keep unlabelled flag bits, quoted/escaped script strings, export declarations and correctly typed CONST and pushdata values. Validate signed integers and write byte-aligned UTF-8. Add 23 public CLI regressions and record the native 174-resource batch plus bounded retests: four discovered pages are repaired, while the sound placeholder and native float formatting remain explicit accuracy limits. Rebuild the 1.0.1 Windows executable and leave unrelated SDK changes untouched.
33 lines
3.7 KiB
Markdown
33 lines
3.7 KiB
Markdown
# ra3apt-cli 1.0.1
|
|
|
|
Convert RA3 APT binaries to editable XML and build them using the bundled cc3tools converters.
|
|
|
|
```powershell
|
|
ra3apt-cli.exe expand path/to/page.apt -o private/page_edit.xml
|
|
ra3apt-cli.exe build private/page_edit.xml -o private/page.apt
|
|
```
|
|
|
|
Keep the input APT's CONST, DAT, manifest XML and geometry together. Use `--tools-path` when cc3tools is not adjacent to the executable. Build in a private output directory: it also writes a CONST, manifest, DAT and geometry files. Textures referenced by the manifest must be supplied separately.
|
|
|
|
## Roundtrip repairs
|
|
|
|
Version 1.0.1 preserves raw edittext channels without the old asymmetric red/blue swap. These channel names follow cc3tools' dump convention; they must not be interpreted as an independent runtime RGB definition. For example raw edittext channels `(98,177,244)` correspond to packed color `0xFFF4B162`, whose rendered RGB is `(244,177,98)`.
|
|
|
|
PlaceObject color transforms and alpha are retained before flags are recalculated. Inactive matrix/color storage fields are removed during expansion, so a Move-only object no longer acquires an active matrix or color transform on build. Ratio and clipdepth flags are based on field presence, including an active zero value. The original HasClipAction bit is retained when its pointer is null, without creating an empty array. Remove HasClipAction explicitly from the input flags to clear that presence bit. Unlabelled flag bits are preserved as explicit hexadecimal terms such as 0x40; their engine meaning is not guessed.
|
|
|
|
Assembly strings now preserve quotes, backslashes, commas, control characters, ampersands and literal entity text with one XML decode. Export declarations retain their original order and repeated names. Constant pools accept names such as `constructor` and `__proto__`; pushdata uses the actual data schema and retains quoted string types. Type-7 integers use signed32 validation and preserve negative bit patterns. Fractional/overflow operands and embedded NUL constants are rejected instead of silently changing values. Strings are stored as variable-length UTF-8 with byte-based pointers and alignment.
|
|
|
|
Re-expand the original APT with this version before editing. Old saved edit XML may contain inactive default fields or ambiguous backslashes from the old expansion and is not automatically migrated.
|
|
|
|
## Accuracy boundary
|
|
|
|
This tool does not promise byte-exact APT/CONST roundtrips. IDs, pool ordering and manifest/DAT declarations may be rebuilt. cc3tools emits many float32 values to six decimal places; this loses precision before the JavaScript layer receives them. A script `pushfloat 0.3333333432674408` becomes `0.333333` in native output and rebuilds to different float32 bits. Equal expanded XML cannot establish original float32 equality. Repairing that loss requires a precise native formatter or a separately designed binary preservation mechanism.
|
|
|
|
The sampleMissionBriefing baseline contains a real type-6 sound character. cc3tools exports it only as a not-implemented placeholder without its payload/id. Build now stops with a specific diagnostic; this resource cannot be rebuilt accurately through the current native XML representation.
|
|
|
|
UTF-8 byte preservation does not establish engine font/encoding support. Native conversion and XML checks do not substitute for in-game testing of edited resources. See `ROUNDTRIP_REPORT.md` for the actual 2026-10-13 resource results.
|
|
|
|
## Development
|
|
|
|
Install normal dependencies, run `npm test`, and build the Windows executable with `npm run build:exe` (Node 24 target). Tests and their limits are documented in `test/README.md`. Direct test artifacts with `RA3_CLI_TEST_ARTIFACT_ROOT`; generated files belong in `.work/` and must not be committed.
|