-
Notifications
You must be signed in to change notification settings - Fork 32
Home
JSON data spec for COMP/CON v3 and later
The lancer-data npm package is available at @massif/lancer-data
C/C v3 is backwards compatible with v2 data, however v3 expands several item types. The following additions have been made:
- License Collection format
deprecatedflag- inline SVGs for Manufacturer icons, Talent icons, and Status icons,
- Effect objects
- Bonus Damage data
- Resistances
- Saving Throw data
- Additional Bonuses
- NPC spec
- Eidolons
This wiki serves as documentation for authors of custom Lancer Content Packages (LCPs) for use with COMP/CON.
If you are interested in submitting your content package to be included in the community content directory in COMP/CON, please check the LANCER Community Content Packs section
A working example of custom data can be found in the Long Rim player data repository. Additionally, all item data for the Core book can be found within this repository.
If you have any additional questions after reading this document, please contact me at @Beeftime#0558 in the #comp-con-homebrew channel on the official LANCER Discord
COMP/CON comes with the Core Book data already loaded, but other data (official and otherwise) must be loaded via a Lancer Content Package (.lcp) file, a renamed .zip archive.
An LCP must be a single-level archive. All subdirectories will be ignored. It must contain, at a minimum, a valid lcp.manifest.json file.
A working, but content-less, LCP structure would look like this:
my homebrew folder
│ lcp_manifest.json
additional data must be included in the archive at the same level as the info.json file. Content folders should not have any depth.
COMP/CON's LANCER data is stored as JSON data that is then parsed on app load to hydrate an item database. Lancer Content Packs (LCPs) with additional content can be parsed by C/C provided they follow the schema detailed below. These content packs will be appended to the core content in this repo (meaning it is impossible to overwrite a piece of core equipment, even if they share an ID).
Content packs must follow the same folder and naming conventions as the lib folder in this repo: for example, to add a custom background in my LCP, I must include a backgrounds.json that contains a single array with objects containing id, name, and description fields, as described here. LCPs are .zip files with a renamed extension (though C/C will be able to parse .zips), and an update to the LCP authoring tools is underway. LCPs must contain, at minimum, a lcp_manifest.json with the fields described below.
If this document is insufficient, please use the core data files in the lib folder as reference. If you have a further question or suggestion, please contact me in #comp-con or #comp-con-homebrew in the LANCER Discord.
Editing or creating COMP/CON homebrew requires a working knowledge of JavaScript Object Notation, or JSON. Information about JSON structure and writing JSON is outside the scope of this document, but the Mozilla MDN web docs contain excellent resources on the subject: https://www.json.org/json-en.html
In this document, data object properties are notated with name and type. Many COMP/CON data objects allow, but do not require, certain properties, and may be safely omitted. These are marked below with a ?
Example notation:
{
"required_property": string,
"required_sub_object": IObject,
"optional_enum"?: EnumeratedType
"optional_property"?: number
}Omitting one or both of the optional properties would allow C/C to correctly parse this object. Omitting any of the required properties would cause C/C to fail to load the LCP correctly.
COMP/CON, whenever it can, references item data by ID. This means two very important things:
-
IDs must be unique for data to be referenced correctly. If there are two items with the same ID there's no guarantee as to which one will be referenced, so it's in your best interests to have longer, specific IDs. Consider the following format:
my-lcp-prefix_data-type-prefix_my_item_name. Long IDs will not slow in-app item references. -
If you change and item ID, user data that references that item will break (in one form or another). To the extent possible, ensure that item IDs stay the same through future versions of your LCP
Occasionally the contents of an LCP may change such that an item needs to be removed from future LCP versions. However, removing its associated LCP data will break all user data that contains the removed item, and prevent non-instanced versions from being loaded in COMP/CON. For these cases, LCP authors should mark the removed item with the deprecated flag.
deprecated can be set on any LCP content item and will replace the in-app item UI with a notification that this item should be removed or replaced with a different item.
If you'd like to submit your content pack for inclusion within COMP/CON, there are a few requirements:
- Compatible with the new item regime, as described by this document.
- Downloadable through an itch.io page (free or paid)
- Nominated by the community as a good asset, even for people that aren't on the Discord or otherwise tied in to the greater Lancer community (ie: has been playtested, doesn't require other assets, only references already-published material, etc.)
- Does not contain any questionable or illegal content, nor any content not owned by the author.
- Passes a final content and code pass
If these standards are acceptable, please contact me at @Beeftime#0558 in the official LANCER Discord, ideally within the #comp-con-homebrew channel.
COMP/CON is an open-source project and may be forked freely. However, if you want to submit code for novel features to support your content packs (or otherwise), that's totally acceptable. Please notify me at @Beeftime#0558 in the official LANCER Discord, in the #comp-con channel and we can discuss the details.
Additionally, I am available for commissioned work to develop COMP/CON features at your direction (outside of currently-planned features, etc.). Please contact me on the Discord for rates, timeframe, and further information.
If an LCP does not load, first check that the .zip archive does not contain subfolders, as no content will be read beyond the archive root. This can occur when zipping a folder from most OS quick actions.
Beyond that, most of the time, issues related to LCPs come from malformed LCP data or missing IDs.
Many of these issue can be found and remedied by using the COMP/CON VSCode extension
Further questions can be answered in the #comp-con-homebrew channel in the LANCER Discord.