Fate/instruct API

What is the instruct file

Every FPX mod requires a patch.json file in its root directory, which defines the mod and contains the instructions on how to apply it. It does follow normal JSON formatting standards. This json file is the 'instruct' file, as it literally instructs the Fate Patcher in how to apply files. An "empty" mod to use as a starting template can be downloaded here.

General data

The instruct file will generally start with the following information. Only the bold entries are required; the rest are optional, but will be useful for users managing their mods with the GUI front-end eventually distributed with FPX. Unless otherwise mentioned, assume all elements are strings.

name	Name of your mod
version	Version of your mod. Supports advanced versioning*
author	Primary mod author or team name
web	URL to be opened if the user is checking for updates
description	Describe the mod in a sentence or two
contributors	List of individual contributors/authors, if multiple.

Following these informational elements, you provide the actual 'instructive' content that defines how your mod is set up. This content includes one or more of six possible 'operations'. Below lists each possible operation. Where a ellipses (…) occurs in the script file, is where something (can) continue/repeat in the given sequence.

Index operations

Index operations are key/value pairs that "index" a file under a given name, making it patchable. Most OG *.dat files are indexed by default.

"index": {
  "INDEX_NAME": "Path/to/file in the FATE game directory",
  ...repeat for every index being added
},

Copy operations

Given a folder destination and a series of files, the Copy operation copies those files into the destination. This is used to provide assets which are referenced by patch data.

"copy": [
  {
    "folder": "Path/to/file in the FATE game directory",
    "content": [
      "path/to/file from your mod folder, to your asset being deployed",
      ...repeat per asset being deployed to the destination
    ],
  },
  ...repeat the {} per destination folder
],

Patch operations

Given a valid index, the Patch operation adds new file contents to the end of the original indexed file, in effect adding new content to the game.

"patch": [
  {
    "container": "valid index name",
    "content": [
      "path/to/file from your mod folder, to your text file containing the data to append",
      ...
    ],
  },
  ...repeat the {} per index being patched
],

Sequence operations

Sequence operations are similar to a copy operation, but allows the file name to be sequentially generated at deployment. This will mostly only be used when adding new music to the game.

"sequence": [
  {
    "folder": "Path/to/file in the FATE game directory",
    "file": "destination file name",
    "content": [
      "path/to/file from your mod folder, to your asset being deployed",
      ...
    ],
  },
  ...repeat the {} per destination folder and/or file
],

Filter operations

The most powerful yet complex operation, Filters are when you attach a lua file to a given index. This is executed at the end of mod deployment. Refer to the filter script lua API.

"script": [
  {
    "container": "valid index",
    "file": "path/to/file.lua from your mod directory",
  },
  ...repeat {} per index and/or filter script to apply
],

note: Filter scripts may execute lua direclty, but they are limited within a sandbox for security purposes. They can only write directly to the file they are operating on, and can only see your game and your mod files only.

Override operations

Override operations tell FPX to NOT grab the master copy of a file during the patch process. This is useful if you have overwritten a file that is usually indexed and exists within the base game.

"override": [
  "valid index name",
  ...repeat for every overridden indexes
],

Example instruct file

This is part of the instruct file for the Dungeonology expansion, a mod that adds multiple assets across the entire game.

{
	"name": "Dungeonology Expansion",
	"version": "1.0.0",
	"author": "Luxen De'Mark",
	"web": "https://www.nexusmods.com/fate/mods/20",
	"description": "A massive dungeon expansion to FATE",
	"index": {
		"TEMPLATES_MASTER": "TEMPLATES\\manifest.dat",
	},
	"sequence": [
		{
			"folder": "MUSIC",
			"file": "dungeon?.ogg",
			"content": [
				"Music\\imposing.ogg",
				"Music\\unsettled house.ogg",
				"Music\\Fog under the second street light.ogg",
				"Music\\Aquarinonu.ogg",
				"Music\\Apocalypse.ogg",
			],
		},
		{
			"folder": "MUSIC",
			"file": "town?.ogg",
			"content": [
				"Music\\Green-fields.ogg",
				"Music\\Pho Magic.ogg",
				"Music\\Wild waters in the woods.ogg",
			],
		},
	],
	"copy": [
		{
			"folder": "SOUNDS",
			"content": [
				"Props\\ice_crystal\\crystal_ting.wav",
			],
		},
		{
			"folder": "PROPS",
			"content": [
				"Props\\lush_leaf\\lushleaf_obj.MDL",
				"Props\\lush_leaf\\lushleaf_alpha.png",
				"Props\\lush_leaf\\lushleaf_color.png",
			],
		},
		{
			"folder": "ICONS",
			"content": [
				"Items\\Windlass\\windlass_alpha.png",
				"Items\\Windlass\\windlass_color.png",
			],
		},
		{
			"folder": "ITEMS",
			"content": [
				"Items\\Windlass\\windlass_obj.mdl",
				"Items\\Windlass\\windlass_obj_color.png",
				"Items\\Windlass\\windlass_obj_ref.png",
			],
		},
	],
	"patch": [
		{
			"container": "ITEMS_US",
			"content": [
				"Items\\Spellbooks\\spellbook_items.txt",
				"Items\\Gems\\Amber.txt",
				"Items\\Compass\\compass_item.txt",
				"Items\\Totem Rod\\totem_rod.txt",
				"Items\\Bamboo Rod\\bamboo_rod.txt",
			],
		},
		{
			"container": "TEMPLATES_MASTER",
			"content": [
				"Dungeons\\manifest_patch.txt",
			],
		},
	],
}

Additional notes

• File paths must use a double-backslash. A single backslash is used as an escape character in lua, which FPX is written in.