parser

Documentation

Overview

Package parser is the public FFPL save-file parser.

It extracts ACLoadout records from PPSSPP save states (.ppst) and decrypted Armored Core: Formula Front save files (SDDATA.BIN).

This package is the community-auditable surface of the FFPL stack. It contains no server logic, no match-runner code, and no rating engine. Users can verify that their save data is read correctly and that no unexpected data is extracted or transmitted.

Supported regions: US (ULUS-10061), JP (ULJS-19001). Europe (ULES-00622) planned.

Index

• Variables
• type ACLoadout
  • func ParseSDDATA(binPath string, schemaPath string) ([]ACLoadout, error)
  • func ParseSDDATARaw(data []byte, schemaBytes []byte) ([]ACLoadout, error)
• type ACStructSchema
• type IdentifierSchema
• type SchemaWrapper
• type TeamColorScheme

Variables

var ChipDictionary = map[uint8]string{
	1:  "WEP-1",
	6:  "NAT-1",
	10: "ATF-4",
	14: "MOS-1",
	32: "ATB-1",
	42: "WEC-1",
}

ChipDictionary maps raw chip byte values to human-readable chip names. Source: Starter_Chips.bin dictionary.

Types

type ACLoadout

type ACLoadout struct {
	// ID is the PocketBase record ID — empty until pushed to the league server.
	ID string `json:"id"`
	// Profile is the AC pilot name as stored in the save (UTF-8 or decoded Shift-JIS).
	Profile string `json:"profile"`
	// AnchorHex is the raw byte offset of this AC in the source file (debug only).
	AnchorHex string `json:"anchorHex"`
	// TamperHash is a SHA-256 of the raw AC struct bytes — tamper-evident fingerprint.
	TamperHash string `json:"tamperHash"`
	// Region is "US" or "JP" depending on the detected game ID in the save.
	Region string `json:"region"`
	// PartHashes maps slot names ("Head", "Core", "Legs", …) to their internal part IDs.
	PartHashes map[string]uint16 `json:"part_hashes"`
	// AIPerformance maps AI tuning slider names to their 0–100 values.
	AIPerformance map[string]uint8 `json:"ai_performance"`
	// OperationsGrid is the 6×6 AI logic chip grid.
	OperationsGrid [][]string `json:"operations_grid"`
	// ColorScheme holds the team colour selection; nil means use the game default.
	ColorScheme *TeamColorScheme `json:"color_scheme,omitempty"`
}

ACLoadout is a single verified AC build extracted from a save file. It is the canonical data type shared between the public parser and all FFPL backend services.

func ParseSDDATA

func ParseSDDATA(binPath string, schemaPath string) ([]ACLoadout, error)

ParseSDDATA is the file-path convenience wrapper around ParseSDDATARaw. binPath is the path to the save file; schemaPath is the path to data/ac_memory_schema.json.

func ParseSDDATARaw

func ParseSDDATARaw(data []byte, schemaBytes []byte) ([]ACLoadout, error)

ParseSDDATARaw is the primary entry point for user-supplied save data. It accepts both raw .ppst (ZSTD-compressed PPSSPP save states) and decrypted SDDATA.BIN files (via Apollo Save Tool / SaveDeemer). schemaBytes is the contents of data/ac_memory_schema.json.

type ACStructSchema

type ACStructSchema struct {
	Identifier           IdentifierSchema `json:"identifier"`
	LoadoutOffsets       map[string]int   `json:"loadout_offsets"`
	AIPerformanceOffsets map[string]int   `json:"ai_performance_offsets"`
	OperationsGrid       map[string]int   `json:"operations_grid"`
}

ACStructSchema holds the per-field byte offsets from ac_memory_schema.json.

type IdentifierSchema

type IdentifierSchema struct {
	AnchorString string `json:"anchor_string"`
	Encoding     string `json:"encoding"`
	Length       int    `json:"length"`
}

IdentifierSchema is the anchor-string descriptor in ac_memory_schema.json.

type SchemaWrapper

type SchemaWrapper struct {
	ACStruct ACStructSchema `json:"ac_struct"`
}

SchemaWrapper is the top-level wrapper around ac_memory_schema.json.

type TeamColorScheme

type TeamColorScheme struct {
	WeaponMain uint32 `json:"weapon_main"`
	WeaponSec  uint32 `json:"weapon_sec"`
	FrameMain  uint32 `json:"frame_main"`
	FrameSec   uint32 `json:"frame_sec"`

	CustomWeaponMainBGRA *uint32 `json:"custom_wm_bgra,omitempty"`
	CustomWeaponSecBGRA  *uint32 `json:"custom_ws_bgra,omitempty"`
	CustomFrameMainBGRA  *uint32 `json:"custom_fm_bgra,omitempty"`
	CustomFrameSecBGRA   *uint32 `json:"custom_fs_bgra,omitempty"`
}

TeamColorScheme holds the four colour indices applied to all ACs in a team. Color indices for weapon (0=BLACK 1=RED 2=YELLOW 3=GREEN 4=BLUE 5=WHITE) and frame (0=RED 1=YELLOW, remaining 2–11 in display-grid order). CustomXXXBGRA overrides let the match runner patch the game's colour palette at match start. Format: packed LE uint32 = Blue|(Green<<8)|(Red<<16)|(Alpha<<24). nil (omitted from JSON) = use game default palette.