From 909a788505d395eb3f3aa9e9edd2f6052b26c355 Mon Sep 17 00:00:00 2001 From: Jon Ingold Date: Wed, 5 Jun 2019 13:01:30 +0100 Subject: [PATCH 1/2] Documented TURNS, RANDOM, SEED_RANDOM and LIST_RANDOM --- Documentation/WritingWithInk.md | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/Documentation/WritingWithInk.md b/Documentation/WritingWithInk.md index 165e7771..0eae164b 100644 --- a/Documentation/WritingWithInk.md +++ b/Documentation/WritingWithInk.md @@ -721,13 +721,13 @@ or: "I missed him. Was he particularly evil?" -## 7) Game Queries +## 7) Game Queries and Functions **ink** provides a few useful 'game level' queries about game state, for use in conditional logic. They're not quite parts of the language, but they're always available, and they can't be edited by the author. In a sense, they're the "standard library functions" of the language. The convention is to name these in capital letters. -### CHOICE_COUNT +### CHOICE_COUNT() `CHOICE_COUNT` returns the number of options created so far in the current chunk. So for instance. @@ -737,7 +737,11 @@ The convention is to name these in capital letters. produces two options, B and C. This can be useful for controlling how many options a player gets on a turn. -### TURNS_SINCE +### TURNS() + +This returns the number of game turns since the game began. + +### TURNS_SINCE(-> knot) `TURNS_SINCE` returns the number of moves (formally, player inputs) since a particular knot/stitch was last visited. @@ -750,6 +754,14 @@ Note that the parameter passed to `TURNS_SINCE` is a "divert target", not simply TODO: (requirement of passing `-c` to the compiler) +### SEED_RANDOM() + +For testing purposes, it's often useful to fix the random number generator so ink will produce the same outcomes every time you play. You can do this by "seeding" the random number system. + + ~ SEED_RANDOM(235) + +The number you pass to the seed function is arbitrary, but providing different seeds will result in different sequences of outcomes. + #### Advanced: more queries You can make your own external functions, though the syntax is a bit different: see the section on functions below. @@ -1263,6 +1275,18 @@ and the following will test conditions: If more complex operations are required, one can write functions (using recursion if necessary), or call out to external, game-code functions (for anything more advanced). +#### RANDOM(min, max) + +Ink can generate random integers if required using the RANDOM function. RANDOM is authored to be like a dice (yes, pendants, we said *a dice*), so the min and max values are both inclusive. + + ~ temp dice_roll = RANDOM(1, 6) + + ~ temp lazy_grading_for_test_paper = RANDOM(30, 75) + + ~ temp number_of_heads_the_serpent_has = RANDOM(3, 8) + +The random number generator can be seeded for testing purposes, see the section of Game Queries and Functions section above. + #### Advanced: numerical types are implicit Results of operations - in particular, for division - are typed based on the type of the input. So integer division returns integer, but floating point division returns floating point results. @@ -2339,6 +2363,7 @@ We have a few basic ways of getting information about what's in a list: {LIST_COUNT(DoctorsInSurgery)} // "2" {LIST_MIN(DoctorsInSurgery)} // "Adams" {LIST_MAX(DoctorsInSurgery)} // "Cartwright" + {LIST_RANDOM(DoctorsInSurgery)} // "Adams" or "Cartwright" #### Testing for emptiness From eb565f63cc2043ac0c39a78a091db65eca0837c0 Mon Sep 17 00:00:00 2001 From: Jon Ingold Date: Wed, 5 Jun 2019 13:10:30 +0100 Subject: [PATCH 2/2] Added "and" and "or" to the early part of the ink doc --- Documentation/WritingWithInk.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Documentation/WritingWithInk.md b/Documentation/WritingWithInk.md index 0eae164b..3acd6c34 100644 --- a/Documentation/WritingWithInk.md +++ b/Documentation/WritingWithInk.md @@ -541,7 +541,15 @@ You can use several logical tests on an option; if you do, *all* the tests must + { visit_paris } { not bored_of_paris } [Return to Paris] -> visit_paris +#### Logical operators: AND and OR +The above "multiple conditions" are really just conditions with an the usual programming AND operator. Ink supports `and` (also written as `&&`) and `or` (also written as `||`) in the usual way, as well as brackets. + + * { not (visit_paris or visit_rome) && (visit_london || visit_new_york) } [ Wait. Go where? I'm confused. ] -> visit_someplace + +For non-programmers `X and Y` means both X and Y must be true. `X or Y` means either or both. We don't have a `xor`. + +You can also use the standard `!` for `not`, though it'll sometimes confuse the compiler which thinks `{!text}` is a once-only list. We recommend using `not` because negated boolean tests are never that exciting. #### Advanced: knot/stitch labels are actually read counts @@ -555,6 +563,7 @@ If it's non-zero, it'll return true in a test like the one above, but you can al * {seen_clue > 3} [Flat-out arrest Mr Jefferson] + #### Advanced: more logic **ink** supports a lot more logic and conditionality than covered here - see the section on 'variables and logic'.