From b0180bba53cf9b6b4c63c2e6c81d63a9b5718a63 Mon Sep 17 00:00:00 2001 From: Karl Ostmo Date: Sat, 5 Aug 2023 15:29:54 -0700 Subject: [PATCH] add more markup to tutorial objectives prose --- data/scenarios/Tutorials/backstory.yaml | 2 +- data/scenarios/Tutorials/build.yaml | 4 ++-- data/scenarios/Tutorials/conditionals.yaml | 6 +++--- data/scenarios/Tutorials/craft.yaml | 6 +++--- data/scenarios/Tutorials/def.yaml | 8 ++++---- data/scenarios/Tutorials/equip.yaml | 6 +++--- data/scenarios/Tutorials/farming.yaml | 10 +++++----- data/scenarios/Tutorials/grab.yaml | 4 ++-- data/scenarios/Tutorials/lambda.yaml | 4 ++-- data/scenarios/Tutorials/move.yaml | 6 +++--- data/scenarios/Tutorials/place.yaml | 6 +++--- data/scenarios/Tutorials/require.yaml | 6 +++--- data/scenarios/Tutorials/requireinv.yaml | 4 ++-- data/scenarios/Tutorials/scan.yaml | 2 +- data/scenarios/Tutorials/type-errors.yaml | 2 +- data/scenarios/Tutorials/world101.yaml | 4 ++-- 16 files changed, 40 insertions(+), 40 deletions(-) diff --git a/data/scenarios/Tutorials/backstory.yaml b/data/scenarios/Tutorials/backstory.yaml index 8ec2847505..51b840067b 100644 --- a/data/scenarios/Tutorials/backstory.yaml +++ b/data/scenarios/Tutorials/backstory.yaml @@ -8,7 +8,7 @@ objectives: on an alien planet! It's not clear how you'll ever get home, but since you're here, you might as well explore a bit. Your sensors indicate that the atmosphere is highly toxic, so - you'll have to stay inside your robotic base, with its + you'll have to stay inside your robotic `base`, with its built-in life support system. However, you are stocked with all the materials you need to build robots to explore for you! diff --git a/data/scenarios/Tutorials/build.yaml b/data/scenarios/Tutorials/build.yaml index ca19efc46f..353823b82e 100644 --- a/data/scenarios/Tutorials/build.yaml +++ b/data/scenarios/Tutorials/build.yaml @@ -15,8 +15,8 @@ objectives: where in place of `COMMANDS`{=snippet} you write the sequence of commands for the robot to execute (separated by semicolons). - | - Build a robot to harvest the `"flower"` and place it next - to the water. + Build a robot to harvest the `flower`{=entity} and place it next + to the `water`{=entity}. - | TIP: Newly built robots start out facing the same direction as their parent, which in the tutorials will always be north. diff --git a/data/scenarios/Tutorials/conditionals.yaml b/data/scenarios/Tutorials/conditionals.yaml index 30b7697432..41c30fbd26 100644 --- a/data/scenarios/Tutorials/conditionals.yaml +++ b/data/scenarios/Tutorials/conditionals.yaml @@ -38,7 +38,7 @@ objectives: evaluated until needed. In this case, we want to make sure that only the correct branch is evaluated. To write a value of type, say, `{int}`{=type}, we just surround a value of type `int`{=type} - in curly braces, like `{3}`. This is why arguments to `build` + in curly braces, like `{3}`{=snippet}. This is why arguments to `build` must also be in curly braces: the type of `build` is `{cmd a} -> cmd robot`{=type}. - | @@ -50,8 +50,8 @@ objectives: - | TIP: the two branches of an `if` must have the same type. In particular, `if ... {grab} {}`{=snippet} is not - allowed, because `{grab}` has type `{cmd text}`{=type} whereas `{}` has type `{cmd unit}`{=type}. - In this case `{grab; return ()}` has the right type. + allowed, because `{grab}`{=snippet} has type `{cmd text}`{=type} whereas `{}` has type `{cmd unit}`{=type}. + In this case `{grab; return ()}`{=snippet} has the right type. condition: | try { n <- as base {count "very small rock"}; diff --git a/data/scenarios/Tutorials/craft.yaml b/data/scenarios/Tutorials/craft.yaml index 3189e5e69f..a172cb16dc 100644 --- a/data/scenarios/Tutorials/craft.yaml +++ b/data/scenarios/Tutorials/craft.yaml @@ -10,11 +10,11 @@ objectives: - goal: - Robots can use the `make` command to make things, as long as they have a `workbench`{=entity} and the proper ingredients. For - example, `make "circuit"` will make a circuit. - - Your base has a few trees in its inventory. Select them to see the + example, `make "circuit"` will make a `circuit`{=entity}. + - Your base has a few `tree`{=entity}s in its inventory. Select them to see the available recipes. - Your goal is to make a `branch predictor`{=entity}, so you will have to make - some `"branch"`es first. + some `branch`{=entity}es first. - | Note: when used after opening quotes in the REPL, the Tab key can cycle through possible completions of a name. E.g., type: diff --git a/data/scenarios/Tutorials/def.yaml b/data/scenarios/Tutorials/def.yaml index 75cef114db..c61de73268 100644 --- a/data/scenarios/Tutorials/def.yaml +++ b/data/scenarios/Tutorials/def.yaml @@ -4,9 +4,9 @@ description: | Learn how to define new commands. objectives: - goal: - - Your goal is to build a robot to fetch the flower growing in the + - Your goal is to build a robot to fetch the `flower`{=entity} growing in the upper right and bring it back to you; you win the challenge when the base - has a flower in its inventory. + has a `flower`{=entity} in its inventory. - | However, it would be extremely tedious to simply type out all the individual `move` and `turn` commands required. Your base has a `dictionary`{=entity} device @@ -20,12 +20,12 @@ objectives: use of new definitions, it should be possible to complete this challenge in just a few lines of code. - | - TIP: your base is at coordinates (0,0), and the flower is at (16,4), which + TIP: your base is at coordinates `(0,0)`, and the `flower`{=entity} is at `(16,4)`, which you can confirm by clicking in the world map panel. When you click on a cell, its contents and coordinates are shown in the lower left. - | TIP: the type annotation in a definition is optional. You could also write - `def m4 = move; move; move; move end`, and Swarm would infer + `def m4 = move; move; move; move end`{=snippet}, and Swarm would infer the type of `m4`{=snippet}. - | TIP: writing function definitions at the prompt is annoying. diff --git a/data/scenarios/Tutorials/equip.yaml b/data/scenarios/Tutorials/equip.yaml index a25996d17b..76de9cea6e 100644 --- a/data/scenarios/Tutorials/equip.yaml +++ b/data/scenarios/Tutorials/equip.yaml @@ -10,11 +10,11 @@ objectives: perform more complex commands. - Before you start building new robots in the later tutorials, you need to gain the `build` capability. - Try typing `build {}` - you should get an error telling you that you + Try typing `build {}`{=snippet} - you should get an error telling you that you need to equip a `3D printer`{=entity}. - | - Fortunately, there is a 3D printer lying nearby. Go `grab` it, then - `equip` it with `equip "3D printer"`. + Fortunately, there is a `3D printer`{=entity} lying nearby. Go `grab` it, then + `equip` it with `equip "3D printer"`{=snippet}. - | You win by building your first robot: - | diff --git a/data/scenarios/Tutorials/farming.yaml b/data/scenarios/Tutorials/farming.yaml index a05987d8c5..4e2206c607 100644 --- a/data/scenarios/Tutorials/farming.yaml +++ b/data/scenarios/Tutorials/farming.yaml @@ -6,7 +6,7 @@ objectives: - id: get_many_lambdas teaser: Get 256 lambdas goal: - - Lambdas are an essential item for building robots, but they + - `lambda`{=entity}s are an essential item for building robots, but they are somewhat rare in the wild. Therefore, it makes sense to farm them in order to create a reliable supply. - | @@ -20,13 +20,13 @@ objectives: ``` def forever = \c. c ; forever c end ``` - - Your goal is to acquire 256 lambdas. Of course, in order to + - Your goal is to acquire 256 `lambda`{=entity}s. Of course, in order to accomplish this in a reasonable amount of time, it makes sense to plant - a field of lambdas and then program one or more robots to + a field of `lambda`{=entity}s and then program one or more robots to harvest them in an automated way. - "TIP: the `ishere` command can be used to test for the presence of a - (fully-grown) lambda, and the `has` command can be used to test whether - a robot has a lambda in its inventory." + (fully-grown) `lambda`{=entity}, and the `has` command can be used to test whether + a robot has a `lambda`{=entity} in its inventory." condition: | try { as base { diff --git a/data/scenarios/Tutorials/grab.yaml b/data/scenarios/Tutorials/grab.yaml index 85d13edb07..55f691a99e 100644 --- a/data/scenarios/Tutorials/grab.yaml +++ b/data/scenarios/Tutorials/grab.yaml @@ -4,9 +4,9 @@ description: | Learn how to interact with the world by grabbing entities. objectives: - goal: - - Previously you learned how to make new things (like a branch predictor) from ingredients. + - Previously you learned how to make new things (like a `branch predictor`{=entity}) from ingredients. Now you will learn how to obtain the ingredients you need. - - There are some trees ahead of your robot; `move` to each one and `grab` it. + - There are some `tree`{=entity}s ahead of your robot; `move` to each one and `grab` it. - You can learn more by reading about the grabber device in your inventory. Remember, if the description does not fit in the lower left info box, you can either hit **Enter** to pop out the diff --git a/data/scenarios/Tutorials/lambda.yaml b/data/scenarios/Tutorials/lambda.yaml index a61501f152..60c47b1a58 100644 --- a/data/scenarios/Tutorials/lambda.yaml +++ b/data/scenarios/Tutorials/lambda.yaml @@ -5,14 +5,14 @@ description: | objectives: - goal: - Your goal in this challenge is to send a robot to grab the - flower in the lower right (you don't need to bring it back). + `flower`{=entity} in the lower right (you don't need to bring it back). - | The path looks complex, but if you study it, you will see that it has a lot of structure. In particular, there are many parts of the path that repeat four times; it seems like it could be really useful to have a function to repeat a command four times. - | - To write a function, you use lambda syntax. As a simple example, `\x. x + 1` is the + To write a function, you use lambda syntax. As a simple example, `\x. x + 1`{=snippet} is the function which takes an input (locally called `x`{=snippet}) and returns one more than `x`{=snippet}. As another example: - | diff --git a/data/scenarios/Tutorials/move.yaml b/data/scenarios/Tutorials/move.yaml index 41cc161c4d..23d975e4b3 100644 --- a/data/scenarios/Tutorials/move.yaml +++ b/data/scenarios/Tutorials/move.yaml @@ -9,7 +9,7 @@ objectives: - Robots can use the `move` command to move forward one unit in the direction they are currently facing. - To complete this challenge, move your robot two spaces to the right, - to the coordinates `(2,0)` marked with the purple flower. + to the coordinates `(2,0)` marked with the purple `flower`{=entity}. - Note that you can chain commands with semicolon, `;`{=snippet}. - You can open this popup window at any time to remind yourself of the goal using **Ctrl+G**. @@ -27,7 +27,7 @@ objectives: - To reuse that command without having to retype it press the upward arrow on your keyboard. This will allow you to select previous commands. - Ahead of you is a six steps long corridor. Move to its end, i.e. the - coordinates `(8,0)` marked with the second purple flower. + coordinates `(8,0)` marked with the second purple `flower`{=entity}. - You can open this popup window at any time to remind yourself of the goal using **Ctrl+G**. condition: | @@ -64,7 +64,7 @@ objectives: - goal: - Good job! You are now ready to move and turn on your own. - To complete this challenge, move your robot to the northeast corner, - to the coordinates `(8,8)` marked with one flower. + to the coordinates `(8,8)` marked with one `flower`{=entity}. - Remember you can press the upward arrow on your keyboard to select previous commands. - You can open this popup window at any time to remind yourself of the goal using **Ctrl+G**. diff --git a/data/scenarios/Tutorials/place.yaml b/data/scenarios/Tutorials/place.yaml index ee05cd9678..592cd83874 100644 --- a/data/scenarios/Tutorials/place.yaml +++ b/data/scenarios/Tutorials/place.yaml @@ -11,7 +11,7 @@ objectives: - goal: - Previously you learned how to plunder a plentiful forest for wood. Now you will learn how to plant trees to obtain as much wood as you need. - - There is a fast-growing tree (called `"spruce"`) ahead of you. You could `grab` + - There is a fast-growing tree (called `spruce`{=entity}) ahead of you. You could `grab` it as before, but you now have a new device called a `harvester`{=entity}. If you `harvest` a tree rather than `grab` it, a new tree will grow in its place after some time. @@ -19,12 +19,12 @@ objectives: below you using the `place` command. - | Using these commands in conjunction, you can plant new growable entities by - placing and then harvesting them. For example, to plant a new spruce seed + placing and then harvesting them. For example, to plant a new `spruce`{=entity} seed you can write: ``` place "spruce"; harvest ``` - - Your goal is to collect 6 spruce trees. You can speed this up + - Your goal is to collect 6 `spruce`{=entity} trees. You can speed this up by planting more trees. - | TIP: You can get a sneak peak at a feature we will explain later and type: diff --git a/data/scenarios/Tutorials/require.yaml b/data/scenarios/Tutorials/require.yaml index 9170ec40cb..429624bd2a 100644 --- a/data/scenarios/Tutorials/require.yaml +++ b/data/scenarios/Tutorials/require.yaml @@ -6,20 +6,20 @@ objectives: - goal: - The `build` command automatically equips devices on the newly built robot that it knows - will be required. For example, if you `build {move}`, some `treads`{=entity} + will be required. For example, if you `build {move}`{=snippet}, some `treads`{=entity} will automatically be equipped on the new robot since it needs them to `move`. (To see what the `build` command will equip, you can type `requirements `{=snippet} where ``{=snippet} is any expression.) - However, sometimes you need a device but `build` can't tell that you need it. In this case, you can use the special `require`{=snippet} command to require a particular device. For example, if you - `build {require "3D printer"; move}`, a `3D printer`{=entity} will be + `build {require "3D printer"; move}`{=snippet}, a `3D printer`{=entity} will be equipped on the new robot (in addition to `treads`{=entity}) even though it does not execute any commands that use one. - Your goal is to pick a flower on the other side of the river and bring it back to your base. You win when the base has a `periwinkle`{=entity} flower in its inventory. - - "Hint: robots will drown in the water unless they have a `boat`{=entity} device + - "Hint: robots will drown in the `water`{=entity} unless they have a `boat`{=entity} device equipped!" condition: | try { diff --git a/data/scenarios/Tutorials/requireinv.yaml b/data/scenarios/Tutorials/requireinv.yaml index b27ac6ccb9..c8a905a0ad 100644 --- a/data/scenarios/Tutorials/requireinv.yaml +++ b/data/scenarios/Tutorials/requireinv.yaml @@ -10,10 +10,10 @@ objectives: supplies in your inventory. In this case, you can write `require `{=snippet} to require a certain number of copies of a certain entity to be placed in your inventory. - - For example, `build {require 10 "flower"; move; move}` would + - For example, `build {require 10 "flower"; move; move}`{=snippet} would build a robot with 10 `flower`{=entity}s in its inventory. - Your goal in this challenge is to cover the entire 4x4 gray area - with rocks! + with `rock`{=entity}s! - | Remember that you can define commands to simplify your task, for example: ``` diff --git a/data/scenarios/Tutorials/scan.yaml b/data/scenarios/Tutorials/scan.yaml index d49650b3f7..fdba9486b0 100644 --- a/data/scenarios/Tutorials/scan.yaml +++ b/data/scenarios/Tutorials/scan.yaml @@ -7,7 +7,7 @@ objectives: - When you land on an alien planet, all the entities in the world will be unfamiliar to you, but you can learn what they are using the `scan` command, enabled by a `scanner`{=entity} device. - - Send one or more robots to move next to some of the unknown entities (marked as ?), + - Send one or more robots to move next to some of the unknown entities (marked as "?"), scan them (with something like `scan forward` or `scan north`), and then return to the base and execute `upload base`. - For more information about the `scan` and `upload` commands, read diff --git a/data/scenarios/Tutorials/type-errors.yaml b/data/scenarios/Tutorials/type-errors.yaml index 2efd182769..75538b2b61 100644 --- a/data/scenarios/Tutorials/type-errors.yaml +++ b/data/scenarios/Tutorials/type-errors.yaml @@ -13,7 +13,7 @@ objectives: - | `turn move`{=snippet} - | - `place tree`{=snippet} (without double quotes around "tree") + `place tree`{=snippet} (without double quotes around `tree`{=snippet}) - | `move move`{=snippet} - The last expression might give the most confusing error. diff --git a/data/scenarios/Tutorials/world101.yaml b/data/scenarios/Tutorials/world101.yaml index 5c7cd402dd..d9ce6de01a 100644 --- a/data/scenarios/Tutorials/world101.yaml +++ b/data/scenarios/Tutorials/world101.yaml @@ -21,8 +21,8 @@ objectives: via the `run` command. See https://github.com/swarm-game/swarm/tree/main/editors for help configuring your editor with support for swarm-lang. - - Your first task is to collect three or more trees. You can - remind yourself of the available commands using F4. + - Your first task is to collect three or more `tree`{=entity}s. You can + remind yourself of the available commands using **F4**. condition: | try { n <- as base {count "tree"};