Icarus Local Editor

Local-only save-file tools for the PC game Icarus. The current build provides read-only prospect tools plus Character and Workshop Mount editors with validated edited-copy downloads.

Requirements

• Windows PowerShell
• Node.js 20 or newer

If PowerShell blocks npm, use npm.cmd as shown below.

Setup

npm.cmd install

Run Locally

Start the backend and frontend together:

npm.cmd run dev

Or start them separately:

npm.cmd run dev:server
npm.cmd run dev:client

• Frontend: http://localhost:5173
• Backend health: http://localhost:3102/api/health

Both services are intended for localhost only.

User Workflow

1. Choose Character Editor, Workshop Mount Editor, Profile / Currency Editor, or Prospect Research Tools from the top navigation.
2. Upload the required local file: Characters.json for characters, Mounts.json for workshop mounts, or Profile.json for profile currencies.
3. Select the character or mount record.
4. Edit supported fields and preview the changes.
5. Download the untouched original backup.
6. Complete the backup acknowledgments when required.
7. Download the validated edited copy and replace files manually only after closing Icarus.

Checks

npm.cmd run typecheck
npm.cmd test
npm.cmd run lint
npm.cmd run build
npm.cmd run catalog:validate
npm.cmd run characters:validate-private
npm.cmd run mounts:validate-private
npm.cmd run profile:validate-private

To manually refresh public progression metadata:

npm.cmd run catalog:refresh

The refresh command uses only public unauthenticated catalog pages, paces requests conservatively, and preserves the existing cache if no complete public table data can be validated.

To extract the private local Eureka Character Editor snapshot:

npm.cmd run catalog:extract-snapshot
npm.cmd run catalog:report

This reads only sample-data/reference/eureka-character-editor.html, never contacts the live website, and writes normalized factual metadata without character-specific current state.

To validate the private local workshop mount sample and regenerate the redacted mount research report:

npm.cmd run mounts:validate-private
npm.cmd run profile:validate-private

This reads only sample-data/pets/Mounts.json and the private local pet editor snapshot at sample-data/reference/eureka-pet-editor.html, verifies no-change round-trip behavior, validates RecorderBlob BinaryData no-change serialization, and writes redacted reports to shared/catalog/mounts-save-research-report.json, shared/catalog/mounts-binary-research-report.json, and shared/catalog/eureka-pet-snapshot-catalog.json.

To validate a private local profile sample without printing identifiers or balances:

npm.cmd run profile:validate-private

This reads only sample-data/private/Profile.json, validates the Profile.json structure, reports resource row counts, and redacts the UserID. It does not write or modify the private file.

Data Safety

Do not commit personal save files. Put local examples under sample-data/, which is Git-ignored.

Uploaded JSON is parsed and analyzed in memory, SHA-256 hashed from the original bytes, and never written to disk by the server. Character and workshop mount round-trip verification returns the original uploaded bytes for no-change operations and verifies identical SHA-256 hashes. API responses summarize structure while redacting likely account IDs, GUIDs, session identifiers, and server identifiers.

Editing is limited to explicitly classified fields:

• CharacterName, XP, XP_Debt, and ChrSlot in Characters.json
• safe primitive leaves under character MetaResources and Cosmetic
• structured character unlock and compatible resource operations
• MountName, MountLevel, MountType, and MountIconName in Mounts.json
• existing MetaResources[].Count values in Profile.json

The app previews a bounded diff, validates the edited output, and only then enables a browser download named Characters.edited.json or Mounts.edited.json. It does not write to live save folders. IDs, GUIDs, status fields, RecorderBlob, and BinaryData remain protected.

The Profile / Currency Editor edits only the Count property of existing MetaResources rows in Profile.json. Primary supported rows are Credits, Exotic1, Exotic_Red, Biomass, and Exotic_Uranium; advanced rows are Refund and Licence. Internal MetaRow names are authoritative. The editor does not add missing currencies, delete currencies, reorder MetaResources, unlock workshop items, edit talents, edit unlock flags, edit character slots, edit UserID, edit DataVersion, or provide arbitrary JSON editing. Unknown future MetaResources rows are detected, displayed read-only, and preserved.

Profile Count validation accepts only non-negative plain integers from 0 through 2,147,483,647; blank values, decimals, scientific notation, NaN, Infinity, malformed text, duplicate MetaRow entries, missing Count values, and non-integer original Count values are rejected or kept read-only. Preview uses a surgical scalar edit that replaces only the confirmed numeric token range for the target Count property and verifies byte identity outside approved ranges. Close Icarus and keep an untouched backup before replacing any live Profile.json. Profile analysis redacts UserID and returns only protected-section counts, not full private talent or unlock contents.

