-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Minor improvements to campaign editor * Update docs for playsets
- Loading branch information
Showing
20 changed files
with
221 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
You can kick off the [[Campaigns/index|campaign]] creation process using the [[Create a new campaign]] command. | ||
|
||
The command will create a folder and a file representing your campaign. You can use the campaign file as a home page for your campaign-- the important data for Iron Vault is stored in the frontmatter `ironvault` property. Use caution when editing the frontmatter and especially that property. | ||
|
||
![[Create a new campaign modal.png|300]] | ||
|
||
First, choose the options you'd like for your new campaign: | ||
|
||
* **Campaign name**: the name of your campaign. This sets the file name of the campaign file (for easy linking) as well as the display name used by Iron Vault when referring to your campaign. | ||
* **Folder**: the folder that will house your campaign. By default, this will match the **Campaign name** but you may choose a different path if you wish. | ||
* As noted in [[Campaigns/index|Campaigns]], you may not nest campaigns. | ||
* **Playset**: the [[Campaigns/Playsets/index|Playset]] determines which rules are active and which content is available in your campaign. You may select a built-in playset for official content using the toggles displayed, or you may configure a [[Custom playsets|custom playset]]. | ||
* **Scaffold campaign**: when this option is enabled (recommended), the following files and folders will be created in addition to the campaign root and campaign index: | ||
* *Default entity folders*: folders will be created for [[Entities/index|Tracked Entities]] based on the defaults you chose in [[Settings#New game object defaults|the "New game object defaults" settings]]. | ||
* *Truths*: a [[Truths]] file ready for you to select game truths | ||
* *Initial character*: finally, the [[Create new character]] modal will be shown, allowing you to create an initial character for your campaign. | ||
|
||
Once you're ready, click **Create** to create your campaign and optionally the scaffold. The campaign index file will be opened, which makes your new campaign as the [[Campaigns/index|active campaign]], allowing you to immediately use any [[Commands/index|commands]] that require an active campaign. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
[[Campaigns/index|Campaign]] properties can be edited by right-clicking the campaign file in the file explorer and choosing "Edit campaign" from the context menu. You can also access "Edit campaign" from the "..." button in the top-right corner when you have the campaign file open in the normal editor. | ||
|
||
![[Edit a campaign.png]] | ||
For details about these settings, see [[Creating a campaign]]. | ||
|
||
Note that changing the **Display name** does *not* rename the campaign root folder or index file; it only changes the name that Iron Vault uses when displaying the campaign. |
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,120 @@ | ||
You can create a custom playset using a relatively simple syntax that will be familiar to anyone who has worked with `.gitignore` files before. | ||
|
||
To get started, while you are [[Creating a campaign|creating]] or [[Editing a campaign|editing]] a campaign, click the **Configure** button next to the **Custom** playset option. This will launch the **Playset editor** modal: | ||
|
||
![[Playset editor.png|400]] | ||
|
||
From here, you can browse the built-in playsets for inspiration and then when you are ready choose "Custom playset" from the "Playset" dropdown. | ||
|
||
As you type, validation messages will display below the edit box so you know if you have any syntax issues. The search list at the bottom will also update to show you which content would be included and which excluded by your configuration. | ||
|
||
## Playset configuration | ||
|
||
A playset is a set of lines that tell Iron Vault which content it should include or exclude. | ||
|
||
Here's an example config that you might use if you were running a hard sci-fi Starforged game: | ||
|
||
``` | ||
@include(starforged) | ||
asset:sundered_isles/** [starforged.recommended=true] | ||
!asset:** [core.supernatural=true] | ||
``` | ||
|
||
This does three things: | ||
|
||
- Includes the built-in "starforged" playset | ||
- Adds to it all assets from Sundered Isles that are *tagged* as "recommended" for Starforged | ||
- Filters out any of the Starforged or Sundered Isles assets that are tagged as "supernatural" | ||
|
||
Before we can describe the playset syntax in detail, we need to cover a few prerequisites first. | ||
|
||
### Datasworn | ||
|
||
#### Datasworn IDs | ||
|
||
As discussed in [[Rulesets and Homebrew]], Iron Vault is built on top of the [[Datasworn]] library. You can think of a Datasworn rules package as a tree-structured representation of all of the content in Ironsworn/Starforged/etc. Each piece of independent content (e.g., a move, an asset, an oracle) has an ID of the form: | ||
|
||
`<type>:<package id>/<path>` | ||
|
||
The Datasworn types currently supported by Iron Vault playsets are: | ||
|
||
* `oracle_rollable` | ||
* `move` | ||
* `asset` | ||
* `truth` | ||
|
||
Iron Vault playsets can also filter on an additional "virtual type": | ||
|
||
* `rules_package` | ||
* This virtual type corresponds to the base of a Datasworn ruleset or expansion file. In particular, you must include this to get Datasworn `rules` elements, such as stats, condition meters, and impacts. | ||
* We also use the rules_package IDs to activate special handling specific to different base rulesets but not represented in Datasworn currently, such as the terminology for combat initiative/position. | ||
* IDs of this type include only the package ID and no path, e.g., `rules_package:starforged` matches the `starforged` rules package | ||
|
||
#### Embedded content | ||
|
||
The main Datasworn types listed above are used to describe roughly standalone content, such as a core game move or a complete asset. In addition, sometimes content is intended for use only in the context of another piece of content. For example, some assets (for example, Starforged's Empath asset) grant you additional moves (e.g., Empath's "Read heart" move); in the Empath example, we say the "Read Heart" move is embedded in the "Empath" asset. | ||
|
||
IDs for embedded content combine multiple corresponding segments of types and paths. Continuing with the example above, "Read Heart" has ID `asset.ability.move:starforged/path/empath.0.read_heart`. Reading this from right to left, this tells us we are looking for a move called "read_heart" that is in ability "0" (the first ability) of the asset at `starforged/path/empath`. | ||
#### Tags | ||
|
||
In addition to IDs, some Datasworn content is marked with tags of the form `<package id>.<tag id>`. This is currently used to mark Starforged assets recommended for Sundered Isles (and vice versa) as well as the Sundered Isles "technological" and "supernatural" designations. | ||
### Datasworn ID globs | ||
|
||
Iron Vault introduces a way to match patterns on Datasworn IDs using wildcard expressions (similar to [shell path globs](https://en.wikipedia.org/wiki/Glob_(programming))). | ||
|
||
Like a Datasworn ID, each pattern must have the form: | ||
|
||
`<type pattern>:<path pattern>` | ||
|
||
Type pattern can be either `*` or any of the [[#Datasworn IDs|Datasworn types described above]]. A `*` matches any Datasworn type whatsoever. | ||
|
||
A path pattern is made up of one or more path segments separated by a `/` character. A path segment can be a mix of legal literal characters (`a-z`, `0-9`, `_`, and `-`) and wildcards (`*`), which match zero or more legal characters. For example, `e*e*` would match `empowered` and `explorer` but not `empath`. A wildcard in a path segment never matches a `/`. | ||
|
||
A path segment can also be a `**`, which functions like `*` but matches 0 or more complete path segments. For example `asset:starforged/**` matches `asset:starforged`, `asset:starforged/path`, and `asset:starforged/path/empath`. | ||
|
||
A datasworn ID glob ALWAYS matches all [[#Embedded content]] under a matching pattern. Thus, the pattern `asset:starforged/path/empath` also matches `asset.ability.move:starforged/path/empath.0.read_heart`. | ||
### Playset syntax | ||
|
||
With those fundamentals, we can now describe the syntax of the playset configuration. | ||
|
||
Each line of a playset configuration must be one of the following: | ||
|
||
* A [[#Glob statement]] | ||
* An [[#@include statement]] | ||
|
||
You may also include blank lines or comment lines starting with `#`; these will be ignored. | ||
|
||
When determining whether a playset includes a particular piece of content, Iron Vault goes through each of the lines from last to first, until it finds a line that matches the content and issues a *determination* (either an explicit *include* or *exclude*). If no line generates a *determination*, the playset will exclude the content implicitly. | ||
#### Glob statement | ||
|
||
A glob statement is a [[#Datasworn ID globs]] as described above. If the glob matches the current content, then an *explicit include determination* will be made. | ||
|
||
If the line is prefixed with a `!`, an *explicit exclude determination* will be made instead. | ||
|
||
A glob statement can also be refined by tags. These tags must match, in addition to the ID glob matching, in order for this line to match and generate a determination. To match a single tag, add `[packageId.tagId=value]` after the glob. Multiple tags can be matched by separating them with an ampersand, e.g., `[pkg1.tag1=value&pkg1.tag2=value&pkg2.tag3=value]`. | ||
|
||
Tag values can either be: | ||
|
||
* A boolean value `true` or `false` | ||
* A number, e.g., `1` | ||
* A string enclosed in double quotes, e.g., `"this string"` | ||
|
||
Examples: | ||
|
||
``` | ||
# Include everything in the starforged rules package | ||
*:starforged/** | ||
# Include all Sundered Isles assets (and their embedded content) | ||
# as long as they have the starforged.recommended=true tag | ||
asset:sundered_isles/** [starforged.recommended=true] | ||
# Exclude all assets that are tagged as technological | ||
!asset:** [core.technological=true] | ||
``` | ||
|
||
Because the last pattern wins, this playset config would include everything in starforged and all Sundered Isles assets that are tagged as recommended *EXCEPT* that it would exclude *ANY* asset that is tagged as technological (in both Starforged and Sundered Isles) | ||
|
||
#### @include statement | ||
|
||
A line of the form `@include(playsetid)` incorporates all of the lines of the built-in Playset with id `playsetid` in place of the `@include` line. You can use the Playset dropdown in the Playset editor described above to find ids of existing playsets. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
--- | ||
aliases: | ||
- Playset | ||
- playset | ||
--- | ||
A playset is a defined subset of all of the [[Rulesets and Homebrew|available content from official sources and homebrew]]. Each [[Campaigns/index|campaign]] is configured to use a specific playset, and this controls what moves, assets, oracles, etc are available when that campaign is [[Campaigns/index|active]]. | ||
|
||
When [[Creating a campaign|creating]] or [[Editing a campaign|editing]] a campaign, you can choose one of the [[Built-in playsets]] or you may configure a [[Custom playsets|custom playset]]. | ||
|
||
> [!todo] Homebrew | ||
> Currently, if you wish to enable [[Rulesets and Homebrew|homebrew]] in a campaign, you must use a custom playset. In the future, we may make it easier to include certain kinds of homebrew content in your campaign. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1 @@ | ||
Use this command to create a new [[Campaigns|campaign]] in your vault. | ||
|
||
![[Create a new campaign.png|500]] | ||
|
||
The command will create a folder and a file representing your campaign. You can use the campaign file as a home page for your campaign-- the important data for Iron Vault is stored in the frontmatter. Use caution when editing the frontmatter. | ||
The "Create a new campaign" command opens the "Create a campaign" modal which you can use to create a new campaign. See [[Creating a campaign]] for details of the campaign creation process. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1 @@ | ||
This command will open up a menu that will allow you to change the current active [[Characters|Character]] when multiple characters are present in the [[Campaigns|active campaign]]. | ||
This command will open up a menu that will allow you to change the current active [[Characters|Character]] when multiple characters are present in the [[Campaigns/index|active campaign]]. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.