ActRaiser Recomp  (linux/x86_64)
Version v0493-2-g3a0ac4a

This builds and runs the game on your computer from a game ROM you already
own. The compiler and build tools are included. Platform-specific library and
runtime requirements are listed below.

This README describes the generic/legacy script-based archive layout with
run-build and utils/. Current desktop Builder releases open directly as an
.app, .AppImage or .exe. Their Windows game output also opens directly as
ActRaiserRecomp.exe with its supporting files; no batch launcher is required.
See utils/docs/desktop-packaging.md for the desktop Builder's output layout.


WHAT YOU NEED
-------------
Your own game ROM: a ".sfc" or ".smc" file.
- SDL3 3.4.14 and SDL3_ttf 3.2.2 headers and libraries are included. Do not install
  SDL development packages. This build needs the Linux desktop/audio/font
  runtime libraries below. The Builder reports missing libraries
  before compiling. On a minimal Debian 13 installation these can be added with:
    sudo apt install libasound2t64 libpulse0 libdecor-0-0 libfribidi0 libx11-6 libxext6 libxcursor1 libxi6 libxfixes3 libxrandr2 libxss1 libxtst6 libwayland-client0 libwayland-cursor0 libwayland-egl1 libxkbcommon0 libfreetype6 libharfbuzz0b
  These are OS runtime components, not compilers or SDL SDKs. A graphical
  session and working graphics drivers are also needed to play normally.
  Selected SDL3 package requirements: libasound2 (>= 1.0.27), libc6 (>= 2.29), libdecor-0-0 (>= 0.2.0), libfribidi0 (>= 0.19.2), libpulse0 (>= 5.0), libwayland-client0 (>= 1.17.93), libwayland-cursor0 (>= 1.0.2), libwayland-egl1 (>= 1.15.0), libx11-6 (>= 2:1.2.99.901), libxcursor1 (>> 1.1.2), libxext6, libxfixes3 (>= 1:5.0), libxi6 (>= 2:1.6.99.1), libxkbcommon0 (>= 1.0.0), libxrandr2 (>= 2:1.2.99.3), libxss1, libxtst6
  Selected SDL3_ttf package requirements: libc6 (>= 2.14), libfreetype6 (>= 2.2.1), libharfbuzz0b (>= 2.3.1), libsdl3-0 (>= 3.2.6)
  Exact dependency versions, URLs and checksums: utils/licenses/sdl-sdk.lock.json
