Customizing the ChoiceScript Stats Screen

Most of our games have a “Show Stats” button (Choice of the Dragon has a “My Dragon” button) showing some of the stats applying to your character.

This document describes how to build a stat screen in games you’re writing in ChoiceScript.

Don’t Start Here!

Be sure to read our basic ChoiceScript Introduction page before reading this advanced documentation.

Create a Stat Chart

tl;dr: Try experimenting with the “choicescript_stats.txt” file.

The essence of the stat screen is the “stat chart,” which you can create using the *stat_chart command. The chart shows the value of any number of ChoiceScript variables; if the values are numbers between 1 and 100, you can display them as bars on the chart.

Let’s suppose you’ve got three variables:

the “name” variable, which contains the player’s name (e.g. “Dan”)
the “leadership” variable, which contains a Leadership score between 1-100
the “strength” variable, which contains a Strength score between 1-100

You could use the *stat_chart command like this:

*stat_chart
  text name
  percent leadership
  percent strength

That would display a stat chart like this:

Note that when we want to display the value of the variable as text, we write text before the variable; when we want to display the variable as a percentage bar, we write percent before the variable.

If you don’t like the percentage bars, you can use text for everything, in which case we’ll display the number as a numeral:

*stat_chart
  text name
  text leadership
  text strength

The “Show Stats” Button

You can use the *stat_chart in any ChoiceScript vignette; it’s just like any other command. For example, it’s nice to display a stat chart at the end of the game, to give players a sense of closure and accomplishment.

But the most interesting place to use *stat_chart is in a specially named file called choicescript_stats.txt.

choicescript_stats.txt is a ChoiceScript vignette file, just like startup.txt or any other file you create. When the player clicks the “Show Stats” button, we pause the current ChoiceScript scene and display the choicescript_stats.txt scene; when you finish that scene, we resume the scene previously in action.

Most of the time, the choicescript_stats.txt file contains almost nothing except the *stat_chart, but you may feel free to experiment with including other text in that file, especially if you want to include some information about the character that shouldn’t appear in a data chart.

Label the Stats Poetically

In the previous example, the chart displayed “name”, “leadership” and “strength” all in lower case; normally values like this should be in “Title Case” (like the headline of a newspaper article).

You can capitalize the names of your variables any way you like, for example:

*stat_chart
  text Name
  percent LEADERSHIP
  percent sTrEnGtH

That’s because, in ChoiceScript, variables are case-insensitive, so “strength” and “sTrEnGtH” mean the same thing.

But you can also give the variables different names. Perhaps you want to use more poetic labels, so instead of “Strength” you want to call it “Thews and Sinews”; instead of “Leadership” you want to call it “Serpent’s Tongue;” instead of “Name” you want to call it “Nom de Guerre.” You can write that like this:

*stat_chart
  text name Nom de Guerre
  percent leadership Serpent's Tongue
  percent strength Thews and Sinews

Display Opposed Pairs on the Chart

In some of our games, we say that two variables are “opposed;” e.g. Brutality is the opposite of Finesse, Cunning is the opposite of Honor, and Disdain is the opposite of Vigilance.

However, in our ChoiceScript code, we really only have three variables: “brutality,” “cunning,” and “disdain.” When we say “Honor increases” we simply decrease Cunning.

We can use these variables to display opposed pairs on the chart, like this:

*stat_chart
  opposed_pair Brutality
    Finesse
  opposed_pair Cunning
    Honor
  opposed_pair Disdain
    Vigilance

Again, note that “Finesse,” “Honor,” and “Vigilance” don’t really exist as variables in ChoiceScript, so we can write anything we like here. For example, we could have called Vigilance “Eye of the Dragon.”

However, if you need to use a poetic label for the LEFT side of the chart, you’ll need to write your chart a little differently:

*stat_chart
  opposed_pair strength
    Thews and Sinews
    Fragile Bones
  opposed_pair leadership
    Serpent's Tongue
    Minion's Obeisance

In this case, the first indented line is the left-side label, and the second indented line is the right-side label. If there’s only one indented line, then we assume it’s the right-side label.

It’s perfectly fine to have some variables that are opposed next to some other values that aren’t. For example, in Dragon, “Infamy” is not opposed by anything, so we can write our chart like this:

*stat_chart
  opposed_pair Brutality
    Finesse
  opposed_pair Cunning
    Honor
  opposed_pair Disdain
    Vigilance
  percent Infamy

NOTE: Some people have expressed confusion about how opposed variables are displayed. I think of them as bar charts; in the above example, the top bar is mostly red, because the dragon has 85% Brutality and 15% Finesse.

But some people look at the chart and see the opposite; they imagine that the chart is like a needle on a speedometer gauge; when the needle points all the way to “Finesse,” the dragon has lots of Finesse. Those people look at the chart and incorrectly think that the dragon has 85% Finesse! I think this is a bug in the way we display stats; I hope to fix it in a future version of ChoiceScript.

Use Temp Variables for Weird Values

In Choice of the Dragon, we keep track of wounds as a simple number 0-4, but display it as text, like this:

Wounds=0: Uninjured
Wounds=1: Battle-scarred
Wounds=2: Permanently wounded
Wounds=3: Permanently weakened
Wounds=4: At Death’s door

The way we do that is by creating a temporary variable to hold the text describing your wounds, like this:

*temp wound_text
*if wounds = 0
  *set wound_text "Uninjured"
  *goto chart
*elseif wounds = 1
  *set wound_text "Battle-scarred"
  *goto chart
*elseif wounds = 2
  *set wound_text "Permanently wounded"
  *goto chart
*elseif wounds = 3
  *set wound_text "Permanently weakened"
  *goto chart
*else
  *set wound_text "At Death's door"
*label chart

*stat_chart
  text wound_text Wounds

Adding Stat Definitions

WARNING: This feature is somewhat advanced, and may not have been a very good idea. If you feel a need to define your stats, it may be a sign that they aren’t named very well; maybe you’re being a bit too poetic.

Stat charts can include definitions for any line on the chart; just include a definition indented underneath the line in the *stat_chart command.

*stat_chart
  text name Nom de Guerre
    Your new name as a clan member
  percent leadership Serpent's Tongue
    Ability to convince others to follow you
  percent strength Thews and Sinews
    Endurance and strength of arms

That gets a bit more complicated when you want to define opposed pairs with definitions; you have to do it like this:

*stat_chart
  opposed_pair Brutality
    Brutality
      Strength and cruelty
    Finesse
      Precision and aerial maneuverability
  opposed_pair Cunning
    Cunning
      Intelligence and trickery
    Honor
      Honesty and trustworthiness
  opposed_pair Disdain
    Disdain
      Patience and scorn
    Vigilance
      Attention and impulsiveness