Core Definition Files

A core is comprised of several files, which all must be placed into the core’s folder.

  • core.json: Main core definition file.
  • audio.json: Audio features. (upcoming feature)
  • data.json: List of all data slots.
  • input.json: Description of custom button mappings for the core. (upcoming feature)
  • interact.json: List of custom UI elements for the in-core menu, which can be used to interact with the core while running.
  • variants.json: Variants list for supporting small variations of a base core.
  • video.json: Video settings. Defines the video scaler settings used, namely resolution for each of the 8 scaler slots.

Additionally, a core may allow users to select assets together in a predetermined group as an "instance". These instance JSON files are stored as assets themselves in the Assets folder and follow the same rules for their location.

  • <instance>.json: Instance definition file, stored as an asset.

Folder Naming Convention

The core folder name should follow this convention: AuthorName.CoreName where AuthorName and CoreName correspond to author and shortname in core.json respectively.

core.json

Describes the core in general terms, framework requirements, and a list of bitstreams.

magic: string
Must be APF_VER_1.

metadata

platform_ids: array
Array of supported platform strings. Refer to platform list. If no platforms are specified (empty array) then core is standalone. This affects where assets and saves are stored in the filesystem.

Maximum 4 platforms.

shortname: string
Short name used for filesystem. Maximum length 31 characters.

description: string
Short description. Maximum length 63 characters.

author: string
Name of the core author. Maximum length 31 characters.

url: string
URL to more information about core. Maximum length 63 characters.

version: string
Version of the release. SemVer is highly encouraged. Maximum length 31 characters.

date_release: string
Date of the release in this format: 2022-12-31. The date the release was made. Maximum length 10 characters.

framework

target_product: string
Must be "Analogue Pocket".

version_required: string
Minimum firmware version required, in the format "1.1"

sleep_supported: boolean
If sleep is supported by the core. Additionally, a core can selectively allow or deny each individual save state creation request.

chip32_vm: string
Filename of Chip32 program. If present, the program will take over all loading operations. File must be present in the root of the core’s folder. Maximum length 15 characters.

dock

supported: boolean
Whether Dock should be allowed. Must be true.

analog_output: boolean
Does core support analog output timing modes? Upcoming feature.

hardware

link_port: boolean
Whether link port is utilized.

cartridge_adapter: integer
0: Cartridge used, no adapter check. -1: Cartridge unused and unpowered.

cores

A maximum of 8 cores is allowed.

name: string
Identifier for the bitstream used in debugging. Optional. For debugging purposes. Maximum length 15 characters.

id: integer / hex string
Identifier.

filename: string
Filename of the bitstream (bit-reversed). Maximum length 15 characters.

Sample File

{
  "core": {
    "magic": "APF_VER_1",
    "metadata": {
      "platform_ids": [],
      "shortname": "SampleCore",
      "description": "This is a sample core",
      "author": "developer",
      "url": "https://",
      "version": "1.0.0-preview",
      "date_release": "2022-04-20"
    },
    "framework": {
      "target_product": "Analogue Pocket",
      "version_required": "1.1",
      "sleep_supported": true,
      "dock": {
        "supported": true,
        "analog_output": false
      },
      "hardware": {
        "link_port": false,
        "cartridge_adapter": -1
      }
    },
    "cores": [
      {
        "name": "default",
        "id": 0,
        "filename": "bitstream.rbf_r"
      }
    ]
  }
}

audio.json

Describes the audio parameters. (upcoming feature)

magic: string
Must be APF_VER_1.

Sample File

{
  "audio": {
    "magic": "APF_VER_1"
  }
}

data.json

Describes up to 32 possible data slots. Each slot can be loaded with an asset, loaded and saved to a nonvolatile save file, and contains a number of options.

magic: string
Must be APF_VER_1.

data_slots (array)

A maximum of 32 data slots is allowed.

name: string
Name of the data slot. Maximum length of 15 characters.

required: boolean
If true, Pocket will check for a filename. If none is present, it will spawn a file browser in the location it expects the file to be in.

parameters: integer / hex string
Bitmap for the slot's configuration. See Parameters Bitmap below.

nonvolatile: boolean
If true, slot will be both loaded and unloaded on core exit. Related functionality with parameters above and Parameters Bitmap.

