Site Tools


developer_integration

Developer Integrations

NOTE: Free Enterprise is open source software. For information about developing for the game itself, see the Developer Documentation.

FE also exposes some features meant to assist developers looking to create tools related to the randomizer. These features are outlined here.

Embedded Metadata

Each randomized Free Enterprise ROM contains a small embedded JSON document describing its basic metadata. The length of this document is specified at address 0x1FF000 as a little-endian 32-bit integer, and the JSON document (encoded in utf-8) follows immediately after.

In-game Tracking

Developers wishing to create automated trackers can make use of the same memory values used by the in-game tracker to read their data, detailed below:

  • 7E:1500-1502 : Found key items (1 bit per item)
  • 7E:1503-1505 : Used key items (1 bit per item)
  • 7E:1510-151F : Checked potential key item locations (1 bit per location)
  • 7E:1520-153F : Completed objectives (1 byte per objective, in the same order as in the metadata)
  • 70:7080-70A1 : Locations where each key item was found (2 bytes per item)

Bit flags are in little-endian order, as are the 2-byte location values.

Key items are indexed in the following order:

Index Item
0x00 Package
0x01 SandRuby
0x02 Legend Sword
0x03 Baron Key
0x04 TwinHarp
0x05 Earth Crystal
0x06 Magma Key
0x07 Tower Key
0x08 Hook
0x09 Luca Key
0x0A Darkness Crystal
0x0B Rat Tail
0x0C Adamant
0x0D Pan
0x0E Spoon
0x0F Pink Tail
0x10 Crystal

Potential key item locations are indexed/numbered as follows:

Index Location
0x0020 Starting item
0x0021 Antlion nest
0x0022 Defending Fabul
0x0023 Mt. Ordeals
0x0024 Baron Inn
0x0025 Baron Castle
0x0026 Edward in Toroia
0x0027 Cave Magnes
0x0028 Tower of Zot
0x0029 Lower Bab-il boss
0x002A Super Cannon
0x002B Luca
0x002C Sealed Cave
0x002D Feymarch chest
0x002E Rat Tail trade
0x002F Yang's wife (for finding Yang)
0x0030 Yang's wife (Pan trade)
0x0031 Feymarch queen
0x0032 Feymarch king
0x0033 Odin throne
0x0034 From the Sylphs
0x0035 Cave Bahamut
0x0036 Pale Dim/Murasame altar
0x0037 Wyvern/Crystal Sword altar
0x0038 Plague/White spear altar
0x0039 D.Lunar/Ribbon chest 1
0x003A D.Lunar/Ribbon chest 2
0x003B Ogopogo/Masamune altar
0x003C Tower of Zot monster-in-a-box
0x003D Eblan monster-in-a-box 1
0x003E Eblan monster-in-a-box 2
0x003F Eblan monster-in-a-box 3
0x0040 Lower Bab-il monster-in-a-box 1
0x0041 Lower Bab-il monster-in-a-box 2
0x0042 Lower Bab-il monster-in-a-box 3
0x0043 Lower Bab-il monster-in-a-box 4
0x0044 Cave Eblan monster-in-a-box
0x0045 Upper Bab-il monster-in-a-box
0x0046 Cave of Summons monster-in-a-box
0x0047 Sylph Cave monster-in-a-box 1
0x0048 Sylph Cave monster-in-a-box 2
0x0049 Sylph Cave monster-in-a-box 3
0x004A Sylph Cave monster-in-a-box 4
0x004B Sylph Cave monster-in-a-box 5
0x004C Sylph Cave monster-in-a-box 6
0x004D Sylph Cave monster-in-a-box 7
0x004E Giant of Bab-il monster-in-a-box
0x004F Lunar Path monster-in-a-box
0x0050 Lunar Core monster-in-a-box 1
0x0051 Lunar Core monster-in-a-box 2
0x0052 Lunar Core monster-in-a-box 3
0x0053 Lunar Core monster-in-a-box 4
0x0054 Lunar Core monster-in-a-box 5
0x0055 Lunar Core monster-in-a-box 6
0x0056 Lunar Core monster-in-a-box 7
0x0057 Lunar Core monster-in-a-box 8
0x0058 Lunar Core monster-in-a-box 9
0x0059 Rydia's Mom
0x005A Fallen Golbez (vanilla Crystal location)
0x005D Objective completion

MSU-1 Support

Free Enterprise supports custom MSU-1 soundtracks. The process of setting up your ROM/emulator/cart with a custom soundtrack is outside the scope of this document, but for those who wish to build soundtrack lists, the following table indicates which track numbers correspond to which songs. (Note that fade-in and fade-out of MSU-1 tracks is not supported.)

