Ship fight profiles

Ship fight profiles in a package as JSON files in its fightprofiles folder, so everyone who installs it can play them, with naming, versions, extends, how Asterobot reads them, testing and every error.

A fight profile tells Asterobot's fight module how a bot plays its fights. Players make their own on the Fight Profiles page (Fight profiles), and a package can ship some too: a farming package can come with the profiles its fights are tuned for, and a package can exist only to share profiles. Once the package is installed, its profiles show on the Fight Profiles page, and any bot can play them.

@asterobot:base ships 24 profiles this way, one for each common way of fighting, none naming a spell: its fightprofiles folder is a good place to see complete profiles, and a profile of yours can extend one of them.

Where the files go

A package ships each profile as one JSON file in a fightprofiles folder at its root, next to index.js. A file holds one profile in the fight profile format, exactly as the Fight Profiles page's Export downloads it, and its name, without .json, is the profile's name within the package:

my-package/
├── index.js
├── asterobot.json
└── fightprofiles/
    ├── air-cra.json
    └── air-cra-careful.json

fightprofiles/air-cra.json:

{
  "version": 1,
  "name": "Air Cra",
  "description": "Hits from afar and steps back after casting.",
  "role": "damage",
  "range": "ranged",
  "elements": ["air"],
  "positioning": "kite"
}

fightprofiles/air-cra-careful.json:

{
  "version": 1,
  "name": "Air Cra, careful",
  "extends": "@some-author:fighters/air-cra",
  "risk": 20
}

For a package named @some-author:fighters, these are @some-author:fighters/air-cra and @some-author:fighters/air-cra-careful: the package's name, a /, then the file's name. That full name is the one a bot's Profile list shows, the one extends names, and the one players see on the Fight Profiles page with the Package source.

• Only .json files directly in fightprofiles/ are profiles. A subfolder of it, or a file with another extension, is left out, as any other file of the package is (Package layout).
• Name files like keys: lower case and dashes, such as air-cra-careful.json. The name can't hold a /.
• Give each profile a name: the format requires one. The page and the bots go by the full name made from the file's name, whatever name says.
• Profiles are data, never run. A script can't import one: Asterobot refuses it as not a module.

The easiest way to write one is to build it on the Fight Profiles page, where the editor checks every value as you go, then Export it and put the downloaded file in your package's fightprofiles folder. In the package editor, Add a file takes a path such as fightprofiles/air-cra.json, and opens it as JSON.

Which version plays

A bot can play a package's profile whether or not it plays the package itself, and every bot plays it from the newest version of the package installed. The page lists each profile from that version too. So when you publish an update, its profiles replace the old ones for everyone who updates, at their next fight, and the profiles that extend them, yours or the players', follow.

A player who wants to keep a profile as it is, whatever your updates do, copies it into their own profiles with Copy. When a player removes your package, the bots set to one of its profiles play the default profile, and their console says so.

So treat a profile's key like a public name: renaming one in an update leaves the bots set to the old name on the default profile.

Extending

A package's profile can extend another profile, with the same rules as the players' own (Extend another profile): one of the same package by its full name, another package's, or Idle. Only one level: a profile can't extend a profile that extends another. Players can extend yours too, and keep their changes on top of your updates.

A profile can't extend one of the player's own profiles in a reliable way, since you don't know their names.

How Asterobot reads them

Asterobot reads the files themselves, without running the package's script. So a package whose script has an error still lists its profiles, and the Fight Profiles page lists the profiles of every installed package, whether a bot plays it or not. Each file is read again when the page lists the profiles and when a fight starts, so a package updated in the meantime plays from the next fight.

The files travel with the package's modules: installing from a folder or a .zip, exporting, publishing on asterobot.net and copying a package all carry them, and the package's integrity checksum covers them (The manifest).

Errors

A profile never stops anything else: not the package's script, nor its other profiles. A file that isn't valid JSON, or holds a value Asterobot can't use, is marked Can't be played on the Fight Profiles page, with the reason, and a bot set to it plays the default profile. Warnings, such as an id the game data doesn't have, show the same way. The fight profile format lists every error and warning.

Test your profiles

1. Install your package in your library, from its folder or a .zip (The editor, Zip and command line).
2. Open Fight Profiles. Your profiles are listed with the Package source: check that each one is Ready, and read its warnings.
3. Open one with View to see every setting as the editor reads it.
4. Set a bot's Profile to it, switch on Play this bot's fights, and read the Turn log after a fight.

To try a change, Copy the profile, edit the copy, then Export it back into your package's fightprofiles folder.

Next, the Packages chapter describes the manifest, starting with every field of asterobot.json.