The Character Editor has a dedicated Progression workspace with sub-tabs for Overview, Research Points, Talents, and Solo Talents. The character Talents array is split into those progression systems using the private local reference snapshot metadata. Research Points use two explicit buttons: 0 - Locked and 1 - Unlocked. Character and Solo Talents are grouped into factual tree/subgroup sections, show friendly names first, and render one numbered button for every valid rank from 0 through each entry's proven maximum. Clicking a numbered button queues that exact numeric rank. A mixed global Max All remains disabled.

Talent tree progress uses effective rank: pending rank when present, otherwise the saved rank. Snapshot reward text, prerequisites, hierarchy depth, and icon references are displayed as metadata; the UI uses local fallback icons and does not hotlink external assets.

Save RowNames that are not exact catalog matches are reconciled only through explicit trusted aliases. Alias-backed edits preserve the original save RowName during serialization. Any unresolved or unknown-maximum entry is preserved read-only under Unmapped / Legacy Save Entries and is excluded from progress totals and bulk actions.

MountName and MountType are synchronized through outer JSON plus confirmed RecorderBlob.BinaryData string representations. The UI requires preview validation, an untouched backup acknowledgment, a corruption-risk acknowledgment, and typing I HAVE A VERIFIED BACKUP before downloading Mounts.EDITED.<timestamp>.json. MountLevel and MountIconName remain outer JSON edits only when duplication checks do not find BinaryData copies.

The Mount Editor now uses a reference-assisted workspace with a recovery panel, dense creature roster, selected creature summary, disabled Delete/Clone/New Pet actions, Overview & Genetics, Talents, Advanced, and Review & Download. MountName uses the existing synchronized JSON/BinaryData transaction, and MountLevel is the only proven ordinary gameplay-stat scalar. Sex, lineage, appearance, species conversion, experience, health, talents, status, and Wild/Alpha-style classification clues remain visible but protected until value semantics and serialization are proven. Genetics values are editable because BinaryData IntProperty parse/serialize is proven.

Current structure notes are in docs/save-structure-observations.md. User interface workflow notes are in docs/user-interface-workflow.md. Human-friendly editor UI notes are in docs/human-friendly-editor-ui.md. Binary blob inspection notes are in docs/binary-blob-inspection.md. Property layout notes are in docs/unreal-property-layout.md. Sequential walker notes are in docs/sequential-property-walker.md. Nested sublayout probe notes are in docs/nested-sublayout-probe.md. Inline name encoding notes are in docs/inline-name-encoding.md. Hybrid inline property notes are in docs/hybrid-inline-property-tags.md. Character save notes are in docs/character-save-format.md. Workshop mount notes are in docs/workshop-mount-save-format.md. Round-trip safety notes are in docs/exact-round-trip-safety.md. Edit transaction safety notes are in docs/edit-transaction-safety.md. Character name editing notes are in docs/character-name-editing.md. Workshop mount name editing notes are in docs/workshop-mount-name-editing.md. Primitive editing notes are in docs/primitive-field-editing.md. Field classification notes are in docs/field-classification.md. Numeric validation notes are in docs/numeric-validation.md. Character talent notes are in docs/character-talents.md. Character progression classification notes are in docs/character-progression-classification.md. Eureka HTML snapshot extraction notes are in docs/eureka-html-metadata-extraction.md. Progression snapshot cross-reference notes are in docs/progression-snapshot-cross-reference.md. Progression UI snapshot layout notes are in docs/progression-ui-snapshot-report.md. Research Points editor notes are in docs/research-points-editor.md. Character talent metadata notes are in docs/character-talent-metadata.md. Solo talent metadata notes are in docs/solo-talent-metadata.md. Progression metadata catalog notes are in docs/progression-metadata-catalog.md. Public catalog import notes are in docs/public-catalog-import.md. Progression entry mapping notes are in docs/progression-entry-mapping.md. Character unlock notes are in docs/character-unlocks.md. Character resource notes are in docs/character-resources.md. Character cosmetic notes are in docs/character-cosmetics.md. Mount RecorderBlob notes are in docs/mount-recorder-blob.md. Structured transaction notes are in docs/structured-edit-transactions.md. Mount binary layout notes are in docs/mount-binary-layout.md. Mount binary round-trip notes are in docs/mount-binary-round-trip.md. Mount skill/stat mapping notes are in docs/mount-skill-stat-mapping.md. Mount JSON/binary consistency notes are in docs/mount-json-binary-consistency.md. Mount value parser notes are in docs/mount-value-parser.md. Mount parsed-value round-trip notes are in docs/mount-parsed-value-round-trip.md. Mount synchronized preview notes are in docs/mount-synchronized-edit-preview.md. Mount containing-record notes are in docs/mount-containing-records.md. Mount synchronized apply notes are in docs/mount-synchronized-edit-apply.md. Mount save research notes are in docs/mounts-save-research-report.md. Save backup workflow notes are in docs/save-backup-workflow.md. Expert Mode safety notes are in docs/expert-mode-safety.md.