Sim Polis

Everything in the game from actions a character can complete to the conditions that define their behaviour and the grass between their toes and the day-night cycles above their heads is data-driven, meaning that they can be changed at runtime simply by modifying their data, or by encountering modifications created by other players. The purpose of Forms are to provide an interface in-game for modifying these structures and publishing them online.

Let’s take a look at a simple form to edit an Agent:

The Edit Agent form shown above is rendered in an “Edit Agent” window and is created with the following data:

{
    "urlid": "https://simpolis.gamescommons.com/assets/data/ui/forms/agent.json",
    "type": "form",
    "fields": [
        {
            "name": "name",
            "default": "Nameless",
            "type": "field",
            "fieldType": "simple",
            "cast": "string"
        },
        {
            "name": "description",
            "default": "",
            "type": "field",
            "fieldType": "simple",
            "cast": "string"
        },
        {
            "name": "capabilities",
            "default": [],
            "type": "field",
            "fieldType": "multi_select",
            "from": [
                {
                    "name": "Fire",
                    "urlid": "https://simpolis.gamescommons.com/assets/data/capabilities/fire.json"
                }
            ]
        }
    ]
}

This simple form can be passed into a game via the settings, but it can also be attached to an Agent specifically via the form attribute. This means that a character with important custom attributes, can use a customised Vampire Form. This is OK, but we are looking to improve how forms could be built more dynamically, e.g. incorporating elements due to being a Vampire while maintaining the fields important to a Knight of the Realm, for example, as well as looking for better ways for Form selection depending on context.

We are expanding on the principle of Commons UI and we’re planning on using structures like Forms for controlling aspects of the Heads-up Display (HUD). This is going to be a process of trial-and-error, so heads up that the structure of these forms might change with experience.

Form Field options

The type should always be field, while fieldType specifies the type of input which should be used (see options below). The name should always correspond to the value which is added to the parent object (in this example, an Agent). The name will be shown with an edit field as a label, unless the label key is present.

default defines a default value for the field if it is not present, and required indicates that the form should not be allowed to submit without it (an error message will be shown if the user tries). Including a default thus removes any meaning from required, since the user can just leave the input as the default. placeholder can be used to give a user extra instructions.

dependsOn can be used to disable a form element until another form element has been given a value. In the example above, adding "dependsOn": "name" to description, will prevent the user from adding a description until a name has been given.

Simple fields ("fieldType": "simple")

Simple fields are used to convert user input into a direct value, like a string, an integer or a boolean. The key cast instructs the field on which type to convert input to on submit.

Simple select ("fieldType": "select")

The select component is rendered as a list of options which the user can select from (the options are defined with the from key).

{
    "name": "input",
    "type": "field",
    "fieldType": "select",
    "required": true,
    "from": [
        {
            "name": "Edible",
            "urlid": "https://simpolis.gamescommons.com/assets/data/actions/inputs/edible.json"
        }
    ]
}

The name key on an option defines the label which will be rendered in the list. In the above example all options are objects (with urlid), but without a urlid they can define instead value:

{
    "name": "Edible",
    "value": "I can be whatever you want me to be!"
}

In future it will be possible to define search parameters for finding values for select fields from the Federation, i.e. online.

Multi-select ("fieldType": "multi_select")

The multi-select is a variation of the simple select field where the user can select zero or more items.

Cast ("fieldType": "cast")

This is a drop-down designed for the cast property: all valid values for query casts are included.

{
    "name": "cast",
    "type": "field",
    "fieldType": "cast"
}

JMES ("fieldType": "jmes")

JMESPath is used in queries in the Games Commons, and it’s essentially a light form of query language for JSON structures. This field is used to initialise a JMESPath query builder.

{
    "name": "path",
    "type": "field",
    "fieldType": "jmes"
}