If one of these tracks is missing from your custom soundtrack, the original in-game track will play in its place.

Track No. Song
0 None (FF4 uses song 0 to mean “stop music”)
1 Prologue
2 Tower of Wishes
3 (unused fanfare)
4 Yellow Chocobo
5 Black Chocobo
6 Underworld
7 Zeromus Battle
8 Victory Fanfare
9 Town
10 Rydia's Theme
11 Decisive Battle
12 Mountain
13 Overworld
14 Big Whale
15 Sad Music (“Cry In Sorrow”)
16 Sleep
17 Golbez's Theme
18 Edward's Theme (will not be played on MSU-1)
19 Rosa's Theme
20 Baron Castle
21 Prelude
22 “Somewhere In The World”
23 Tower of Bab-il
24 Airship
25 Tower of Zot
26 Boss Battle
27 Giant of Bab-il / Lunar Core
28 Sylph Cave / Feymarch
29 Destruction
30 Lunar Path
31 Surprise
32 Dwarf Castle
33 Palom & Porom's Theme
34 Calbrena Music
35 “Hurry!”
36 Cid's Theme
37 Cave
38 Dancer Music
39 Battle
40 Damcyan / Eblan
41 Character Joined
42 Character Died
43 Chocobo Forest
44 Cecil / Red Wings (fade-in start)
45 “Suspicions”
46 Fabul
47 Long Fanfare (eg. became a paladin)
48 Fat Chocobo
49 Moon
50 Toroia Castle
51 Mysidia
52 Lunar Subterrane
53 Ending Part 1
54 Ending Part 2
55 End Credits

Seed Generation API

There is an API for programmatically generating seeds from the online randomizer; however it requires an API key to access and is currently restricted to developers working on support software for FE community races. The API doc is pasted here verbatim:

Slapdash FE Seed Generation API
-------------------------------

You will need an API key, you get these by talking to b0ardface.

Overall flow for generating a seed:

1. POST to /api/generate with your desired flags and seed (seed optional)
2. Monitor the status of the generation task at /api/task until finished
3. Retrieve the generated seed info from /api/seed

Note that if you are trying to generate a seed that already has been
cached on the server, you might proceed directly from 1 to 3.

--------------------------------------------------------------

To initiate generation of a seed, make a POST request to:

  /api/generate?key=<api_key>

The body of this request should be a JSON object with the
following format:

  {
    "flags"      : "<desired flag string>",
    "seed"       : "<desired randomization seed; optional>",
    "metaconfig" : <optional metaconfiguration object; see below>
  }

NOTE: For backwards compatibility, the flags and seed values may be
passed as URL query parameters or formdata values in the body instead.
To use metaconfigurations, you must use the JSON parameter format.

The metaconfiguration object, and all fields within it, are optional.
Note that when a metaconfiguration is specified, a "unique" seed is
generated -- rerunning the same generation parameters later will
result in a different seed.

The metaconfig object has this format:

  {
    "hide_flags" : <bool>
  }

The generate call will return a JSON response in one of the following
formats:

  // If the generation process started correctly
  {
    'status' : 'ok',
    'task_id' : <task_id:string>
  }

  // If the requested seed has already been generated
  // and is still cached on the server
  {
    'status' : 'exists',
    'seed_id' : <seed_id:string>
  }

  // If something went wrong
  {
    'status' : 'error',
    'error' : <error_msg:string>
  }

--------------------------------------------------------------

To monitor the status of a generation task in progress,
make a GET query to:

  /api/task?key=<api_key>&id=<task_id>

This will return a JSON response in one of the following formats:

  // If the task is waiting to start
  {
    'status' : 'pending'
  }

  // If the task is in progress
  {
    'status' : 'in_progress'
  }

  // If the task has completed successfully
  {
    'status' : 'done',
    'seed_id' : <seed_id:string>
  }

  // If the task failed
  {
    'status' : 'error',
    'error' : <error_msg:string>
  }

--------------------------------------------------------------

To get info about a generated seed, make a GET query to:

  /api/seed?key=<api_key>&id=<seed_id>

This will return a JSON response in one of the following formats:

  // If successful (example shown below)
  {
    "status":       "ok",
    "version":      "0.3.0",
    "seed":         "KW1FDT93",
    "flags":        "Ji K Ps Ca -rescue T4gr S4 B -whyburn Etf Xsbk",
    "verification": "Claw/Staff/Tent/Feather",
    "url":          "http://ff4fe.com/get?id=bAAMAJGQEAMCpoA4.KW1FDT93"
  }

  // If something went wrong
  {
    'status' : 'error',
    'error' : <error_msg:string>
  }
developer_integration.txt · Last modified: 2024/07/14 02:26 by wylem