# Advanced ChoiceScript

A guide to more advanced features in the ChoiceScript programming language. Please post on the ChoiceScript google group if you have questions about this document.

## Don't Start Here!

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

## More Commands

- `*comment`: This command does nothing; any text you put after `*comment` will be ignored. It's helpful to put remarks in the text that only the author should read. `

        *comment TODO We should make this scene more interesting!

  `
- `*page_break`: Put in a "Next" button with no radio buttons. The game will continue on the subsequent page. `

        You turn the corner slowly.  Blood rushes through your ears.  As you open the door...
        *page_break
        ... the masked murderer attacks!

  `
- `*line_break`: Put just one line break in your text, like a `<br>` in HTML. ChoiceScript automatically converts single line breaks to spaces, and double line breaks to paragraphs. `

        So
        this
        is
        all
        one
        line.

        But this is a new paragraph.

        And this
        *line_break
        is two lines.

  `

  That code would display like this:

  > So this is all one line

  > But this is a new paragraph.

  > And this
  > is two lines

- `*input_text`: Provides a text box for the user to specify the value of a variable, e.g. the user's name. `

        Please enter your name.
        *input_text name

        Your name is ${name}

  `
- `*fake_choice`: This convenience command behaves exactly like `*choice`, but no commands are allowed in the body of the choice; thus no `*goto`/`*finish` is required. `

        What color do you prefer?

        *fake_choice
          #Red
            Red is the color of roses.
          #Blue
            Blue is the color of the sea.
          #Green
            Green is the color of spring.

        What an excellent choice!  And what flavor of ice cream would you like?

        *fake_choice
          #Vanilla
          #Chocolate
          #Strawberry

        Mmm, delicious!
        *finish

  `
- `*rand`: Set a variable to a random number. You set the minimum and maximum, we do the rest. For example, this would set the variable `die_roll` to a value from 1 to 6 inclusive: `

        *rand die_roll 1 6

  `

  Beware! It can be very hard to adequately test scenes that use randomness.

## Advanced Techniques

- Labeled buttons: By default, `*finish` buttons say "Next Chapter" and `*page_break` buttons say "Next". You can make the button say something else, instead: `

        *page_break On with the show!
        *finish The show is over!

  `
- Conditional options: This advanced technique lets you show/hide some options based on the player's variables. `

        How will you handle this?
        *choice
          #Try to talk them out of it.
            They cannot be dissuaded.
            *finish
          #Force them to relent.
            They back down, for now.
            *finish
          *if president
            #Abuse my presidential powers to silence them
              This works; you will never hear from them again.
              *finish

  `

  In this case, players have the option to abuse their presidential power only if they are president; if they are not president, then the option is completely hidden.

- Fairmath: ChoiceScript includes two rather strange operators specifically for use on variables that are percentages, called "%+" and "%-". You use them like this: `

        *set leadership 50
        *set leadership %+ 20
        *set leadership %- 40

  `

  The "%+" and "%-" operators are called the "fairmath" operators. The idea is that as your leadership score gets higher, it becomes harder to increase, and easier to decrease. According to fairmath:

  - Fair Addition: `(x %+ y) = (x + (100-x)*(y/100))`
  - Large scores are hard to increase: `(90 %+ 20) = (90 + 2) = 92`
  - Small scores are easy to increase: `(10 %+ 20) = (10 + 18) = 28`
  - Fair Subtraction: `(x %- y) = (x - x*(y/100))`
    - Large scores are easy to decrease: `(90 %- 20) = (90 - 18) = 72`
    - Small scores are hard to decrease: `(10 %- 20) = (10 - 2) = 8`
  - 50 is equally easy to increase or decrease.
    - `(50 %+ 20) = (50 + 10) = 60`
    - `(50 %- 20) = (50 - 10) = 40`

  Fairmath is great in expressions like: `*set leadership %+ 20`. The player will get anywhere from 0 to 20 more points of leadership, depending on how high leadership is currently.

- Advanced `*if` statements: You can do a lot more with `*if` statements than `leadership > 15`. Here's a few tricks:
  - Equality and Inequality
    - Equal to: `leadership = 40` (Is leadership equal to forty?)
    - Not equal to: `leadership != 40` (Is leadership different from forty?)
    - Greater than: `leadership >40` (Is leadership greater than forty?)
    - Less than: `leadership <40` (Is leadership less than forty?)
    - Greater than OR equal to: `leadership >=50` (Is leadership greater than or equal to fifty?)
    - Less than OR equal to: `leadership <=40` (Is leadership less than or equal to forty?)
  - And/or (with mandatory parentheses)
    - And: `(leadership > 30) and (strength > 40)`
    - Or: `(leadership > 60) or (strength > 70)`
    - Complex parentheses: `((leadership > 60) and (agility > 20)) or (strength > 80)`
  - Comparing text:
    - `lover_name = "Jamie"`
    - `"2" = 2` (this is true!)
  - Setting variables to `true` or `false`:
    - `*set finished false`
    - `*set correct guess = "blue"`
- Text tricks:
  - Capitalize first letter: You can capitalize just the first letter of a variable like this: `Behold! $!{He} is capitalized.`
  - Concatenation: You can join text together like this: `*set murder "red"&"rum"`. You can use variables in the same way: `*set title "Dr. " & last_name`
  - Quotes: You can put quotes in your text by using backslashes, like this:

          *set joke "she said it was \"ironic\"!"

    If you write `${joke}`, you'll get:

    > she said it was "ironic"!

  - Backslashes: You can put backslashes in your text by using even more backslashes, like this:

          *set slashy "Here's one backslash: \\ and here's two backslashes: \\\\"

    If you write `${slashy}`, you'll get:

    > Here's one backslash: \ and here's two backslashes: \\

  - `*print`: This command is no longer necessary; it just prints the value of the variable you specify. Use `${}` variable substitution instead.
- Truly bizarre references: Probably only programmers will appreciate these. Beware! They add complexity without adding much value.
  - `*setref`: Set a variable by name, e.g. `*setref "leadership" 30` sets leadership to 30. Use it in crazy code like this: `

          *set virtue "courage"
          *setref virtue 30

    ` This code would set `courage` to 30. If this still doesn't seem useful, consider that `virtue` could have been determined by earlier choices, so it might have set `honesty` to 30 instead.

    Still not convinced? Don't worry about it; you'll probably never need it.

  - `*gotoref`: Goto a label by name, e.g. `*gotoref "claws"` TODO This doesn't work yet!
  - Curly parens: Put some text in curly braces and we'll turn it into the value of the named variable. `

          *set honesty 30
          *set virtue "honesty"
          *set score {virtue}
          Your ${virtue} score is ${score}

    ` This would print:

    > Your honesty score is 30

## Questions?

Please post on the ChoiceScript google group if you have questions about this document.