diff --git a/data/entities.yaml b/data/entities.yaml index 3bad5068c..da5f4f7d7 100644 --- a/data/entities.yaml +++ b/data/entities.yaml @@ -497,7 +497,7 @@ description: - A robot with a boat equipped can float on top of water without drowning. - | - Note: most devices are automatically equipped on robots that + **NOTE:** most devices are automatically equipped on robots that will require them; but this doesn't work in the case of boats since floating is not associated with any particular command. To manually ensure a boat is equipped on a robot, just add the special command `require "boat"` to the robot's program. @@ -765,7 +765,7 @@ - Equipping treads on a robot allows it to move and turn. - The `move` command moves the robot forward one unit. - | - Example:' + Example: ``` move; move; // move two units ``` diff --git a/data/scenarios/Challenges/Ranching/gated-paddock.yaml b/data/scenarios/Challenges/Ranching/gated-paddock.yaml index 144740893..9552aaa96 100644 --- a/data/scenarios/Challenges/Ranching/gated-paddock.yaml +++ b/data/scenarios/Challenges/Ranching/gated-paddock.yaml @@ -142,7 +142,7 @@ objectives: create specialDrill; equip specialDrill; - // NOTE: System robots can walk on water + // **NOTE:** System robots can walk on water // so we only need this if we want to // demo the algorithm with a player robot. // create "boat"; diff --git a/data/scenarios/Tutorials/bind2.yaml b/data/scenarios/Tutorials/bind2.yaml index c763cb435..71c562b71 100644 --- a/data/scenarios/Tutorials/bind2.yaml +++ b/data/scenarios/Tutorials/bind2.yaml @@ -13,7 +13,7 @@ objectives: - | Build a robot to retrieve and restore the mystery artifact to its proper place! - | - Note: If you find yourself stuck, you can select "Start over" from + **NOTE:** If you find yourself stuck, you can select "Start over" from the "Quit" (**Ctrl+Q**) dialog. condition: | try { @@ -38,7 +38,7 @@ objectives: For example, `grab` has type `cmd text`{=type}, and returns the name of the grabbed entity as a text value. - | - To use the result of a command later, you need "bind notation", which + To use the result of a command later, you need _bind notation_, which consists of a variable name and a leftwards-pointing arrow before the command. For example: - | diff --git a/data/scenarios/Tutorials/build.yaml b/data/scenarios/Tutorials/build.yaml index ca19efc46..2fa71beb8 100644 --- a/data/scenarios/Tutorials/build.yaml +++ b/data/scenarios/Tutorials/build.yaml @@ -15,10 +15,10 @@ 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 + **TIP:** Newly built robots start out facing the same direction as their parent, which in the tutorials will always be north. condition: | try { diff --git a/data/scenarios/Tutorials/conditionals.yaml b/data/scenarios/Tutorials/conditionals.yaml index 30b769743..c5f83e2e1 100644 --- a/data/scenarios/Tutorials/conditionals.yaml +++ b/data/scenarios/Tutorials/conditionals.yaml @@ -42,13 +42,13 @@ objectives: must also be in curly braces: the type of `build` is `{cmd a} -> cmd robot`{=type}. - | - TIP: Note that `if` requires a `bool`{=type}, not a `cmd bool`{=type}! So you cannot directly say + **TIP:** Note that `if` requires a `bool`{=type}, not a `cmd bool`{=type}! So you cannot directly say `if (ishere "very small rock") {...} {...}`{=snippet}. Instead you can write `b <- ishere "very small rock"; if b {...} {...}`{=snippet}. You might enjoy writing your own function of type `cmd bool -> {cmd a} -> {cmd a} -> cmd a`{=type} to encapsulate this pattern. - | - TIP: the two branches of an `if` must have the same type. In particular, + **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. diff --git a/data/scenarios/Tutorials/craft.yaml b/data/scenarios/Tutorials/craft.yaml index f3549fe4b..885914798 100644 --- a/data/scenarios/Tutorials/craft.yaml +++ b/data/scenarios/Tutorials/craft.yaml @@ -10,13 +10,13 @@ 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 + **NOTE:** when used after opening quotes in the REPL, the Tab key can cycle through possible completions of a name. E.g., type: - | `> make "br[Tab][Tab]`{=snippet} diff --git a/data/scenarios/Tutorials/def.yaml b/data/scenarios/Tutorials/def.yaml index 75cef114d..12cf62804 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,15 +20,15 @@ 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 + **TIP:** the type annotation in a definition is optional. You could also write `def m4 = move; move; move; move end`, and Swarm would infer the type of `m4`{=snippet}. - | - TIP: writing function definitions at the prompt is annoying. + **TIP:** writing function definitions at the prompt is annoying. You can also put definitions in a `.sw`{=path} file and load it with the `run` command. Check out https://github.com/swarm-game/swarm/tree/main/editors diff --git a/data/scenarios/Tutorials/equip.yaml b/data/scenarios/Tutorials/equip.yaml index a25996d17..2c1af3201 100644 --- a/data/scenarios/Tutorials/equip.yaml +++ b/data/scenarios/Tutorials/equip.yaml @@ -13,7 +13,7 @@ objectives: Try typing `build {}` - 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 + Fortunately, there is a `3D printer`{=entity} lying nearby. Go `grab` it, then `equip` it with `equip "3D printer"`. - | You win by building your first robot: diff --git a/data/scenarios/Tutorials/farming.yaml b/data/scenarios/Tutorials/farming.yaml index a05987d8c..f40b79859 100644 --- a/data/scenarios/Tutorials/farming.yaml +++ b/data/scenarios/Tutorials/farming.yaml @@ -6,7 +6,8 @@ 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 +21,15 @@ 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." + - | + **TIP:** the `ishere` command can be used to test for the presence of a + (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 85d13edb0..55f691a99 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 a61501f15..5f9c0d869 100644 --- a/data/scenarios/Tutorials/lambda.yaml +++ b/data/scenarios/Tutorials/lambda.yaml @@ -5,7 +5,7 @@ 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 diff --git a/data/scenarios/Tutorials/move.yaml b/data/scenarios/Tutorials/move.yaml index 41cc161c4..0d6be79e7 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**. @@ -23,11 +23,13 @@ objectives: - | Previously you could move twice by chaining the move command: - | + ``` move; move + ``` - 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 +66,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 ee05cd967..e17637973 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,15 +19,15 @@ 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: + **TIP:** You can get a sneak peak at a feature we will explain later and type: ``` def t = move; place "spruce"; harvest; end ``` diff --git a/data/scenarios/Tutorials/require.yaml b/data/scenarios/Tutorials/require.yaml index 9170ec40c..1b1803aac 100644 --- a/data/scenarios/Tutorials/require.yaml +++ b/data/scenarios/Tutorials/require.yaml @@ -19,7 +19,7 @@ objectives: - 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 b27ac6ccb..219a48862 100644 --- a/data/scenarios/Tutorials/requireinv.yaml +++ b/data/scenarios/Tutorials/requireinv.yaml @@ -13,7 +13,7 @@ objectives: - For example, `build {require 10 "flower"; move; move}` 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 d49650b3f..fdba9486b 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 2efd18276..75538b2b6 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/types.yaml b/data/scenarios/Tutorials/types.yaml index d479609d1..4bc4486e8 100644 --- a/data/scenarios/Tutorials/types.yaml +++ b/data/scenarios/Tutorials/types.yaml @@ -12,7 +12,7 @@ objectives: its type will be displayed in gray text at the top right of the window. - For example, if you try typing `move`, you can see that it has type `cmd unit`{=type}, which means that `move` is a command which - returns a value of the unit type (also written `()`). + returns a value of the `unit`{=type} type (also written `()`). - As another example, you can see that `turn` has type `dir -> cmd unit`{=type}, meaning that `turn` is a function which takes a direction as input and results in a command. diff --git a/data/scenarios/Tutorials/world101.yaml b/data/scenarios/Tutorials/world101.yaml index 5c7cd402d..5fdca2d6b 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"}; @@ -43,7 +43,7 @@ objectives: - Now that you have a harvester, you can use `harvest` instead of `grab` whenever you pick up a growing item (check for the word "growing" at the top of the item description), to leave behind a seed that will regrow. - - "TIP: since you only have a single harvester device for now, whenever you + - "**TIP:** since you only have a single harvester device for now, whenever you send out a robot to harvest something, try programming it to come back to the base when it is done. Then, execute `salvage` to get the harvester back, so you can reuse it in another robot later." @@ -51,7 +51,7 @@ objectives: define and use parameterized commands. Scan some things and use the process of elimination to find one. Since lambdas regrow, once you find one, try getting it with `harvest`. - - "TIP: remember that you can click on cells in the world to see their + - "**TIP:** remember that you can click on cells in the world to see their coordinates." condition: | try { as base {has "lambda"} } {return false}