Skip to content

Commit 87be5c3

Browse files
dseguindseguin
committed
Expand widget clauses: Documentation
1 parent 1205b8f commit 87be5c3

File tree

1 file changed

+105
-33
lines changed

1 file changed

+105
-33
lines changed

‎doc/SIDEBAR_MOD.md‎

Lines changed: 105 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,10 @@
1313
- [height](#height)
1414
- [alignment](#text_align--label_align)
1515
- [colors](#colors)
16-
- [phrases](#phrases)
1716
- [flags](#flags)
17+
- [Phrases and conditions](#phrases-and-conditions)
18+
- [Conditions](#conditions)
19+
- [Default phrase](#default-phrase)
1820
- [Variable ranges](#variable-ranges)
1921
- [Variables](#variables)
2022
- [Numeric variables](#numeric-variables)
@@ -75,6 +77,8 @@ Each widget has a "style" field that may be:
7577
- `layout`: Layout container for arranging other widgets in rows or columns
7678
- `sidebar`: Special top-level widget for defining custom sidebars
7779

80+
"style" can also be `symbol` or `legend`, which are specific to [phrases](#phrases-and-conditions).
81+
7882
Let's start at the top, with the "sidebar" widget, composed of several "layout" widgets.
7983

8084

@@ -188,6 +192,14 @@ And a widget to show the HP of the right arm would define "var" and "bodypart" l
188192
}
189193
```
190194

195+
Some widgets can take advantage of multiple "bodyparts" like so:
196+
197+
```json
198+
{
199+
"bodyparts": [ "head", "torso", "arm_l", "arm_r" ]
200+
}
201+
```
202+
191203
See [Variables](#variables) for a list of available "var" values.
192204

193205

@@ -475,63 +487,123 @@ mapped as closely as possible to the spectrum of colors, with one exception - va
475487
"normal" value or range always use white (`c_white`) when the value is within normal.
476488

477489

478-
## `phrases`
490+
## `flags`
491+
492+
Widgets can use flags to specify special behaviors:
493+
494+
```json
495+
{
496+
"id": "my_widget",
497+
"type": "widget",
498+
"style": "text",
499+
"label": "My Widget",
500+
"var": "my_widget_var",
501+
"flags": [ "W_LABEL_NONE", "W_DISABLED" ]
502+
}
503+
```
504+
505+
Here are some flags that can be included:
479506

480-
Some widgets can take advantage of "phrases" - definitions for what text/values to display and
507+
| Flag id | Description
508+
|--- |---
509+
| `W_LABEL_NONE` | Prevents the widget's label from being displayed in the sidebar
510+
| `W_DISABLED` | Makes this widget disabled by default (only applies to top-level widgets/layouts)
511+
| `W_DYNAMIC_HEIGHT` | Allows certain multi-line widgets to dynamically adjust their height
512+
513+
514+
# Phrases and conditions
515+
516+
Widgets can take advantage of "phrases" - definitions for what text/values to display and
481517
how to display them. These take the form of a nested object containing several optional fields:
482518

483519
```json
484520
{
485521
"id": "bp_status_indicator_template",
486522
"type": "widget",
487-
"style": "phrase",
523+
"style": "text",
488524
"phrases": [
489-
{ "id": "bitten", "text": "bitten", "sym": "B", "color": "yellow" },
490-
{ "id": "infected", "text": "infected", "sym": "I", "color": "pink" },
491-
{ "id": "broken", "text": "broken", "sym": "%", "color": "magenta" },
492-
{ "id": "splinted", "text": "splinted", "sym": "=", "color": "light_gray" },
493-
{ "id": "bandaged", "text": "bandaged", "sym": "+", "color": "white" },
494-
{ "id": "disinfected", "text": "disinfected", "sym": "$", "color": "light_green" },
495-
{ "id": "bleeding", "text": "bleeding", "value": 0, "sym": "b", "color": "light_red" },
496-
{ "id": "bleeding", "text": "bleeding", "value": 11, "sym": "b", "color": "red" },
497-
{ "id": "bleeding", "text": "bleeding", "value": 21, "sym": "b", "color": "red_red" }
525+
{ "id": "bitten", "text": "bitten", "sym": "B", "color": "yellow", "condition": { ... } },
526+
{ "id": "infected", "text": "infected", "sym": "I", "color": "pink", "condition": { ... } },
527+
{ "id": "broken", "text": "broken", "sym": "%", "color": "magenta", "condition": { ... } },
528+
{ "id": "splinted", "text": "splinted", "sym": "=", "color": "light_gray", "condition": { ... } },
529+
{ "id": "bandaged", "text": "bandaged", "sym": "+", "color": "white", "condition": { ... } },
530+
{ "id": "disinfected", "text": "disinfected", "sym": "$", "color": "light_green", "condition": { ... } },
531+
{ "id": "bleeding", "text": "bleeding", "value": 0, "sym": "b", "color": "light_red", "condition": { ... } },
532+
{ "id": "bleeding", "text": "bleeding", "value": 11, "sym": "b", "color": "red", "condition": { ... } },
533+
{ "id": "bleeding", "text": "bleeding", "value": 21, "sym": "b", "color": "red_red", "condition": { ... } }
498534
]
499535
}
500536
```
501537

502-
| JSON Field | Description
503-
|--- |---
504-
| `id` | Which "phrase" this definition should apply to.
505-
| `text` | Translated text that may be interpreted and displayed in the widget.
506-
| `sym` | A shortened symbol representing the text.
507-
| `color` | Defines the color for the text derived from this "phrase".
508-
| `value` | A numeric value for this "phrase", which may be interpreted differently based on the context of the parent widget.
509-
510538
In the above example, the widget is simply used as a template for other widgets to `copy-from`,
511539
which provides text and color definitions for different bodypart status conditions.
512540

513-
## `flags`
541+
| JSON Field | Description
542+
|--- |---
543+
| `id` | An optional identifier for this phrase
544+
| `text` | Translated text that may be interpreted and displayed in the widget.
545+
| `sym` | A shortened symbol representing the text.
546+
| `color` | Defines the color for the text derived from this "phrase".
547+
| `value` | A numeric value for this "phrase", which may be interpreted differently based on the context of the parent widget.
548+
| `condition` | A dialogue condition (see [Dialogue conditions](NPCs.md#dialogue-conditions)) that dictates whether this phrase will be used or not. If the condition is true (or when no condition is defined), the phrase can be used to its text/symbol/color in the widget's value.
514549

515-
Widgets can use flags to specify special behaviors:
550+
551+
## Conditions
552+
553+
Widget phrases and conditions can be used to define new widgets completely from JSON, using
554+
[dialogue conditions](NPCs.md#dialogue-conditions). By omitting the widget's `var` field, the
555+
widget is interpreted as either a "text", "number", "symbol", or "legend" depending on the given
556+
`style`. The widget will evaluate each of its phrases to determine which ones to draw values from:
557+
558+
| Widget style | Phrase field used | Details | Example
559+
|--- |--- |--- |---
560+
| `"number"` | `"value"` | Lists values as comma-separated-values from all phrases that have true conditions. | `Next threshold: 30, 40, 55`
561+
| `"text"` | `"text"` | Lists text as comma-separated-values from all phrases that have true conditions. | `TORSO: bleeding, broken, infected`
562+
| `"symbol"` | `"sym"` | Lists syms sequentially from all phrases that have true conditions. | `TORSO: b%I`
563+
| `"legend"` | `"sym"` and `"text"` | Lists syms and text in a paragraph format, with spaces between pairs, from all phrases that have true conditions. | `b bleeding % broken I infected`
564+
565+
Widgets using the `legend` style can be multiple lines high using a `height` > 1 (and optionally, the `W_DYNAMIC_HEIGHT` flag), so that the generated list can span the given vertical space.
566+
567+
Some conditions can be specific to certain bodyparts. In order to simplify phrases, these conditions can pull from the parent widget's `bodypart` field (or `bodyparts` field if defining multiple). This allows the same phrases to be `copy-from`'d to multiple widgets, and each widget can display the phrases depending on whether its bodypart(s) passes the condition (assuming the condition relies on a bodypart).
568+
569+
570+
## Default phrase
571+
572+
Widgets can define a default phrase that will be used if none of the phrases in the `phrases`
573+
array pass their conditions:
516574

517575
```json
518576
{
519-
"id": "my_widget",
577+
"id": "observ_widget",
520578
"type": "widget",
521579
"style": "text",
522-
"label": "My Widget",
523-
"var": "my_widget_var",
524-
"flags": [ "W_LABEL_NONE", "W_DISABLED" ]
580+
"label": "Observation",
581+
"phrases": [
582+
{
583+
"text": "Good!",
584+
"color": "light_green",
585+
"condition": { "u_has_trait": "EAGLEEYED" }
586+
},
587+
{
588+
"text": "Bad!",
589+
"color": "light_red",
590+
"condition": { "u_has_trait": "UNOBSERVANT" }
591+
}
592+
],
593+
"default_phrase": {
594+
"text": "Neutral!",
595+
"color": "white"
596+
}
525597
}
526598
```
527599

528-
Here are some flags that can be included:
600+
In the example above, the widget would print out the following text:
529601

530-
| Flag id | Description
531-
|--- |---
532-
| `W_LABEL_NONE` | Prevents the widget's label from being displayed in the sidebar
533-
| `W_DISABLED` | Makes this widget disabled by default (only applies to top-level widgets/layouts)
534-
| `W_DYNAMIC_HEIGHT` | Allows certain multi-line widgets to dynamically adjust their height
602+
| Player has trait | Widget text
603+
|--- |---
604+
| Scout | `Observation: Good!`
605+
| Topographagnosia | `Observation: Bad!`
606+
| - | `Observation: Neutral!`
535607

536608

537609
# Variable ranges

0 commit comments

Comments
 (0)