- Normal AppImage launching needs working FUSE (for example, Debian's fuse3).
  APPIMAGE_EXTRACT_AND_RUN=1 provides a no-FUSE launch fallback.


HOW TO PLAY
-----------
1. Start "run-build.sh":
      macOS    - double-click  run-build.command
      Windows  - double-click  run-build.bat
      Linux    - run           ./run-build.sh

2. Your browser opens the private local workshop. Choose "Build your game" on
   Home, select your ROM, then press "Build game". This takes a few minutes
   and only needs to be done one time.
   Your ROM never leaves this computer.

3. Play - press "Play" in the builder now. Later, open ActRaiserRecomp.app on
   macOS or ActRaiserRecomp.AppImage on Linux. This legacy Windows archive uses
   run-game.bat to select its utils/ data and ROM; the desktop Builder's new
   Windows game-folder output does not need it. The older run-game scripts
   are also kept for compatibility. Starting run-build again detects the game
   and opens as a launcher without rebuilding.

   The generated app is private: it contains your ROM. Do not distribute it.
   The Mac app is automatically signed locally; no Apple account is needed.


CHOOSE YOUR INSTALLATION TYPE
-----------------------------
Generated macOS/Linux game applications support the two choices below.
Legacy run-game scripts continue to use the original bundle's data folder.
Windows games use a portable folder; copying only the game .exe does not select
global storage or carry its required libraries and data.

Portable installation (Builder default)
  Keep the application, its .portable sidecar, and utils/ together. The Builder
  creates the sidecar automatically: its name is the complete application
  filename with .portable appended, and its contents point to utils/.

  Launch the application directly. Existing saves, settings, language packs,
  music and artwork are used in place from utils/. To move the installation,
  copy all three together, preserving their names and relative locations.
  Rebuilding an existing portable install requires no manual sidecar setup or
  data migration.

Non-portable installation (per-user data)
  Copy ONLY the application to your preferred location, leaving its .portable
  sidecar and utils/ behind. Launch that copy directly. Without a sidecar, the
  application uses your operating system's standard per-user application data
  directory, even if an old portable data folder is nearby.

  First launch initializes the required files there; later launches reuse that
  user's saves, settings and assets. Moving or replacing the application does
  not move this data. Switching types does not automatically transfer or merge
  saves and settings. The original portable files remain intact.

Do not put writable data inside the application. Exact data locations,
command-line overrides and launch diagnostics are documented in
utils/docs/desktop-packaging.md. The Workshop opened through run-build still
edits the original bundle's utils/ data, not a separate non-portable install.


UPGRADING TO A NEWER VERSION
----------------------------
Back up your saves before upgrading.

Portable: extract the newer Builder bundle over this folder and rebuild the
game. Keep the generated application and sidecar with the existing utils/ data.

Non-portable: generate the updated application with the newer Builder, then
replace only the application in your chosen location. Leave the new Builder's
.portable sidecar behind. Your existing per-user data remains in its operating
system directory and is reused by the updated application.

Shipped defaults are separate from live settings. New settings are merged in
alongside yours, and you will see a line like

      [upgrade] config.ini: 2 new settings added, your values kept

the next time you play. If you changed a setting, your value always wins; only
settings that are genuinely new in that version get added.

The same is true of "diorama-layers.ini" and "game-assets/manifest.ini": your
authored rooms and your own asset entries survive an upgrade.

You will need your ROM again only if you want to REBUILD. If you just want to
keep playing, the game is already built and nothing else is needed.


OPTIONAL: FREE UP SPACE WHEN YOU ARE DONE BUILDING
--------------------------------------------------
Most of this folder is the build toolchain, and it is only needed if you want to
build again later. After a successful build the builder offers to remove it and
keep just the game - it will tell you how much space that frees.

Nothing you need to play is touched: the game, your settings, your saves and any
music or graphics you added, and the bundled manual all stay. Afterwards
run-build still works as a launcher, it simply no longer offers to build - so
the builder itself is kept (it is small), and only the toolchain it needs goes.
If you ever do want to rebuild, download this package again.

You can also do it by hand. These folders inside "utils" are only for building
and are safe to delete. Note it is "utils/tools/toolchain", not all of
"utils/tools": that folder also holds the builder program itself, and run-build
will not start without it.

      utils/tools/toolchain  the compiler toolchain (by far the largest)
      utils/tools/sdl3       build copy of a support library
      utils/build          leftover build scratch
      utils/src            the game's source code
      utils/recomp         recompiler configuration
      utils/snesrecomp-go  runner SDK headers and static library used while building
      utils/third_party    a support library used while building

For a portable installation, keep the rest of "utils": "utils/config.ini",
"utils/diorama-layers.ini", "utils/game-assets" and "utils/saves" are live data. The
Workshop also uses this folder. A non-portable application runs independently
of it, but copying just the application does NOT copy these saves or settings;
keep or back up the original data before discarding an old installation.


IF SOMETHING GOES WRONG
-----------------------
- The browser does not open: copy the private http://127.0.0.1 URL printed in
  the run-build window and paste it into any browser on this computer.

- macOS says the file is from an unidentified developer: hold Control, click
  run-build.command, choose Open, then Open again. (You only do this once.)

OPTIONAL: YOUR OWN MUSIC AND HD GRAPHICS
----------------------------------------
This package starts with the ROM's original music and graphics. Open Assets
in the sidebar and choose Music or Title artwork. Select a music track and
browse to an Ogg Vorbis file, then press Save changes. All 17 ROM song images
are listed; currently unknown names use a "Track NN"
label so you can extract and listen to them before naming them.
The builder copies those files into "utils/game-assets" and updates
"manifest.ini" for you. Advanced packs can still add their own files and
records there directly. Anything you don't add simply stays original.

After supplying the ROM on the Build tab, you can also press "Extract
original-audio previews" on Assets. The bundled pure-Go audio renderer creates
local 30-second WAVs so each original track can be played beside the selected
replacement. These previews stay in your computer's user cache; they are not
copied into the game, its manifest, or a release package.


LOCALIZATION WORKSHOP
---------------------
To install a published .arlang without the editor, copy the file directly into
game-assets/languages/packs/ inside the game's data directory (utils/ for a
portable install). Do not unzip it. Restart the application and select its
package name under Localization. The application includes its archive helper;
legacy run-game installs must retain utils/tools/actraiser-builder. Duplicate
enabled IDs, including archive/folder duplicates, must be resolved before
selection.
See utils/docs/language-packs.md for manual install/update/removal, editor-free
authoring and validation commands. The machine-readable route reference and
archive schema accompany it; small authored examples live in utils/examples/.

Open Languages in the sidebar to install a shared language pack, create your
own translation, resume or clone a project, or extract a read-only source from
a clean US, EU,
German, French or Japanese ROM. The build also prepares your local US source.
Create a named translation from US, browse/search messages, and save each as
Not started, WIP or Done. Regional sources can be selected as references.

Author backups (.arproject) keep your progress, notes and local source template;
keep ROM-derived backups private. Language pack exports (.arlang) include your
reviewed translations, author credits and license notices. Import packs or
backups to resume editing; duplicate locales remain separate by package ID.
The GUI and build use the same Go extraction/validation code. No Python needed.

Install a reviewed pack, restart the game, then select its name in the overlay's
Localization menu. Enhanced text uses the selected source. Native rendering
keeps original USA text/font. The editor preview is a script preview, not final
in-game font layout; visually check translations before sharing them.
Opening/importing and saving only change your workshop copy. Use the explicit
Pack actions → Install in game workflow to update the installed version the game uses.
Local installation keeps all supplied translations; redistribution consent and
WIP filtering belong to Export for sharing. Under Import new pack, choose an
.arlang file, or drop one .arlang at a time into the Workshop from any section.
Review the package, then choose Import & install. Unpacked folders
remain available under Advanced: unpacked language folder. Install already
imported lets you choose saved work. Installed packs have enable/disable
checkboxes in Languages. Unchecking keeps their files and progress but hides
them from the game's language selector after restart.

Workshop projects and installed packs live under utils/game-assets/languages.
The shared and Japanese interface fonts and their licenses are under
utils/game-assets/fonts. Regional
ROMs and extracted scripts are never included in the distribution. See
utils/docs/language-pack-format.md for authoring, controls, fonts and credits.
See utils/docs/builder-workshop.md for navigation and the optional Home scene.


WHAT THE FOLDERS ARE
--------------------
- run-build.*     opens the graphical builder. After the game is built this
                  opens as a launcher instead.
- run-game.*      compatibility launcher using this bundle's utils/ data.
- ActRaiserRecomp.app / .AppImage  native game application (macOS / Linux).
- ActRaiserRecomp.app.portable / .AppImage.portable  selects utils/ data.
- utils/          the build tools, Workshop files and portable game data.
                  Non-portable applications use per-user data separately.
                  See "free up space" above for what is safe to remove.
- utils/defaults/ this version's stock settings, kept separately so upgrading
                  never overwrites yours. Do not edit these; edit the copies in
                  utils/ instead.

Licensing and credits are in utils/LICENSE, utils/LICENSE_SCOPE.md,
utils/ATTRIBUTION.md, utils/THIRD_PARTY_NOTICES.md, and
utils/ACTRAISER-THIRD-PARTY-NOTICES.md. The vended runner's
notices are also under utils/snesrecomp-go/runtime/.
