Resource

Resources are one of the main constructs in your system. A resource represents a "component" of your TTRPG system. For example, a spell would be a resource. A class, weapon, armor, item, species, etc., would all be resources. It is, essentially, a model that holds data, with a defined schema.

Resources are very special and powerful. Each of them can interact with other resources, and support bringing mechanics that are associated to them to the table (pun-intended!). Going back to the spell example from earlier, a spell might have a mechanic to roll for damage and trigger the spells effects, for instance.

Resources don't need to be concrete—they can represent abstract concepts, in fact. A magical effect (if you want to allow players to be able to customize them) might be a resource. A levelled_feature (ie: a feature that has a level associated with it) could also be a resource (you might want to use it to be able to specify features that are unlocked at a specific level, for example).

You will have a lot (A LOT) of resources in your system. Some of them will be special, however, as they will be "core" resources. These resources are going to be displayed in the resource section of the app (the orange one), and will allow the player to edit and create them, search them (as a compendium) and share them.

Finally, resources can have views attached to them. Not all of them will, but resource views are very helpful when developing your system. These will tell the RPG Companion App how to display a resource visually for the player to interact with. Views are mandatory, however, for core resources. These must have all 4 views (display, edit, list and search) implemented. search, in fact, is only useful if the resource is a core resource.

JSON Format

{
  "type": "Resource",
  "id": ...,
  "name": ...,
  "plural": ...,
  "abbreviation": ...,
  "core": ...,
  "color": ...,
  "stats": ...,
  "indexed_stats": ...,
  "display_name": ...,
  "display_view": ...,
  "edit_view": ...,
  "list_view": ...,
  "search_item_view": ...,
  "mechanics": ...,
  "search_filters": ...,
  "sort_options": ...
}

Fields

Field	Type	Required	Description
id	String	✓	The id for this type instance. This should be unique.
name	String	✓	The name for this type instance.
plural	String		Optional. The plural form of the name for this type instance (e.g: "Items" if the name is "Item").
abbreviation	String		Optional. Abbreviation of the name for this type instance (e.g: "STR" for Strength).
core	bool		Optional. Defaults to false. Signals if this resource is a "core" resource or not. Please read the explanation above on what core resources are.
color	Color		Only required (and useful) for core resources. This is going to be the color associated with this resource (in a hex string format, e.g: "#1d2fb5"). Try to make all your core resources have different colors to make the experience the best possible.
stats	Map<String, Stat>	✓	NOTE: Even though this type shows in this documentation as Map<String, Stat>, it should be treated as List<Stat> instead. This is the list of stats that your resource is composed of.
indexed_stats	List<String>		Optional. Defaults to an empty index. Characters and resources have indexes. These allow the app to quickly retrieve data from the database to provide a good user experience. For search item views (see search_view), any stat that is directly used in the search item view needs to be added to this index (by id). Note the 'directly' in the last sentence. This means that, if you're using a stat in your search item view which depends on another stat, you do not need to add that second stat to the index (unless, of course, it is directly referenced by the search item view). If you define a search filter or sort option for a stat, it should also be added to the list of indexed stats.
display_name	String		Optional. The id of the stat in this resource that represents its name. Defaults to name.
display_view	RPGView		This view will be used whenever a resource's detail is being shown to the player. This is the view that pops up in a bottom sheet whenever a resource is tapped on by the player. Players will usually go through this view before being able to edit it.
edit_view	RPGView		This view will be shown to the player when they are trying to edit or create a resource. Using a ViewPager view is recommended for very big and complex edit views, as that can make the experience better for players.
list_view	RPGView		This view will be used to display a resource as part of a list in the character sheet (ie: list of items, etc). It is very similar to the search item view (in fact, chances are they will be almost identical), but you do not need to add a stat to the indexed_stats to use it in this view. This lets you show even more data to the player without any performance implications, if you wanted to do that. It is recommended to use the ListItem view type for this, as it will make your life easier.
search_item_view	RPGView		The search_item_view is the view that will be displayed in the resources screen, when the player searches for resources. This view has access to the stats of the resource, but only the ones that you have defined in the indexed_stats property. Please see that property for additional details. It is recommended to use the ListItem view type for this, as it will make your life easier.
mechanics	List<Mechanic>		Optional. Defaults to an empty list. This list should contain all the mechanics that you want to run in your character sheet whenever an instance of this resource is attached to the character. This mechanic will automatically activate when that happens (only in the character sheet).
search_filters	List<SearchFilter>		Optional. Defaults to an empty list. A list of search filters which will be available for users when searching this resource type. Just think about how you would want to be able to filter your resource to search for instances effectively (e.g: you might want to filter by "level" for a spell, or by "type" for a weapon). Any stat that's included here needs to be included in the indexed_stats list. Otherwise it will not work.
sort_options	List<SortOption>		Optional. Defaults to an empty list. A list of sort options which will be available for users when searching this resource type. Just think about how you would want to be able to sort your resource to make searching easier (e.g: you might want to sort by "level" for spells, or by "type" for weapons). By default the app will always include an "alphabetic" sort option on the display_name stat.