deferload: boolean
If true, slot will not be loaded, but its size and ID will still be communicated to the core, and the core may read/write it with Target commands.

secondary: boolean
If true, slot will be ignored, and will only be loaded if referenced in a selected variant

filename: string
Expected filename for the slot. See Parameters Bitmap below. Maximum length of 31 characters.

extensions: string
Array of up to 4 supported file extensions. Each extension may be up to 7 characters. If a file browser is spawned, it will filter the files shown.
Example: "extensions": ["bin", "sav"].

size_zero: integer / hex string
If specified, or non-zero, the filesize will be checked and only loaded if the size matches. 32-bit unsigned.

size_maximum: integer / hex string
If specified, or non-zero, the file will not load unless it is equal or smaller in size than this value. 32-bit unsigned.

address: integer / hex string
Load address. 32-bit unsigned.

Parameters Bitmap

Bit PositionDescriptionCleareadSet
0User-reloadableSlot is reloadable in Core UI
1Core-specific fileFile common to platform, not any coreFile specific to this core only
2Nonvolatile filenameFilename as written in the slotFilename cloned from slot 0, with this slot's extension appended
3Read-onlyFile may be modifiedFile is read-only
4Instance JSONNormal assetTreat a JSON loaded into this slot as an instance description. Must also be flagged as "core-specific file", and only valid in first slot.
5Initialize nonvolatile data on loadData is loaded if it exists, otherwise nothing is written to this nonvolatile slotData is loaded if it exists, otherwise the slot's memory is overwritten with 0xFF's up to size_maximum
  • A core-specific file is distributed with the core itself, and does not share anything with its platform. The path would be: /Assets/<platform>/AuthorName.CoreName/examplefile.bin. It could also be a nonvolatile file, which would be located in /Saves/<platform>/AuthorName.CoreName/examplefile.bin.
  • A nonvolatile data slot, such as a save file, may be generated for every time the core is started based on the filename and path of the primary data slot, which is slot 0. Additionally, this file will take on the extension of the first extension in the nonvolatile data slot's extension list.
  • An instance JSON, if specified, will specify exact filenames for some or all other slots and select a variant to load. This can be useful if a core requires many different assets to be loaded.

A slot that is both nonvolatile/named from slot0 and read only would have the bitmap computed as follows:

(1 << bit2) + (1 << bit3) = 
4 + 8 = 
12

Sample File

{
  "data": {
    "magic": "APF_VER_1",
    "data_slots": [
      {
        "name": "Background Pic",
        "id": 1,
        "required": true,
        "parameters": 3,
        "extensions": [
          "bin"
        ],
        "size_exact": 0,
        "size_maximum": 8388608,
        "address": "0x00000000"
      },
      {
        "name": "Audio Sample",
        "id": "0xFC0",
        "required": true,
        "parameters": 3,
        "extensions": [
          "wav"
        ],
        "size_maximum": "0x4000000",
        "address": "0x00400000"
      },
      {
        "name": "Save Data",
        "id": 123,
        "required": true,
        "parameters": 7,
        "extensions": [
          "sav"
        ],
        "size_maximum": 8192,
        "address": "0x02000000"
      }
    ]
  }
}

<instance.json>

An instance file is stored in the same place that an asset would be - following platform path conventions (and core name, possibly). The location that a core will expect the instance JSON to be located from will be exactly the same as any other data slot. The Parameters Bitmap of a data slot determines if the data slot will be treated as common to a platform (in the “common” folder) or core-specific (in a subfolder named after the core itself).

To use an instance JSON, the data slot entry in data.json must have:

  • an extension list containing “json” so that the file browser filter will display JSON files
  • a Parameters Bitmap with the “Instance JSON” bit set

The filenames listed below should be located starting in the same folder as the instance JSON, but may be located in any number of subfolders.

magic: string
Must be APF_VER_1.

data_path: boolean
If true, the variant matching ID will be loaded.

variant_select

id: integer / hex string
ID of variant to select as part of the load process. Limited to 16-bit unsigned.

select: boolean
If true, the variant matching ID will be loaded.

Variants are currently not yet supported

data_slots (array)

A maximum of 32 data slots is allowed.

id: integer / hex string
ID of data_slot . Limited to 16-bit unsigned.

filename: string
Exact filename, including any subfolders. Relative paths are not supported. Maximum length of 255 characters.

