madden-franchise v3.4.0

madden-franchise

Read and write Madden Franchise files using NodeJS.

Usage

const Franchise = require('madden-franchise');

let franchise = await Franchise.create([path to file], [options]);
let table = franchise.getTableByName('Player');

// Read all records...
await table.readRecords();
console.log(table.records[0].FirstName); // Alts: table.getValueByKey('FirstName') or table.getFieldByKey('FirstName').value

// OR Save time & memory by reading certain fields...
await table.readRecords(['FirstName', 'LastName'])

table.records[0].FirstName = 'John';
table.records[0].LastName = 'Madden';

await franchise.save();

Documentation

Supported Games

Quick Start

Initializing

(New for v3.3.0): let franchise = await FranchiseFile.create(filePath, [,settings]) returns a Promise that resolves once the file is ready.

(Old): new FranchiseFile(filePath, [,settings]).on('ready', file => { // your code here }) the old way still works to preserve backwards compatibility.

Franchise File Settings

{
  // SAVE ON CHANGE
  saveOnChange: true/false [default: false] // if any field value is changed, the file will be saved automatically. You won't need to call .save() every time.

  // SCHEMA OVERRIDE - manually specify a schema version and path to use
  schemaOverride: {
    'major': int,  // the schema major version
    'minor': int,  // the schema minor version
    'gameYear': int, // the Madden year (19 or 20)
    'path': string // path to the schema file
  }

  // SCHEMA DIRECTORY - add a custom directory of schemas for the system to automatically choose from in addition to the bundled ones.
  schemaDirectory: string // path to a directory containing schema files to choose

  // AUTO PARSE - specify if you want the system to automatically parse all tables in the file, or if you want to explicity call file.parse()
  autoParse: true/false [default: true]

  // AUTO UNEMPTY - specify if you want the system to automatically determine if an empty field should become un-empty once you edit it.
  // Warning: may have unintended side-effects if you batch import. Enable with caution.
  autoUnempty: true/false [default: false]
}

Terminology

Schemas

Schemas define human-readable field (column) names for each table. They make editing files much easier and more straightforward. Schemas are located within the game files and can be found using a tool like Frosty.

Ex: a schama defines that the Player table has 300+ fields, that the FirstName field is a string containing up to 30 characters, or that the AwarenessRating is an integer with a maxValue of 127 (yes, really).

New for v3.3.0 - the library can support schema-less or partial schemas. Tables will be read with generic field names and each field will default to the int data type. This can lead to unexpected results in-game and very likely will cause crashes. Prefer to edit tables with schemas defined unless you are an advanced user.

Cloning/Forking Guide

1. npm install all dependencies
2. Make your changes
3. You can run the 700+ regression tests using mocha tests\**\*.spec.js. Test data is included with this repository.

Extended Docs

FranchiseFile

Represents the file as a whole. Contains metadata, list of tables, and allows saving.

Fields

Functions

Events

FranchiseFileTable

Tables can hold zero or many records. Each table has a capacity defined in its header which denotes the maximum size it can be. In addition, a table may contain empty records.

Fields

Functions

Events

Empty Records (Advanced)

Empty records are null records that can appear scattered throughout a table. They are captured as FranchiseFileRecord objects and can be detected with the isEmpty attribute on the record object.

Think of empty records like a linked list. Each empty record points to the next empty record in the chain. Technically speaking, the first 4 bytes of a record contain the next empty record index while the rest of the record bytes are set to 00. Due to this, empty record string values may point to the first table2 field so it may initially seem like they are populated with duplicate data but they are not.

Each table's header keeps a reference of the nextRecordToUse, which either points to an empty record or equals the number of rows in the table. When a new record needs to be added, the nextRecordToUse should be the row that gets populated. Once populated, the header's nextRecordToUse will take on the value of the next empty record in the mapping.

The final empty record's reference will equal the number of rows in the table. This means it is the last empty row in the table and no other empty rows exist. The nextRecordToUse would then get updated to match the table length. If a new row is to be added and the table capacity is not yet filled, a new row may be inserted. If the table is already at capacity, a new row cannot be added.

Example

nextRecordToUse is set to row 2. Row 0 is not empty, Row 1 & 2 are empty. Row #2 points to Row #1. Row #1 points to Row #3, which is equal to the number of rows in the table. This means Row #1 is the last empty row that can be filled. Note that the actual length of Field_1 and Field_2 would be 32 bits, or 4 bytes.

When a new row gets populated, the game will place the data in row #2 because it is the nextRecordToUse. nextRecordToUse gets updated to row 1, because row #2 previously pointed to row #1.

If yet another row was added, it would be placed in Row #1. nextRecordToUse would get updated to 3 in this case, indicating there are no more empty records.

FranchiseFileRecord

A record represents a row in a table. It can have many columns, or fields. Technically speaking, this is a Proxy object that allows you to directly access field names as if they were attributes of the object itself and return their respective formatted values.

Ex: a record in the Player table. You can access/write a field by writing record.FirstName = 'Matt'.

Fields

Functions

FranchiseFileField

Fields contain a key and data. The offset table determines how each field should read its data from the buffer. Most field values are read as bits and converted to formatted values for easy use in JS.

Ex: a Player's Awareness rating shows as 64 but it is stored in binary as 7 bits with value 1000000.

• In this case, the formatted value is 64 and the unformatted value is a BitView instance representing the binary 1000000.

Note for string and blob field types, value will return the string/blob itself from the table2Field/table3Field, while unformattedValue will contain the BitView instance of the table2/table3 offset.

• Ex: Player First Name = "Matt". The table1 data will equal the offset of the string in the table2 data. The table2 data will contain the literal string "Matt".

Field values are not loaded by default. Every time their values are accessed/changed, the value is cached for quick future retrieval.

Fields

Functions

FranchiseFileTable2Field & FranchiseFileTable3Field

These objects represent the literal string/blob values for their respective fields. Their save behavior is slightly different between Franchise and FTC files:

• Franchise files: Strings always take up the full amount of length defined in the schema. Strings are padded with 00s.
• FTC files: Strings take up only as much room as they need and are not padded.

Fields