wish-engine.scripting-api — wish-engine 0.1.0-SNAPSHOT

Public scripting API

The public functions in this namespace (declared with defn-api) are provided at runtime to wish-engine Data Source scripts. Data Source scripts have two modes of operation: compile-time and runtime.

Compile-time, or "top-level," operation occurs when the Data Source is initially loaded, and is used to declare all the primary entities that might be used to build a character. As such, all compile-time functions are named with the declare- prefix, such as declare-class. Compile-time functions may only be used at compile-time.

Runtime operation occurs when a character sheet is in use, with the purpose of building upon a primary entity (such as a Class) based on user-selected options, in order to build up the "current" state of the entity. Runtime functions are invoked on an entity state map, and return the new state, allowing them to be used easily in pipelines to gradually add features, etc.

In general, any feature can have a runtime operation attached to it (also known as an on-provide function, using the :! key) which will be applied to an entity state when the feature is attached it. Such functions have a simple signature:

  (fn [state] state)

To simplify implementation, the on-state macro is provided, which automatically threads the given state through. It might be used like:

  (on-state
    (provide-feature :gunslinging)
    (provide-to-list :weapons :weapon/captains-pistol))

An extra value of having state provided at runtime to this function is that you can access things like :level in order to dynamically change the behavior of features, limited-uses, etc.---without requiring special support from the sheet! For example:

  (on-state
    (provide-limited-use
      {:id :gunslinging/precision-shot
       :uses (:level state)))

Note that the on-state macro provides the state with the implicit name state, as in the signature described above.

In general, when providing things to an entity, whether features to an entity, or items to a list, you can use:

1. A function of state that returns the value: This enables you to refer to values that may be declared in other Data Sources, or which are dynamically added by other features at runtime. Several helpers for creating these functions exist, such as [options-of] or [items-from-list].
2. A map: this represents an inline declaration of the feature at runtime, as you provide it. This is commonly used for class features that won't be referenced by other features.
3. A keyword: this is syntactic sugar for using the by-id function, enabling you to easily reference a feature declared elsewhere.

In addition, for any provide or declare function that allows you to pass multiple values, you can provide a mix of sequences and values, enabling you to use strutures like (map) or list comprehension with (for) to generate values.

add-limited-use clj/s

(add-limited-use state spec)

Legacy alias for provide-limited-use

add-to-list clj/s

(add-to-list state id-or-spec & entries)

Legacy alias of provide-to-list

by-id clj/s

(by-id id)

Given an ID, returns a function of state that will fetch the feature (or list item) with that ID

declare-class clj/s

(declare-class class-spec)

declare-effects clj/s

(declare-effects & effects)

declare-features clj/s

(declare-features & features)

declare-items clj/s

(declare-items base & items)

declare-list clj/s

(declare-list id-or-spec & entries)

declare-options clj/s

(declare-options feature-id & options)

declare-race clj/s

(declare-race race-spec)

declare-subrace clj/s

(declare-subrace parent-race-id race-spec)

has? clj/s

(has? vals-set coll)

Alias for (some) that can handle sets in production

items-from-list clj/s

(items-from-list list-id)

Given a list ID, returns a function of state that will fetch the items from that list

options-of clj/s

(options-of feature-id)

Given a feature ID, returns a function of state that fetches the selected options of that feature

ordinal clj/s

(ordinal n)

Given an integer, returns the English ordinal string, EG: 1 -> 1st, 2 -> 2nd, etc.

provide-attr clj/s

(provide-attr state attr-id-or-path value)

Provide an attribute to the entity, explictly. Attributes are used for sheet-specific data, and can store permanent or temporary state. The path can be a simple keyword or a sequence of keywords, and the value may be of any type.

A common pattern for providing multiple values for an attribute is to share a top-level key and store values in a sub-key based on the feature. For example, an item with ID :armor/browncoat that provides a +2 bonus to AC when equipped might look like:

  {:id :armor/browncoat
   :name "An old coat from another time"
   :! (on-state
        (provide-attr [:buffs :ac :armor/browncoat] 2))}

Then in order to compute the total AC bonuses at runtime, client code can do something like:

  (->> (get-in entity [:attrs :buffs :ac])
       vals
       (apply +))

This structure allows on-provide functions to provide attributes in an idempotent way.

The ID of the feature that provided this attribute (IE :armor/browncoat in the above example) will be stored at [:attrs/meta ...path].

provide-feature clj/s

(provide-feature state feature)

Provide a Feature to the entity. feature may be an ID keyword or a map, declaring the feature inline. See declare-features

provide-features clj/s

(provide-features state & features)

provide-limited-use clj/s

(provide-limited-use state spec)

Provide a limited-use item, stored at [:limited-uses id] in the entity. wish-engine does little with these directly, but as features that may only be used a limited number of times are core to most RPG systems, limited-use is a core function of wish.

Here's a real example from Wish:

  (on-state
    (provide-limited-use
      {:id :sorcerer/points#uses
       :name "Sorcery Points"
       :uses (fn [#{level}] level)
       :restore-trigger (if (< (:level state) 20)
                          :long-rest

                          ; NOTE: trigger on *both*; a long rest triggers
                          ; both, but if we don't declare both we will only
                          ; see :short-rest
                          #{:short-rest :long-rest})
       :restore-desc (when (= (:level state) 20)
                       "20 / Long Rest; 4 / Short Rest")
       :restore-amount
       (fn [#{trigger used level}]
         (if (= :short-rest trigger)
           (when (= 20 level) (min used 4))
           used))}))

Note the naming with the providing feature followed by the #uses suffix. This is not required, but is a common convention. The entity state will be passed to both the :uses and :restore-amount functions, enabling you to scale uses programmatically. They may both alternatively be declared statically. wish-engine will compile :restore-amount to a function, and even provide a default value that restores everything, if omitted.

Also note that, as elsewhere, the current state of the entity is available as state (from the on-state macro), so we can access things like :level in order to change the behavior at runtime.

provide-to-list clj/s

(provide-to-list state id-or-spec & entries)

Provide one or more entries to a list. The list may either be declared by id or with a list spec, which must be of the format:

  {:id :my-list
   :type :up-to-you}

If the :type is :feature, each map item of entries will be treated as provide-feature.