Skip to content

Mod packages: feature-oriented loader with guarded stock-disc operations - #81

Closed
mstan wants to merge 13 commits into
masterfrom
feat/mod-packages
Closed

Mod packages: feature-oriented loader with guarded stock-disc operations#81
mstan wants to merge 13 commits into
masterfrom
feat/mod-packages

Conversation

@mstan

@mstan mstan commented Jul 25, 2026

Copy link
Copy Markdown
Owner

The framework half of the mod-package work: a feature-oriented mod loader whose operations resolve against the user's own verified stock disc, before boot, with no patched image and no per-permutation recomp build.

What this adds

  • Feature/package/operation model. A .psxmod archive is an install and trust boundary that may contain many features; a feature is the user-facing toggle with its own state and options; an operation is the runtime primitive it resolves into. Enumeration, persistence, resolution and diagnostics live here.
  • Guarded operation vocabulary. Expected-value–guarded guest writes and disc/asset overlays, plus progressively richer patch records: bounded integers (u8/u16le/u32le), a register-linked mips_lui_ori_u32 transform, feature-local ordered-integer constraints, omit_when_default, and format-4 sparse owned fields so independent features can share one semantic record when their complete guards agree and their owned ranges are disjoint. Typed integer predicates select bounded templates before boot.
  • Composition and conflict handling. Resolution validates guards, targets and bounds, detects collisions across the whole plan, coalesces identical writes, and fails with both feature names and the contested resource rather than guessing. Package order is explicitly not a composition mechanism.
  • Trusted in-tree resolvers. Packages never carry native code; a game repo registers builtin:<id> resolvers for cases where several features must compose into a shared bitfield, table or allocation, and the package only names the resolver plus its selections.
  • Runtime context for resolvers, and feature-prerequisite handling so a feature that depends on a shared foundation says so rather than relying on ordering.

Design constraints held

  • Disc overlays are indexed once before launch, never scanned per CD read.
  • Guarded writes are applied once at the correct lifecycle point.
  • Hundreds of installed-but-disabled features cost nothing in-game.
  • The stock disc is never modified; the reference patcher and its derived images stay development oracles only.

Scope

Deliberately excludes two things that build on top of this and are in review separately:

MMX6 is the consuming game and the large-scale proving ground; its conversion is a separate PR in that repo.

@TechnicallyComputers TechnicallyComputers mentioned this pull request Jul 29, 2026
@mstan

mstan commented Aug 1, 2026

Copy link
Copy Markdown
Owner Author

Closing as superseded by the separately integrated mod-package series now on master. The feature was not rejected: commits 316eaa4 through 05e569c carried the loader, guarded stock-disc operations, conflict handling, typed patches, resolver context, prerequisites, tests, docs, and sparse fields into master. Master has since added substantial follow-up functionality and tests, so merging this older branch would conflict with or roll back the evolved implementation. The final framework suite (36/36) and four-title regeneration/build regression passed on the current implementation.

@mstan mstan closed this Aug 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant