Setup and Start

Installing the app

HakkinFF1 doesn't use an installer. The release is a zip archive containing a single executable and its license files. You put the executable in a folder and run it.

Windows

  1. Download the latest Windows file and verify its SHA-256.
  2. Pick a folder that you can write to without administrator rights, for example C:\Users\<you>\Apps\HakkinFF1 or D:\Tools\HakkinFF1. Don't use protected system folders like C:\Program Files: it's read-only for standard accounts, and the app reads shared extensions from an extensions folder next to the executable, which you'll want to be able to edit.
  3. Right-click the zip, choose Properties, and if there's an Unblock checkbox at the bottom, check it and click OK. If you skip this, Windows flags every extracted file as downloaded from the internet.
  4. Right-click the zip, choose Extract All..., and extract it into the folder from step 2. You'll get:
    HakkinFF1\
      HakkinFF1.Desktop.exe               the app
      LICENSE.txt                         Apache License 2.0
      NOTICE.txt                          copyright and licensing notice
      THIRD-PARTY-NOTICES.txt             licenses of the components the app includes
      TRADEMARKS.txt                      trademark policy for the HakkinFF1 name and icon
  5. Double-click the .exe to start the app. The executable isn't code-signed, so Windows SmartScreen may show Windows protected your PC. Click More info, then Run anyway. Windows shouldn't ask again for that file.
  6. Optional: right-click the .exe and choose Pin to Start, or create a desktop shortcut.

The app opens on the Welcome view.

Where things are stored. App settings, including the recent-projects list, are saved per user in %AppData%\HakkinFF1\appsettings.json. Each project is self-contained in its own folder, wherever you create it. That means you can update by replacing the .exe with a newer one, and your settings and projects stay as they are.

Linux

The Linux build is for 64-bit x86 (x64) PCs with a graphical desktop. It includes the .NET runtime, so you don't need to install .NET.

  1. Download the latest Linux file and verify its SHA-256.
  2. Pick a folder in your home folder, for example ~/Apps/HakkinFF1. Don't use system folders like /opt or /usr/local: they're owned by root, and the app reads shared extensions from an extensions folder next to the executable, which you'll want to be able to edit.
  3. Extract the zip into that folder from a terminal:
    mkdir -p ~/Apps/HakkinFF1
    unzip ~/Downloads/HakkinFF1.Desktop-<version>-linux64.zip -d ~/Apps/HakkinFF1
    You'll get:
    HakkinFF1/
      HakkinFF1                           the app
      LICENSE.txt                         Apache License 2.0
      NOTICE.txt                          copyright and licensing notice
      THIRD-PARTY-NOTICES.txt             licenses of the components the app includes
      TRADEMARKS.txt                      trademark policy for the HakkinFF1 name and icon
    The zip keeps the app's execute permission, so it's ready to run.
  4. Start the app from a terminal:
    cd ~/Apps/HakkinFF1
    ./HakkinFF1
    After the first time, only these two lines are needed. In GNOME Files, you can instead right-click inside the folder and choose Open in Terminal, then type just ./HakkinFF1. Leave the terminal open while you use the app: closing it closes the app too.

The app opens on the Welcome view.

Why a terminal? GNOME Files, the file manager on Ubuntu, Zorin OS, and other GNOME desktops, doesn't start programs on a double-click. Double-clicking HakkinFF1 shows There is no app installed for "Executable" files, and no setting changes that. Other file managers, such as Dolphin on KDE and Thunar on Xfce, may still start it on a double-click. Starting it from a terminal works on every desktop, and any startup error is printed there.

