PSXRecomp mod packages and features

A .psxmod is a versioned installation, provenance, and trust boundary. A package may contribute any number of independently configurable features. The launcher presents those features as the primary Mods list; package installation, version selection, and removal are a secondary management view.

Feature identity is always (package_id, feature_id). Enabling one feature never enables, disables, or reconfigures another feature.

The player selects a verified stock BIN/CUE. Resolution produces guarded native operations and sparse disc overlays without rewriting or replacing that stock image.

Feature manifest

format_version = 1
id = "example.localization"
version = "1.2.0"
name = "Example Localization Pack"
author = "Example Author"
description = "Independent title and script features."
license = "MIT"
resolver = "declarative"

[[target]]
game_id = "SLUS-00000"
# Required for disc overlays. Use the digest of the supported stock image.
disc_sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

[[feature]]
id = "title-screen"
name = "Title Screen"
description = "Selects the title-screen artwork."
group = "Localization"
default_enabled = false

[[feature]]
id = "retranslation"
name = "Retranslation"
description = "Uses the revised English script."
group = "Localization"

[[option]]
feature = "title-screen"
id = "variant"
label = "Title artwork"
type = "choice"
default = "rockman"

[[option.choice]]
value = "mega-man"
label = "Mega Man X6 (USA)"

[[option.choice]]
value = "rockman"
label = "Rockman X6 (Japan)"

[[patch]]
feature = "title-screen"
target = "main_exe"
address = 0x80041234
expected = "2a 00 02 24"
replace = "0e 00 02 24"
when = { variant = "rockman" }

[[overlay]]
feature = "retranslation"
target = "disc_raw"
offset = 123456
file = "assets/retranslated-script.bin"
sha256 = "..."
# Optional additional guard over the same range in the stock image.
expected_sha256 = "..."

Every [[option]], [[patch]], and [[overlay]] in a feature-style manifest must name its owning feature. Ambiguous operations are rejected.

Option types are boolean, choice, and bounded integer. Conditions are feature-local: when = { option = "value", ... } requires every listed option to match. The legacy when_option/when_value pair remains accepted for a single condition.

Native operations

main_exe writes use PSX guest virtual addresses. Expected bytes are checked after the BIOS loads the executable, then the complete write plan is applied before its entry point. Changed executable ranges use the existing dirty-RAM interpreter/native-overlay machinery; untouched functions remain on the static native path.

Small disc_raw and disc_user patches are equal-length guarded writes and may not cross a sector boundary:

disc_raw offsets use lba * 2352 + byte_in_sector.
disc_user offsets use lba * 2048 + byte_in_sector.

File-backed [[overlay]] operations are intended for large assets and may span any number of sectors. Their paths must remain inside the archive. Payload size and SHA-256 are verified while scanning, but disabled payloads are not retained in memory. Enabled payloads are loaded and reverified during resolution, then indexed by target and LBA before boot. A CD read performs a direct indexed lookup rather than scanning every installed mod.

Feature disc overlays require an exact disc_sha256 on every target entry. expected_sha256 can additionally guard the replaced stock range.

State and migration

mods/state.toml format 2 stores selected package versions separately from per-feature enabled states and values:

format_version = 2

[[package]]
id = "example.localization"
version = "1.2.0"

[[feature]]
package_id = "example.localization"
id = "title-screen"
enabled = true

[feature.values]
variant = "rockman"

State format 1 and package-only manifests remain readable as a migration aid. They appear through one synthetic legacy feature. New packages should use explicit features.

The old derived_disc VCDIFF mechanism is legacy conversion scaffolding only. Feature-style manifests reject it. It is not a product mod primitive, fallback, or image-selection workflow; patched discs may be used offline as parity oracles while converting known mods to native operations.

Resolution and diagnostics

Before boot, the manager:

verifies the selected stock game and revision;
expands only enabled features and their selected options;
orders active packages deterministically by dependencies;
verifies enabled payloads and operation bounds;
collision-checks the complete byte-range plan;
coalesces only truly identical target/range/expected/replacement writes or identical overlays; and
produces a canonical SHA-256 plan fingerprint.

Incompatible overlaps fail before launch. Structured diagnostics identify both (package, feature) owners and the exact contested target range. The launcher marks both feature rows and lets the user decide what to disable. It never silently chooses a winner.

Package-level dependencies and conflicts are reserved for actual implementation relationships. Mutually exclusive choices such as US versus Japanese artwork belong inside one feature as option values.

Trusted adapters and archive safety

resolver = "builtin:<id>" selects a resolver statically registered by the game. Packages cannot load arbitrary native code or select arbitrary symbols.

The installer accepts stored or DEFLATE-compressed ZIP entries, validates CRCs, rejects encrypted entries and unsafe or absolute paths, limits archives to 4096 files and 256 MiB expanded size, stages extraction, validates the manifest, and publishes the version atomically.

5.6 KiB Raw Blame History