memory_writes (array)

A maximum of 8 entries is allowed.

address: integer / hex string
Address to write to. 32-bit unsigned.

data: integer / hex string
Data to be written. 32-bit unsigned.

Sample File

{
  "instance": {
    "magic": "APF_VER_1",
    "variant_select" : {
      "id" : 777,
      "select" : false
    },
    "data_path": "basefolder1/",
    "data_slots": [
      {
        "id": 1,
        "filename": "samplefolder/sample.bin"
      },
      {
        "id": 99,
        "filename": "samplefolder/sample.wav"
      }
    ],
    "memory_writes": [
      {
        "address": "0x00000004",
        "data": "0x12345678"
      }
    ]
  }
}

input.json

Describes the input mappings. Used for button mappings (or other HID devices in the future). This is an upcoming feature.

magic: string
Must be APF_VER_1.

Sample File

{
  "input": {
    "magic": "APF_VER_1"
  }
}

interact.json

Describes any custom UI elements to be displayed in the Core UI settings menu. This is an upcoming feature.

magic: string
Must be APF_VER_1.

Sample File

{
  "interact": {
    "magic": "APF_VER_1"
  }
}

variants.json

Describes up to 8 core variations. These can be used to describe very similar hardware with just a few asset changes. This is an upcoming feature.

Each variant may select a particular bitstream and override data slots with alternate ones as well as write arbitrary data into the core’s address space.

magic: string
Must be APF_VER_1.

variant_list (array)

Maximum of 8 variants.

name: string
Maximum length of 15 characters.

id: integer / hex string
ID number. Limited to 16-bit unsigned.

core_select: object
Contains a child integer object core_id which specifies the bitstream ID to load.

data_overridemagic: array
List of data slot overrides.

memory_writes: array
List of memory writes to tell the bitstream about the selected variant.

data_override (array)

Maximum of 8 variants.

data_id_to: integer / hex string
ID number of the data slot to be replaced. Limited to 16-bit unsigned.

data_id_from: integer / hex string
ID number of the data slot replacing the above. It may be flagged as secondary. Limited to 16-bit unsigned.

memory_writes (array)

Maximum of 8 variants.

address: integer / hex string
Address to write to. 32-bit unsigned.

data: integer / hex string
Data to be written. It may be flagged as secondary. 32-bit unsigned.

Sample File

{
  "variants": {
    "magic": "APF_VER_1",
    "variant_list": [
      {
        "name": "Variant1",
        "id": 0,
        "core_select": {
          "core_id": 0
        },
        "data_override": [
          {
            "data_id": 3,
            "data_id_override": 300
          }
        ],
        "memory_writes": [
          {
            "address": "0x00000004",
            "data": "0x12345678"
          },
          {
            "address": "0x02000200",
            "data": "0xabcdabcd"
          }
        ]
      },
      {
        "name": "Variant2",
        "id": 1,
        "core_select": {
          "core_id": 1
        },
        "data_override": [
          {
            "data_id": "0x100",
            "data_id_override": "0x103"
          }
        ]
      }
    ]
  }
}

video.json

Describes up to 8 video preset scaling configurations.

Cores may switch between any of these resolutions at runtime.

Future features will enable further control over additional scaler/display mode options.

magic: string
Must be APF_VER_1.

scaler_modes (array)

Maximum of 8 scaler modes.

width: integer
Active width in pixels.

height: integer
Active height in pixels.

aspect_w: integer
Aspect ratio width.

aspect_h: integer
Aspect ratio height.

rotation: integer
Degrees to rotate the image. Valid values are 0, 90, 180, 270.

mirror: integer
Reflect the display direction. May be combined with rotation. Bit1: left/right mirror Bit0: up/down mirror.

Sample File

{
  "video": {
    "magic": "APF_VER_1",
    "scaler_modes": [
      {
        "width": 320,
        "height": 240,
        "aspect_w": 4,
        "aspect_h": 3,
        "rotation": 0,
        "mirror": 0
      },
      {
        "width": 512,
        "height": 240,
        "aspect_w": 4,
        "aspect_h": 3,
        "rotation": 0,
        "mirror": 0
      },
      {
        "width": 480,
        "height": 270,
        "aspect_w": 16,
        "aspect_h": 9,
        "rotation": 0,
        "mirror": 0
      }
    ]
  }
}