Where things are stored. App settings, including the recent-projects list, are saved per user in ~/.config/HakkinFF1/appsettings.json (or under $XDG_CONFIG_HOME if you've set it). Each project is self-contained in its own folder, wherever you create it. To update, extract the newer release into the same folder, replacing the old files. Your settings and projects stay as they are.

If it doesn't start. Read the error in the terminal.

macOS

There are two macOS downloads: one for Apple Silicon Macs (M1 and later) and one for Intel Macs. To check which you have, open the Apple menu and choose About This Mac: it lists either a Chip (Apple Silicon) or a Processor (Intel). Each build includes the .NET runtime, so you don't need to install .NET.

  1. Download the latest macOS file for your Mac and verify its SHA-256.
  2. Pick a folder in your home folder, for example ~/Apps/HakkinFF1. The app reads shared extensions from an extensions folder next to the executable, which you'll want to be able to edit.
  3. Extract the zip into that folder from Terminal:
    mkdir -p ~/Apps/HakkinFF1
    unzip ~/Downloads/<file name>.zip -d ~/Apps/HakkinFF1
    You'll get:
    HakkinFF1/
      HakkinFF1                           the app
      LICENSE.txt                         Apache License 2.0
      NOTICE.txt                          copyright and licensing notice
      THIRD-PARTY-NOTICES.txt             licenses of the components the app includes
      TRADEMARKS.txt                      trademark policy for the HakkinFF1 name and icon
  4. Mark the app as executable, and clear the "downloaded from the internet" flag macOS puts on downloaded files:
    chmod +x ~/Apps/HakkinFF1/HakkinFF1
    xattr -c ~/Apps/HakkinFF1/HakkinFF1
    The app isn't signed or notarized by Apple. Without the second command, macOS refuses to open it.
  5. Start the app from Terminal:
    ~/Apps/HakkinFF1/HakkinFF1
    You can also double-click it in Finder, which opens a Terminal window that stays open while the app runs.

The app opens on the Welcome view.

Where things are stored. App settings, including the recent-projects list, are saved per user in ~/.config/HakkinFF1/appsettings.json. Each project is self-contained in its own folder, wherever you create it. To update, extract the newer release into the same folder, replacing the old files, then run both commands from step 4 again. Your settings and projects stay as they are.

If it doesn't start. If macOS says the app can't be opened because Apple cannot check it, open System Settings, go to Privacy & Security, and click Open Anyway next to the message about HakkinFF1. On an Apple Silicon Mac, if Terminal prints killed, give the app a local signature and try again:

codesign --force --sign - ~/Apps/HakkinFF1/HakkinFF1

The New Project view

The three kinds of project are all created from the Welcome view's New Project button. The form is the same for each; the Serializer you choose decides what kind of project you get. That choice is permanent for the life of the project.

The New Project view.
The New Project view.
FieldDetail
Parent Folder that will contain the projectThe folder in which the project's own folder will be created.
Project NameBecomes both the project folder's name and the project file's name.
Serializer How the project's files are read and written. The built-ins are listed first: rom, disch, and anomiex. After them come any extensions found in the app's extensions folder, then Custom... to browse for an extension DLL or a .hff1ext bundle. The list shows each serializer's identifying name, and its friendly name appears just below the dropdown.
Copy serializer to project folder Only used for extension serializers (it's disabled for the built-ins). Check it to copy the extension into the project's own extensions folder, so the project travels with its serializer.
Prototype PathThe existing file the new project is based on. A ROM project uses an NES ROM (*.nes); assembly projects use a disassembly archive (*.zip).
Import a config file? Optional. Check it and choose an FFHackster/FFHacksterEX .dat config file to bring its labels, smart tools, and tint settings into the new project. Anything the file doesn't provide gets the defaults.

Click Create to build the project and open it on the Landing view, or Cancel to return to the Welcome view. The app checks the prototype and config paths before it creates anything. If either file can't be found, it says so and leaves the disk untouched.

Creating a ROM project

A ROM project edits a copy of an NES ROM image directly. It's the simplest kind of project and needs nothing besides a ROM.

  1. On the Welcome view, click New Project.
  2. Choose the Parent Folder and type a Project Name.
  3. Leave Serializer set to rom (the default).
  4. For Prototype Path, browse to a clean Final Fantasy (NES) ROM. The app never modifies it; the project works on a copy.
  5. Optionally, import an FFHackster/FFHacksterEX .dat config.
  6. Click Create.

If you leave Prototype Path empty, the project starts with a blank (zero-filled) ROM. That's rarely what you want, so supply a ROM unless you mean to.

Files in a ROM project

<Parent Folder>\<Name>\
  <Name>.ff1r                      project file: name, type, serializer, description, author, link, dates
  <Name>.ff1d                      project data: labels, ROM/RAM values, editor and tool lists, editor settings
  <Name>.dialogue                  sprite dialogue routine definitions (plain text, hand-editable)
  workrom.nes                       the working ROM; every editor save writes to it
  <Name>.ff1s                      saved UI state for editors and tools (created when first needed)
  sharedextensionsettings.json      extension settings readable by any module (created when needed)
  privateextensionsettings.json     extension settings private to each module (created when needed)
  extensions\                       only present when an extension was copied into the project
FilePurpose
<Name>.ff1rThe file you open to load the project. JSON, holding the project's identity: its name and type, the serializer it uses (stored so the project still opens after it's moved), and the description, author, link, and created/last-edited dates you see in Project Settings.
<Name>.ff1dProject data, in JSON. It holds the label lists (maps, shops, battles, AI, teleports, and more), the ROM Values and RAM Values tables, the order and module choice for Landing's tools and editors, per-editor settings, smart tools, and tint settings.
<Name>.dialogueThe routine definitions the Sprite Dialogue editor uses, in a hand-editable format close to FFHacksterEX's own .dialogue files.
workrom.nesThe ROM being edited. Saving in any editor writes to it, so it's always up to date and ready for Publish or Run.
<Name>.ff1sUI state that needs to persist even when you cancel out of an editor, for example the In-Game Text editor's per-section View with DTE toggles.
*extensionsettings.jsonSettings saved by editor and tool extensions: one shared file and one private file.

Creating a Disch assembly project

A Disch project is built on Disch's Final Fantasy Disassembly 1.0. The assembly source is the real project: the app reads the game data out of it, and saving an editor writes the changed data back into the .asm and .bin source files. The ROM is assembled from that source when you need it.

  1. Download the Disch disassembly archive (a .zip). The project is created straight from the zip, so you don't need to extract it.
  2. On the Welcome view, click New Project.
  3. Choose the Parent Folder and type a Project Name.
  4. Set Serializer to disch (shown as Disch 1.0).
  5. For Prototype Path, browse to the disassembly .zip.
  6. Optionally, import an FFHackster/FFHacksterEX .dat config.
  7. Click Create. The app extracts the source into the project's asm folder and reads the game data from it.

No toolchain to install. To build workrom.nes, the app runs its own bundled copies of the cc65 assembler and linker (ca65/ld65), the same steps the disassembly's build.bat performs. That's why Publish and Run work for Disch projects on every platform, and why the archive's own ca65.exe/ld65.exe aren't copied into the project.

Files in a Disch project

<Parent Folder>\<Name>\
  <Name>.ff1a                      project file (assembly project)
  <Name>.ff1d                      project data, as for a ROM project
  <Name>.dialogue                  sprite dialogue routines, plus the bank addresses used to resolve source labels
  <Name>.asmrecs                   where each piece of editable data lives in the source
  asm\                              the disassembly source: the project's source of truth
    nesheader.bin, nes.cfg            iNES header and linker layout
    bank_00.dat ... bank_0F.asm       the 16 PRG banks
    bin\                              binary data blocks (weapon/armor/magic/enemy data, text, maps...)
    Constants.inc, variables.inc, macros.inc, table_*.tbl, build.bat, ...
  workrom.nes                       assembled from asm\ when Publish or Run needs it
  <Name>.ff1s, *extensionsettings.json, extensions\   as for a ROM project
FilePurpose
<Name>.ff1aThe file you open to load the project, in the same JSON format as .ff1r. The .ff1a extension marks it as an assembly project.
<Name>.asmrecsThe project's catalog of assembly data records. Each record maps one piece of game data the editors work with (weapon data, shop data, a lookup table, and so on) to the source file and label it lives at. Saving an editor writes back only the records that editor changed. It starts as a copy of the app's built-in Disch catalog, and records added to the app in later versions are merged in when you open the project.
asm\The extracted disassembly. You can open and edit these files in your own editor too. The app reads the game data back from the source whenever it opens the project.
<Name>.dialogueAs for a ROM project. In an assembly project its bankaddr= entries also tell the app which address each source label corresponds to.
workrom.nesA build output, not a source file. It's rebuilt whenever it's missing or older than your last save.

Creating an Anomie assembly project

An Anomie project is built on Anomie's Final Fantasy disassembly, shown in the app as Anomiex. Its bank listings (b00.txt to b15.txt) are the project's source. Saving writes changed data back into the matching lines of those listings.

  1. Download the Anomie disassembly archive (a .zip). Don't extract it.
  2. On the Welcome view, click New Project.
  3. Choose the Parent Folder and type a Project Name.
  4. Set Serializer to anomiex.
  5. For Prototype Path, browse to the disassembly .zip. The app finds the bXX.txt files whether they're at the archive's root or inside a folder (newer releases use ff/).
  6. Optionally, import an FFHackster/FFHacksterEX .dat config.
  7. Click Create.

No build step. Anomie's listings already contain the final bytes, so the app writes workrom.nes directly, without assembling anything.

The app can only read the parts of the ROM that its Anomiex catalog covers. Anything the catalog doesn't cover reads back as zero.

Files in an Anomie project

<Parent Folder>\<Name>\
  <Name>.ff1a                      project file (assembly project)
  <Name>.ff1d                      project data, as for a ROM project
  <Name>.dialogue                  sprite dialogue routine definitions
  <Name>.asmrecs                   where each piece of editable data lives in the listings
  asm\                              the disassembly: the project's source of truth
    b00.txt ... b15.txt               one listing per bank
  workrom.nes                       written from the listings when Publish or Run needs it
  <Name>.ff1s, *extensionsettings.json, extensions\   as for a ROM project

These files do the same jobs as in a Disch project. The difference is that <Name>.asmrecs starts from the app's Anomiex catalog, and its records point at lines in the bXX.txt listings rather than at .asm/.bin files.

Loading an existing project

On the Welcome view, click Load Project. The Load Project view offers four sources; the Load Project view section has the details.

SourceWhat it does
From ProjectBrowse to a project file (.ff1r or .ff1a) and open it.
From MRUChoose from recently opened projects. Only shown once you've opened or created one; the two most recent are also listed beneath it as direct links.
From ArchiveUnpack an HFF1 archive (.hff1zip, made with Landing's export button) into a new folder under a new name, then open it.
Clone ExistingCopy an existing project into a new folder under a new name, then open the copy.

When a project opens, the app shows its Landing view.