swarm 0.4 → 0.5.0.0

raw patch · 183 files changed

+6792/−2594 lines, 183 filesdep +astardep +palettedep +pandocdep −criteriondep ~brickdep ~megaparsecdep ~prettyprinterPVP ok

version bump matches the API change (PVP)

Dependencies added: astar, palette, pandoc, pandoc-types, scientific, tasty-bench, terminal-size

Dependencies removed: criterion

Dependency ranges changed: brick, megaparsec, prettyprinter, tasty

API changes (from Hackage documentation)

Files

• CHANGELOG.md +37/−0
• app/Main.hs +36/−14
• bench/Benchmark.hs +0/−125
• data/entities.yaml +43/−17
• data/scenarios/Challenges/00-ORDER.txt +2/−0
• data/scenarios/Challenges/2048.yaml +3/−3
• data/scenarios/Challenges/Mazes/easy_cave_maze.yaml +1/−1
• data/scenarios/Challenges/Ranching/_gated-paddock/enclosure-checking.sw +3/−145
• data/scenarios/Challenges/Ranching/_gated-paddock/meandering-sheep.sw +1/−20
• data/scenarios/Challenges/Ranching/capture.yaml +1/−1
• data/scenarios/Challenges/Ranching/gated-paddock.yaml +15/−154
• data/scenarios/Challenges/Ranching/powerset.yaml +1/−1
• data/scenarios/Challenges/Sliding Puzzles/3x3.yaml +1/−1
• data/scenarios/Challenges/Sokoban/Gadgets/no-reverse.yaml +1/−1
• data/scenarios/Challenges/Sokoban/Gadgets/one-way.yaml +1/−1
• data/scenarios/Challenges/Sokoban/Simple/trapdoor.yaml +1/−1
• data/scenarios/Challenges/Sokoban/foresight.yaml +2/−2
• data/scenarios/Challenges/_combo-lock/setup.sw +85/−0
• data/scenarios/Challenges/_combo-lock/solution.sw +65/−0
• data/scenarios/Challenges/_wave/solution.sw +15/−0
• data/scenarios/Challenges/arbitrage.yaml +1/−1
• data/scenarios/Challenges/blender.yaml +3/−3
• data/scenarios/Challenges/bridge-building.yaml +14/−14
• data/scenarios/Challenges/bucket-brigade.yaml +5/−5
• data/scenarios/Challenges/chess_horse.yaml +2/−2
• data/scenarios/Challenges/combo-lock.yaml +135/−0
• data/scenarios/Challenges/friend.yaml +2/−0
• data/scenarios/Challenges/gopher.yaml +9/−7
• data/scenarios/Challenges/hackman.yaml +2/−2
• data/scenarios/Challenges/ice-cream.yaml +3/−3
• data/scenarios/Challenges/maypole.yaml +1/−1
• data/scenarios/Challenges/teleport.yaml +1/−1
• data/scenarios/Challenges/wave.yaml +89/−0
• data/scenarios/Challenges/wolf-goat-cabbage.yaml +3/−3
• data/scenarios/Challenges/word-search.yaml +2/−2
• data/scenarios/Speedruns/curry.yaml +1/−1
• data/scenarios/Speedruns/forester.yaml +2/−2
• data/scenarios/Speedruns/mithril.yaml +2/−2
• data/scenarios/Testing/00-ORDER.txt +7/−0
• data/scenarios/Testing/1341-command-count.yaml +107/−0
• data/scenarios/Testing/1355-combustion.yaml +133/−0
• data/scenarios/Testing/1430-built-robot-ownership.yaml +64/−0
• data/scenarios/Testing/1535-ping/00-ORDER.txt +2/−0
• data/scenarios/Testing/1535-ping/1535-in-range.yaml +87/−0
• data/scenarios/Testing/1535-ping/1535-out-of-range.yaml +67/−0
• data/scenarios/Testing/1535-ping/_1535-in-range/buddy.sw +41/−0
• data/scenarios/Testing/1535-ping/_1535-in-range/solution.sw +57/−0
• data/scenarios/Testing/1535-ping/_1535-out-of-range/solution.sw +11/−0
• data/scenarios/Testing/1536-custom-unwalkable-entities.yaml +50/−0
• data/scenarios/Testing/836-pathfinding/00-ORDER.txt +8/−0
• data/scenarios/Testing/836-pathfinding/836-automatic-waypoint-navigation.yaml +154/−0
• data/scenarios/Testing/836-pathfinding/836-no-path-exists1.yaml +48/−0
• data/scenarios/Testing/836-pathfinding/836-no-path-exists2.yaml +52/−0
• data/scenarios/Testing/836-pathfinding/836-path-exists-distance-limit-reachable.yaml +33/−0
• data/scenarios/Testing/836-pathfinding/836-path-exists-distance-limit-unreachable.yaml +35/−0
• data/scenarios/Testing/836-pathfinding/836-path-exists-find-entity-unwalkable.yaml +51/−0
• data/scenarios/Testing/836-pathfinding/836-path-exists-find-entity.yaml +47/−0
• data/scenarios/Testing/836-pathfinding/836-path-exists-find-location.yaml +47/−0
• data/scenarios/Testing/836-pathfinding/_836-automatic-waypoint-navigation/gardener.sw +18/−0
• data/scenarios/Testing/836-pathfinding/_836-automatic-waypoint-navigation/patrol.sw +35/−0
• data/scenarios/Testing/836-pathfinding/_836-automatic-waypoint-navigation/rabbit.sw +16/−0
• data/scenarios/Testing/836-pathfinding/_836-path-exists/find-entity-solution.sw +14/−0
• data/scenarios/Testing/836-pathfinding/_836-path-exists/find-entity-unwalkable-solution.sw +22/−0
• data/scenarios/Testing/836-pathfinding/_836-path-exists/find-location-solution.sw +14/−0
• data/scenarios/Testing/Achievements/00-ORDER.txt +1/−0
• data/scenarios/Testing/Achievements/RobotIntoWater.yaml +48/−0
• data/scenarios/Testing/_Validation/1221-duplicate-entities.yaml +1/−0
• data/scenarios/Tutorials/type-errors.yaml +1/−1
• data/scenarios/Tutorials/types.yaml +2/−1
• data/scenarios/Tutorials/world101.sw +36/−0
• data/scenarios/Tutorials/world101.yaml +5/−3
• editors/emacs/swarm-mode.el +3/−0
• editors/vim/swarm.lua +8/−0
• editors/vim/swarm.vim +24/−0
• editors/vscode/syntaxes/swarm.tmLanguage.json +1/−1
• src/Swarm/App.hs +6/−5
• src/Swarm/Constant.hs +5/−1
• src/Swarm/Doc/Gen.hs +60/−50
• src/Swarm/Doc/Pedagogy.hs +8/−3
• src/Swarm/Doc/Schema/Arrangement.hs +42/−0
• src/Swarm/Doc/Schema/Parse.hs +52/−0
• src/Swarm/Doc/Schema/Refined.hs +145/−0
• src/Swarm/Doc/Schema/Render.hs +194/−0
• src/Swarm/Doc/Schema/SchemaType.hs +38/−0
• src/Swarm/Doc/Util.hs +22/−0
• src/Swarm/Game/Achievement/Attainment.hs +14/−4
• src/Swarm/Game/Achievement/Definitions.hs +33/−7
• src/Swarm/Game/Achievement/Description.hs +86/−75
• src/Swarm/Game/Achievement/Persistence.hs +7/−5
• src/Swarm/Game/CESK.hs +37/−26
• src/Swarm/Game/Entity.hs +68/−9
• src/Swarm/Game/Exception.hs +28/−22
• src/Swarm/Game/Failure.hs +10/−2
• src/Swarm/Game/Location.hs +46/−23
• src/Swarm/Game/Log.hs +0/−76
• src/Swarm/Game/Recipe.hs +41/−24
• src/Swarm/Game/ResourceLoading.hs +28/−4
• src/Swarm/Game/Robot.hs +174/−64
• src/Swarm/Game/Scenario.hs +19/−3
• src/Swarm/Game/Scenario/Objective.hs +4/−4
• src/Swarm/Game/Scenario/Objective/Validation.hs +4/−3
• src/Swarm/Game/Scenario/Scoring/Best.hs +4/−1
• src/Swarm/Game/Scenario/Scoring/CodeSize.hs +5/−2
• src/Swarm/Game/Scenario/Scoring/ConcreteMetrics.hs +4/−1
• src/Swarm/Game/Scenario/Scoring/GenericMetrics.hs +7/−4
• src/Swarm/Game/Scenario/Status.hs +17/−10
• src/Swarm/Game/Scenario/Style.hs +4/−0
• src/Swarm/Game/Scenario/Topography/Area.hs +9/−4
• src/Swarm/Game/Scenario/Topography/Cell.hs +11/−9
• src/Swarm/Game/Scenario/Topography/EntityFacade.hs +5/−5
• src/Swarm/Game/Scenario/Topography/Navigation/Portal.hs +19/−4
• src/Swarm/Game/Scenario/Topography/Navigation/Util.hs +44/−0
• src/Swarm/Game/Scenario/Topography/Navigation/Waypoint.hs +16/−0
• src/Swarm/Game/Scenario/Topography/Placement.hs +3/−0
• src/Swarm/Game/Scenario/Topography/Structure.hs +6/−3
• src/Swarm/Game/ScenarioInfo.hs +6/−4
• src/Swarm/Game/State.hs +457/−297
• src/Swarm/Game/Step.hs +244/−313
• src/Swarm/Game/Step/Combustion.hs +227/−0
• src/Swarm/Game/Step/Pathfinding.hs +137/−0
• src/Swarm/Game/Step/Util.hs +224/−0
• src/Swarm/Game/Terrain.hs +3/−2
• src/Swarm/Game/Universe.hs +19/−3
• src/Swarm/Game/Value.hs +6/−2
• src/Swarm/Game/World.hs +10/−9
• src/Swarm/Game/World/Coords.hs +4/−4
• src/Swarm/Game/World/Modify.hs +40/−0
• src/Swarm/Game/World/Parse.hs +4/−11
• src/Swarm/Game/World/Render.hs +65/−0
• src/Swarm/Game/World/Typecheck.hs +2/−2
• src/Swarm/Language/Capability.hs +12/−1
• src/Swarm/Language/Direction.hs +4/−4
• src/Swarm/Language/Key.hs +4/−4
• src/Swarm/Language/LSP/Hover.hs +2/−0
• src/Swarm/Language/Parse.hs +4/−4
• src/Swarm/Language/Pretty.hs +117/−54
• src/Swarm/Language/Requirement.hs +6/−6
• src/Swarm/Language/Syntax.hs +50/−42
• src/Swarm/Language/Text/Markdown.hs +8/−7
• src/Swarm/Language/Typecheck.hs +28/−3
• src/Swarm/Log.hs +70/−0
• src/Swarm/ReadableIORef.hs +1/−1
• src/Swarm/TUI/Attr.hs +0/−189
• src/Swarm/TUI/Controller.hs +138/−135
• src/Swarm/TUI/Controller/Util.hs +5/−5
• src/Swarm/TUI/Editor/Controller.hs +14/−12
• src/Swarm/TUI/Editor/Json.hs +5/−1
• src/Swarm/TUI/Editor/Masking.hs +2/−0
• src/Swarm/TUI/Editor/Model.hs +13/−6
• src/Swarm/TUI/Editor/Palette.hs +3/−2
• src/Swarm/TUI/Editor/Util.hs +33/−21
• src/Swarm/TUI/Editor/View.hs +4/−2
• src/Swarm/TUI/Launch/Controller.hs +2/−2
• src/Swarm/TUI/Launch/Prep.hs +7/−6
• src/Swarm/TUI/Launch/View.hs +1/−1
• src/Swarm/TUI/Model.hs +17/−32
• src/Swarm/TUI/Model/Goal.hs +7/−3
• src/Swarm/TUI/Model/Menu.hs +4/−1
• src/Swarm/TUI/Model/Name.hs +10/−0
• src/Swarm/TUI/Model/Repl.hs +35/−18
• src/Swarm/TUI/Model/StateUpdate.hs +6/−6
• src/Swarm/TUI/Model/UI.hs +17/−33
• src/Swarm/TUI/View.hs +253/−121
• src/Swarm/TUI/View/Achievement.hs +6/−6
• src/Swarm/TUI/View/Attribute/Attr.hs +229/−0
• src/Swarm/TUI/View/Attribute/CustomStyling.hs +37/−0
• src/Swarm/TUI/View/Attribute/Util.hs +28/−0
• src/Swarm/TUI/View/CellDisplay.hs +81/−42
• src/Swarm/TUI/View/CustomStyling.hs +0/−38
• src/Swarm/TUI/View/Objective.hs +8/−4
• src/Swarm/TUI/View/Util.hs +1/−1
• src/Swarm/Util.hs +53/−2
• src/Swarm/Util/UnitInterval.hs +38/−0
• src/Swarm/Util/WindowedCounter.hs +189/−0
• src/Swarm/Version.hs +7/−1
• src/Swarm/Web.hs +140/−80
• swarm.cabal +50/−13
• test/bench/Benchmark.hs +168/−0
• test/integration/Main.hs +103/−17
• test/unit/TestLanguagePipeline.hs +37/−18
• test/unit/TestNotification.hs +8/−7
• test/unit/TestPretty.hs +12/−0
• test/unit/TestUtil.hs +1/−1

@@ -1,5 +1,42 @@ # Revision history for swarm +## **0.5.0.0** - 2023-11-01++### Bugfixes++* Fix bug where some pretty-printed terms contained extra elaborated+  terms inserted by @byorgey ([#1497](https://github.com/swarm-game/swarm/pull/1497))++### New Features++#### Language++* New `path` command for pathfinding by @kostmo ([#1523](https://github.com/swarm-game/swarm/pull/1523))++#### New scenarios++* "Robot wave" scenario by @kostmo ([#1556](https://github.com/swarm-game/swarm/pull/1556))+* Combination locks scenario by @kostmo ([#1591](https://github.com/swarm-game/swarm/pull/1591))++#### New achievements++* Grant `RobotIntoWater` achievement by @byorgey ([#1504](https://github.com/swarm-game/swarm/pull/1504))+* Achievement for pointless swapping by @kostmo ([#1588](https://github.com/swarm-game/swarm/pull/1588))++#### UI enhancements++* Support Markdown in achievement descriptions by @kostmo ([#1508](https://github.com/swarm-game/swarm/pull/1508))+* Render map preview on scenario selection screen by @kostmo ([#1515](https://github.com/swarm-game/swarm/pull/1515))+* Robot activity counts in F2 menu by @kostmo ([#1484](https://github.com/swarm-game/swarm/pull/1484))+* Show robot IDs in F2 menu by @kostmo ([#1482](https://github.com/swarm-game/swarm/pull/1482))+* Print REPL errors inline and get rid of error popup by @byorgey ([#1487](https://github.com/swarm-game/swarm/pull/1487))+* Improvements to scrolling by @byorgey ([#1481](https://github.com/swarm-game/swarm/pull/1481))++#### Command line options++* Improvements to term pretty-printing by @xsebek ([#1464](https://github.com/swarm-game/swarm/pull/1464))+* `swarm format` now actually formats by @xsebek ([#1459](https://github.com/swarm-game/swarm/pull/1459))+ ## **0.4.0.0** - 2023-08-18  ### Bugfixes

@@ -13,15 +13,21 @@ import Data.Text.IO qualified as Text import GitHash (GitInfo, giBranch, giHash, tGitInfoCwdTry) import Options.Applicative+import Prettyprinter+import Prettyprinter.Render.Text qualified as RT import Swarm.App (appMain) import Swarm.Doc.Gen (EditorType (..), GenerateDocs (..), PageAddress (..), SheetType (..), generateDocs)+import Swarm.Game.World.Render (printScenarioMap, renderScenarioMap) import Swarm.Language.LSP (lspMain)-import Swarm.Language.Pipeline (processTerm)+import Swarm.Language.Parse (readTerm)+import Swarm.Language.Pretty (ppr) import Swarm.TUI.Model (AppOpts (..), ColorMode (..)) import Swarm.TUI.Model.UI (defaultInitLgTicksPerSecond)+import Swarm.Util ((?)) import Swarm.Version import Swarm.Web (defaultPort)-import System.Exit (exitFailure, exitSuccess)+import System.Console.Terminal.Size qualified as Term+import System.Exit (exitFailure) import System.IO (hPrint, stderr) import Text.Read (readMaybe) @@ -33,10 +39,13 @@   Nothing -> ""   Just git -> " (" <> giBranch git <> "@" <> take 10 (giHash git) <> ")" +type Width = Int+ data CLI   = Run AppOpts-  | Format Input+  | Format Input (Maybe Width)   | DocGen GenerateDocs+  | RenderMap FilePath   | LSP   | Version @@ -44,8 +53,9 @@ cliParser =   subparser     ( mconcat-        [ command "format" (info (format <**> helper) (progDesc "Format a file"))+        [ command "format" (info (Format <$> format <*> optional widthOpt <**> helper) (progDesc "Format a file"))         , command "generate" (info (DocGen <$> docgen <**> helper) (progDesc "Generate docs"))+        , command "map" (info (RenderMap <$> strArgument (metavar "FILE")) (progDesc "Render a scenario world map."))         , command "lsp" (info (pure LSP) (progDesc "Start the LSP"))         , command "version" (info (pure Version) (progDesc "Get current and upstream version."))         ]@@ -63,10 +73,12 @@               <*> pure gitInfo           )  where-  format :: Parser CLI+  format :: Parser Input   format =-    (Format Stdin <$ switch (long "stdin" <> help "Read code from stdin"))-      <|> (Format . File <$> strArgument (metavar "FILE"))+    (Stdin <$ switch (long "stdin" <> help "Read code from stdin"))+      <|> (File <$> strArgument (metavar "FILE"))+  widthOpt :: Parser Width+  widthOpt = option auto (long "width" <> metavar "COLUMNS" <> help "Use layout with maximum width")   docgen :: Parser GenerateDocs   docgen =     subparser . mconcat $@@ -75,7 +87,9 @@       , command "keys" (info (pure SpecialKeyNames) $ progDesc "Output list of recognized special key names")       , command "cheatsheet" (info (CheatSheet <$> address <*> cheatsheet <**> helper) $ progDesc "Output nice Wiki tables")       , command "pedagogy" (info (pure TutorialCoverage) $ progDesc "Output tutorial coverage")+      , command "endpoints" (info (pure WebAPIEndpoints) $ progDesc "Generate markdown Web API documentation.")       ]+   editor :: Parser (Maybe EditorType)   editor =     Data.Foldable.asum@@ -103,6 +117,7 @@       , Just Recipes <$ switch (long "recipes" <> help "Generate recipes page (uses data from recipes.yaml)")       , Just Capabilities <$ switch (long "capabilities" <> help "Generate capabilities page (uses entity map)")       , Just Commands <$ switch (long "commands" <> help "Generate commands page (uses constInfo, constCaps and inferConst)")+      , Just Scenario <$ switch (long "scenario" <> help "Generate scenario schema page")       ]   seed :: Parser (Maybe Int)   seed = optional $ option auto (long "seed" <> short 's' <> metavar "INT" <> help "Seed to use for world generation")@@ -157,13 +172,19 @@ showInput (File fp) = pack fp  -- | Utility function to validate and format swarm-lang code-formatFile :: Input -> IO ()-formatFile input = do+formatFile :: Input -> Maybe Width -> IO ()+formatFile input mWidth = do   content <- getInput input-  case processTerm content of-    Right _ -> do-      Text.putStrLn content-      exitSuccess+  case readTerm content of+    Right Nothing -> Text.putStrLn ""+    Right (Just ast) -> do+      mWindow <- Term.size+      let mkOpt w = LayoutOptions (AvailablePerLine w 1.0)+      let opt =+            fmap mkOpt mWidth+              ? fmap (\(Term.Window _h w) -> mkOpt w) mWindow+              ? defaultLayoutOptions+      Text.putStrLn . RT.renderStrict . layoutPretty opt $ ppr ast     Left e -> do       Text.hPutStrLn stderr $ showInput input <> ":" <> e       exitFailure@@ -180,6 +201,7 @@   case cli of     Run opts -> appMain opts     DocGen g -> generateDocs g-    Format fo -> formatFile fo+    Format fo w -> formatFile fo w+    RenderMap mapPath -> printScenarioMap =<< renderScenarioMap mapPath     LSP -> lspMain     Version -> showVersion

@@ -1,125 +0,0 @@-{-# LANGUAGE OverloadedStrings #-}-{-# LANGUAGE QuasiQuotes #-}---- |--- SPDX-License-Identifier: BSD-3-Clause-module Main where--import Control.Lens ((&), (.~), (^.))-import Control.Monad (replicateM_)-import Control.Monad.Except (runExceptT)-import Control.Monad.State (evalStateT, execStateT)-import Criterion.Main (Benchmark, bench, bgroup, defaultConfig, defaultMainWith, whnfAppIO)-import Criterion.Types (Config (timeLimit))-import Data.Map qualified as M-import Swarm.Game.CESK (emptyStore, initMachine)-import Swarm.Game.Display (defaultRobotDisplay)-import Swarm.Game.Location-import Swarm.Game.Robot (TRobot, mkRobot)-import Swarm.Game.State (GameState, addTRobot, creativeMode, multiWorld)-import Swarm.Game.Step (gameTick)-import Swarm.Game.Terrain (TerrainType (DirtT))-import Swarm.Game.Universe (Cosmic (..), SubworldName (DefaultRootSubworld))-import Swarm.Game.World (WorldFun (..), newWorld)-import Swarm.Language.Context qualified as Context-import Swarm.Language.Pipeline (ProcessedTerm)-import Swarm.Language.Pipeline.QQ (tmQ)-import Swarm.TUI.Model (gameState)-import Swarm.TUI.Model.StateUpdate (classicGame0)-import Swarm.Util.Erasable---- | The program of a robot that does nothing.-idleProgram :: ProcessedTerm-idleProgram = [tmQ| {} |]---- | The program of a robot which waits a random number of ticks, changes its---   appearance, then waits another random number of ticks, places a tree, and---   then self-destructs.-treeProgram :: ProcessedTerm-treeProgram =-  [tmQ|-  {-    r <- random 100;-    wait (r + 300);-    appear "|";-    r <- random 100;-    wait (r + 300);-    place "tree";-    selfdestruct-  }-  |]---- | The program of a robot that moves forward forever.-moverProgram :: ProcessedTerm-moverProgram =-  [tmQ|-    let forever : cmd unit -> cmd unit = \c. c; forever c-    in forever move-  |]---- | The program of a robot that moves in circles forever.-circlerProgram :: ProcessedTerm-circlerProgram =-  [tmQ|-    let forever : cmd unit -> cmd unit = \c. c; forever c-    in forever (-      move;-      turn right;-      move;-      turn right;-      move;-      turn right;-      move;-      turn right;-    )-  |]---- | Initializes a robot with program prog at location loc facing north.-initRobot :: ProcessedTerm -> Location -> TRobot-initRobot prog loc = mkRobot () Nothing "" mempty (Just $ Cosmic DefaultRootSubworld loc) north defaultRobotDisplay (initMachine prog Context.empty emptyStore) [] [] False False 0---- | Creates a GameState with numRobot copies of robot on a blank map, aligned---   in a row starting at (0,0) and spreading east.-mkGameState :: (Location -> TRobot) -> Int -> IO GameState-mkGameState robotMaker numRobots = do-  let robots = [robotMaker (Location (fromIntegral x) 0) | x <- [0 .. numRobots - 1]]-  Right initAppState <- runExceptT classicGame0-  execStateT-    (mapM addTRobot robots)-    ( (initAppState ^. gameState)-        & creativeMode .~ True-        & multiWorld .~ M.singleton DefaultRootSubworld (newWorld (WF $ const (fromEnum DirtT, ENothing)))-    )---- | Runs numGameTicks ticks of the game.-runGame :: Int -> GameState -> IO ()-runGame numGameTicks = evalStateT (replicateM_ numGameTicks gameTick)--main :: IO ()-main = do-  idlers <- mkGameStates idleProgram [10, 20 .. 40]-  trees <- mkGameStates treeProgram [10, 20 .. 40]-  circlers <- mkGameStates circlerProgram [10, 20 .. 40]-  movers <- mkGameStates moverProgram [10, 20 .. 40]-  -- In theory we should force the evaluation of these game states to normal-  -- form before running the benchmarks. In practice, the first of the many-  -- criterion runs for each of these benchmarks doesn't look like an outlier.-  defaultMainWith-    (defaultConfig {timeLimit = 10})-    [ bgroup-        "run 1000 game ticks"-        [ bgroup "idlers" (toBenchmarks idlers)-        , bgroup "trees" (toBenchmarks trees)-        , bgroup "circlers" (toBenchmarks circlers)-        , bgroup "movers" (toBenchmarks movers)-        ]-    ]- where-  mkGameStates :: ProcessedTerm -> [Int] -> IO [(Int, GameState)]-  mkGameStates prog sizes = zip sizes <$> mapM (mkGameState (initRobot prog)) sizes--  toBenchmarks :: [(Int, GameState)] -> [Benchmark]-  toBenchmarks gameStates =-    [ bench (show n) $ whnfAppIO (runGame 1000) gs-    | (n, gs) <- gameStates-    ]

@@ -7,9 +7,22 @@     A tall, living entity made of a tough cellular material called "wood".     They regrow after being harvested and are an important raw ingredient used     in making many different devices.-  properties: [portable, growable, opaque]+  properties: [portable, growable, opaque, combustible]   growth: [500, 600]+  combustion:+    ignition: 0.01+    duration: [80, 120]+    product: ash +- name: ash+  display:+    attr: rock+    char: '#'+  description:+  - |+    Burned-out remnants of combustion.+  properties: [portable]+ - name: branch   display:     attr: wood@@ -25,7 +38,11 @@     char: 'l'   description:   - A wooden log, obtained by harvesting a tree and cutting off its branches.-  properties: [portable]+  properties: [portable, combustible]+  combustion:+    ignition: 0.05+    duration: [40, 80]+    product: ash  - name: board   display:@@ -33,7 +50,11 @@     char: 'w'   description:   - A wooden board, made by cutting a log into pieces.-  properties: [portable]+  properties: [portable, combustible]+  combustion:+    ignition: 0.2+    duration: [20, 40]+    product: ash  - name: workbench   display:@@ -57,7 +78,11 @@   description:   - A flat material made of pressed and dried wood fibers,     used as a surface on which to inscribe symbols.-  properties: [portable]+  properties: [portable, combustible]+  combustion:+    ignition: 0.5+    duration: [10, 20]+    product: ash  - name: PhD thesis   display:@@ -336,8 +361,12 @@   - A plant with tufts of soft fibers that can be harvested and used     to make things, including sheets of material that the local     aliens like to drape over their bodies.-  properties: [portable, growable]+  properties: [portable, growable, combustible]   growth: [100, 800]+  combustion:+    ignition: 0.1+    duration: [20, 40]+    product: ash  - name: linotype   display:@@ -765,18 +794,16 @@   - Equipping treads on a robot allows it to move and turn.   - The `move` command moves the robot forward one unit.   - |-    Example:-    ```-    move; move; // move two units-    ```+    For example to move two units:+  - |+    `move; move;`   - The `turn` command takes a direction as an argument, which     can be either absolute (north, west, east, south) or relative     (left, right, forward, back, down).   - |     Example:-    ```-    move; turn left; move; turn right-    ```+  - |+    `move; turn left; move; turn right`   capabilities: [move, turn]   properties: [portable] @@ -1200,16 +1227,15 @@   description:   - |     A compass gives a robot the ability to orient using the cardinal-    directions north, south, west, and east; for example, `turn west;-    move; turn north`.+    directions north, south, west, and east. For example:   - |+    `turn west; move; turn north`+  - |     It also enables the `heading : cmd dir` command, which returns the     robot's current heading. For example, the following code moves     east and then restores the same heading as before:   - |-    ```-    d <- heading; turn east; move; turn d-    ```+    `d <- heading; turn east; move; turn d`   properties: [portable]   capabilities: [orient] 

@@ -7,10 +7,12 @@ word-search.yaml gopher.yaml ice-cream.yaml+combo-lock.yaml hanoi.yaml hackman.yaml lights-out.yaml bucket-brigade.yaml+wave.yaml wolf-goat-cabbage.yaml blender.yaml friend.yaml

@@ -5,10 +5,10 @@ objectives:   - goal:     - OK, OK, it's not really the same as the classic "2048" game.-      However, your goal is still to make 2048!  You start with a `1`+      However, your goal is still to make 2048!  You start with a `1`{=entity}       which regrows immediately when-      it is harvested, so if you plant it, you can get as many as you want.  Your-      job is to combine `1`s in order to make a `2048`+      it is `harvest`ed, so if you plant it, you can get as many as you want.  Your+      job is to combine `1`{=entity}s in order to make a `2048`{=entity}       entity.     - "Hint: the `format` command can turn numbers into strings!"     condition: |

@@ -7,7 +7,7 @@   - You are at the top of a cave that gradually descends until reaching a dead end.   - At its bottom is a great treasure.   - Luckily, the cave does not branch out, so it is easy to find the path to the treasure.-  - Send a robot to the the item marked as '!'. You win once the robot grabs it.+  - Send a robot to the the item marked as '**!**'. You win once the robot `grab`s it.   condition: |     j <- robotNamed "judge";     as j {has "goal"}

@@ -1,131 +1,11 @@-// Algorithm:-// -----------// Maintain current direction until a wall is encountered.-// Then enter "wall-following mode".-// This mode presumes the wall is not a loop.-// Wall-following mode exploits recursion to keep track of how many left turns were made-// and then unwinds them again by ensuring each is paired with a right turn.-// Once the recursion is fully unwound, the robot proceeds along its original direction-// (though it may now be laterally displaced).-//-// (If it was a loop, then an "oriented breadcrumb" would need to be left.-// The breadcrumb is oriented in case a single-width passage is backtracked-// along the opposite wall.)--/** A "gate" is walkable, so we need to supplement the "blocked" check with this function.-Since fences are "unwalkable", they do not need to be mentioned in this function.-*/-def isFenced =-    s <- scan forward;-    return (-        case s-            (\_. false)-            (\x. x == "gate")-    );-    end;- def isBlockedOrFenced =     b <- blocked;-    f <- isFenced;-    return (b || f);-    end;--// Returns true if we've already placed two-// breadcrumbs on a given tile, false otherwise.-def leaveBreadcrumbs =-    -    let bc1 = "fresh breadcrumb" in-    let bc2 = "treaded breadcrumb" in--    wasTraversedOnce <- ishere bc1;-    if wasTraversedOnce {-        _crumb <- grab;-        make bc2;-        place bc2;-        return false;-    } {-        wasTraversedTwice <- ishere bc2;-        if wasTraversedTwice {-            return true;-        } {-            // Make sure nothing's in the way before we place-            // our breadcrumb:-            x <- scan down;-            case x return (\y.-                // If we're on a water tile, get rid of-                // it with our special "drilling" recipe-                if (y == "water") {-                    drill down;-                    // Nothing will remain on the ground.-                    // after making the "steam" via-                    // the drilling recipe.-                    return ();-                } {-                    grab;-                    return ();-                };-            );--            make bc1;-            place bc1;-            return false;-        };-    };-    end;--def goForwardToPatrol = \wasBlocked.-    b <- isBlockedOrFenced;-    if b {-        turn left;-        goForwardToPatrol true;-        turn right;-        goForwardToPatrol false;-    } {-        if wasBlocked {-            isLoop <- leaveBreadcrumbs;-            if isLoop {-                fail "loop";-            } {};-        } {};-        move;-    };-    end;--/**-There should only be one place in the-code where an exception is thrown: that is,-if a treaded breadcrumb is encountered.-*/-def checkIsEnclosedInner =-    try {-        goForwardToPatrol false;-        // Water is the outer boundary-        hasWater <- ishere "water";-        if hasWater {-            return false;-        } {-            checkIsEnclosedInner;-        };-    } {-        return true;-    };+    return b;     end;  def checkIsEnclosed =--    // The "evaporator" drill is used-    // to clear water tiles.-    let specialDrill = "evaporator" in-    create specialDrill;-    equip specialDrill;--    // 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";-//    equip "boat";--    checkIsEnclosedInner;+    maybePath <- path (inL ()) (inR "water");+    case maybePath (\_. return True) (\_. return False);     end;  def boolToInt = \b. if (b) {return 1} {return 0}; end;@@ -215,34 +95,12 @@     }     end; -/**-There are 3 sheep.-They have indices 1, 2, 3.-(The base has index 0).--THIS DOES NOT WORK!-*/-def countSheepWithRecursive = \predicateCmd. \i.--    if (i > 0) {-        val <- getValForSheepIndex predicateCmd i;-        recursiveCount <- countSheepWithRecursive predicateCmd $ i - 1;-        return $ val + recursiveCount;-    } {-        return 0;-    }-    end;-- def countSheepWith = \predicateCmd.-     val1 <- getValForSheepIndex predicateCmd 1;     val2 <- getValForSheepIndex predicateCmd 2;     val3 <- getValForSheepIndex predicateCmd 3;     return $ val1 + val2 + val3;-     end;-  justFilledGap <- as base {     isStandingOnBridge;

@@ -1,26 +1,7 @@ // A "sheep" that wanders around randomly. -/** A "gate" is walkable, so we need to supplement the "blocked" check with this function.-Since fences are "unwalkable", they do not need to be mentioned in this function.-*/-def isFenced =-    s <- scan forward;-    return (-        case s-            (\_. false)-            (\x. x == "gate")-    );-    end;--def isBlockedOrFenced =-    b <- blocked;-    f <- isFenced;-    return (b || f);-    end;- def elif = \p.\t.\e. {if p t e} end; - def turnToClover = \direction.    x <- scan direction;@@ -95,7 +76,7 @@   dist <- random 3;   repeat dist ( -    b <- isBlockedOrFenced;+    b <- blocked;     if b {} {       move;     };

@@ -15,7 +15,7 @@     goal:       - |         This porcine pest has been running amok.-        Block the pig by a "monolith" on all four sides to capture it.+        Block the pig by a `monolith`{=entity} on all four sides to capture it.       - Blocking on fewer than four sides will spook the pig, and he will escape!     condition: |       def isSurrounded = \n.

@@ -12,143 +12,23 @@         You've homesteaded on a small island in the ocean.         It's time to gather resources to trade.       - |-        You encounter some feral sheep (@). They slowly wander the island and eat grass.+        You encounter some feral sheep (**@**). They slowly wander the island and eat grass.         Your mind wanders to textiles...       - |         First, paddock at least one sheep so they don't drown.         Make sure there are no gaps in the fence!       - |-        Note that you can use the "drill" command (by way of the "post puller" tool)-        to demolish a fence that has been "placed".+        Note that you can use the `drill` command (by way of the `post puller`{=entity} tool)+        to demolish a `fence`{=entity} that has been `place`d.     condition: |--      // Algorithm:-      // -----------      // Maintain current direction until a wall is encountered.-      // Then enter "wall-following mode".-      // This mode presumes the wall is not a loop.-      // Wall-following mode exploits recursion to keep track of how many left turns were made-      // and then unwinds them again by ensuring each is paired with a right turn.-      // Once the recursion is fully unwound, the robot proceeds along its original direction-      // (though it may now be laterally displaced).-      //-      // (If it was a loop, then an "oriented breadcrumb" would need to be left.-      // The breadcrumb is oriented in case a single-width passage is backtracked-      // along the opposite wall.)--      /** A "gate" is walkable, so we need to supplement the "blocked" check with this function.-      Since fences are "unwalkable", they do not need to be mentioned in this function.-      */-      def isFenced =-          s <- scan forward;-          return (-              case s-                  (\_. false)-                  (\x. x == "gate")-          );-          end;-       def isBlockedOrFenced =           b <- blocked;-          f <- isFenced;-          return (b || f);-          end;--      // Returns true if we've already placed two-      // breadcrumbs on a given tile, false otherwise.-      def leaveBreadcrumbs =--          let bc1 = "fresh breadcrumb" in-          let bc2 = "treaded breadcrumb" in--          wasTraversedOnce <- ishere bc1;-          if wasTraversedOnce {-              _crumb <- grab;-              make bc2;-              place bc2;-              return false;-          } {-              wasTraversedTwice <- ishere bc2;-              if wasTraversedTwice {-                  return true;-              } {-                  // Make sure nothing's in the way before we place-                  // our breadcrumb:-                  x <- scan down;-                  case x return (\y.-                      // If we're on a water tile, get rid of-                      // it with our special "drilling" recipe-                      if (y == "water") {-                          drill down;-                          // Nothing will remain on the ground.-                          // after making the "steam" via-                          // the drilling recipe.-                          return ();-                      } {-                          grab;-                          return ();-                      };-                  );--                  make bc1;-                  place bc1;-                  return false;-              };-          };-          end;--      def goForwardToPatrol = \wasBlocked.-          b <- isBlockedOrFenced;-          if b {-              turn left;-              goForwardToPatrol true;-              turn right;-              goForwardToPatrol false;-          } {-              if wasBlocked {-                  isLoop <- leaveBreadcrumbs;-                  if isLoop {-                      fail "loop";-                  } {};-              } {};-              move;-          };-          end;--      /**-      There should only be one place in the-      code where an exception is thrown: that is,-      if a treaded breadcrumb is encountered.-      */-      def checkIsEnclosedInner =-          try {-              goForwardToPatrol false;-              // Water is the outer boundary-              hasWater <- ishere "water";-              if hasWater {-                  return false;-              } {-                  checkIsEnclosedInner;-              };-          } {-              return true;-          };+          return b;           end;        def checkIsEnclosed =--          // The "evaporator" drill is used-          // to clear water tiles.-          let specialDrill = "evaporator" in-          create specialDrill;-          equip specialDrill;--          // **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";-      //    equip "boat";--          checkIsEnclosedInner;+          maybePath <- path (inL ()) (inR "water");+          case maybePath (\_. return True) (\_. return False);           end;        def boolToInt = \b. if (b) {return 1} {return 0}; end;@@ -238,35 +118,13 @@           }           end; -      /**-      There are 3 sheep.-      They have indices 1, 2, 3.-      (The base has index 0).--      THIS DOES NOT WORK!-      */-      def countSheepWithRecursive = \predicateCmd. \i.--          if (i > 0) {-              val <- getValForSheepIndex predicateCmd i;-              recursiveCount <- countSheepWithRecursive predicateCmd $ i - 1;-              return $ val + recursiveCount;-          } {-              return 0;-          }-          end;--       def countSheepWith = \predicateCmd.-           val1 <- getValForSheepIndex predicateCmd 1;           val2 <- getValForSheepIndex predicateCmd 2;           val3 <- getValForSheepIndex predicateCmd 3;           return $ val1 + val2 + val3;-           end; -       justFilledGap <- as base {           isStandingOnBridge;       };@@ -287,7 +145,7 @@         The sheep will move toward something edible on         an adjacent tile and will eat it if they walk over it.       - |-        You may want to add a gate to the fence+        You may want to add a `gate`{=entity} to the fence         to give yourself easier access.     condition: |-       def getTruthForSheepIndex = \predicateCmd. \i.@@ -317,11 +175,12 @@        anySheep (has "clover") 3;     prerequisite: enclose_sheep-  - goal:+  - teaser: Knit sweater+    goal:       - |-        Yum! Contented, well-fed sheep may drop wool.+        Yum! Contented, well-fed sheep may drop `wool`{=entity}.       - |-        Winter is coming! Collect three wool bundles to make a sweater.+        Winter is coming! Collect three wool bundles to make a `sweater`{=entity}.       - |         Each sheep drops a finite amount over         their lifetime.@@ -356,8 +215,8 @@       - [0, gate]       - [10, hinge]   - name: sheep-    description:-      - meandering livestock+    description: |+      meandering livestock     display:       invisible: false       char: '@'@@ -365,6 +224,8 @@     dir: [0, 1]     inventory:       - [4, wool]+    unwalkable:+      - gate     program: |       run "scenarios/Challenges/Ranching/_gated-paddock/meandering-sheep.sw"; entities:

@@ -32,7 +32,7 @@         However, his experiment is incomplete! He has forgotten one combination.       - |         Place the missing hybrid combination in the empty eastern-most column.-        After you have done this, `place` the "bell" anywhere, and then Bill will inspect+        After you have done this, `place` the `bell`{=entity} anywhere, and then Bill will inspect         your work.     prerequisite:         not: wrong_anwser

@@ -23,7 +23,7 @@       - |         Or, if you prefer, `drill` a tile to cause it to slide         into the adjacent empty space. However, you must not drill a tile that-        has nowhere to slide. Also, drilling consumes "ink", which will be replenished+        has nowhere to slide. Also, drilling consumes `ink`{=entity}, which will be replenished         after the sliding operation is complete, so avoid drilling too fast in         succession.     condition: |

@@ -7,7 +7,7 @@ seed: 0 objectives:   - goal:-      - Grab the flower.+      - Grab the `flower`{=entity}.     condition: |       as base {         has "flower";

@@ -7,7 +7,7 @@ seed: 0 objectives:   - goal:-      - Grab the flower.+      - Grab the `flower`{=entity}.     condition: |       as base {         has "flower";

@@ -12,7 +12,7 @@ seed: 0 objectives:   - goal:-      - Place the flower on the target.+      - Place the `flower`{=entity} on the target.       - You may have to start over if you get stuck.     condition: |       as base {

@@ -13,7 +13,7 @@     fg: "#bbbbff" objectives:   - goal:-      - Push a monolith onto the base's initial location.+      - Push a `monolith`{=entity} onto the base's initial location.     condition: |       as base {         teleport self (0,0);@@ -23,7 +23,7 @@     hidden: true     optional: true     goal:-      - Grab the flower+      - Grab the `flower`{=entity}     condition: |       as base {         has "flower";

@@ -0,0 +1,85 @@+def elif = \t. \then. \else. {if t then else} end+def else = \t. t end+def doN = \n. \f. if (n > 0) {f; doN (n - 1) f} {}; end;++def colorFromIndex = \i.+    if (i == 0) {"R"}+    $ elif (i == 1) {"G"}+    $ else {"B"};+    end;++def pixelFromColor = \c.+    "dial (" ++ c ++ ")";+    end;++def checkCombo = \noMismatchYet. \stepsTaken. \colorString.++    let remainingCount = chars colorString in+    if (remainingCount > 0) {++        let splitted = split 1 colorString in+        let nextLetter = fst splitted in+        let remainingLetters = snd splitted in+        let expectedPixel = pixelFromColor nextLetter in++        move;+        isExpectedHere <- ishere expectedPixel;+        checkCombo (isExpectedHere && noMismatchYet) (stepsTaken + 1) remainingLetters;+    } {+        turn back;++        // Replace the cell watches+        doN stepsTaken (watch down; move);+        turn back;+        return noMismatchYet;+    };+    end;++def unlockGate = \n.+    move;+    turn right;+    move;+    turn left;+    doN n (grab; move);+    return ()+    end;++def doUntilCorrect = \colorString.+    isCorrect <- checkCombo true 0 colorString;+    if isCorrect {+        let remainingCount = chars colorString in+        unlockGate remainingCount;+        return true;+    } {+        wait 1000;+        doUntilCorrect colorString;+    };+    end;+    +def createCombo = \colorString.+    // Scenario map starts with red pixels to+    // mark the combo sequence+    redPixelHere <- ishere $ pixelFromColor "R";++    if redPixelHere {+        r <- random 3;+        let newColor = colorFromIndex r in+        watch down;+        move;+        createCombo $ newColor ++ colorString;+    } {+        turn back;+        return colorString;+    };+    end;++def go =+    comboString <- instant (      +        move;+        createCombo "";+    );+    // say comboString;+    instant $ doUntilCorrect comboString;+    end;++go;

@@ -0,0 +1,65 @@+def moveToLock =+    emptyHere <- isempty;+    if emptyHere {move; moveToLock} {};+    end;++def cycleCombos = \n.+    wait 1;+    entityNorth <- scan north;+    let hasGate = case entityNorth (\_. false) (\x. x == "gate") in+    if hasGate {+        if (n > 0) {+            drill down;+            maybeNextEnt <- scan east;+            case maybeNextEnt return (\_. turn east; move; cycleCombos 3);+            cycleCombos $ n - 1;+        } {+            turn west;+            move;+        };+    } {}+    end;++def moveUntilBlocked =+    isblocked <- blocked;+    if isblocked {} {+        move;+        moveUntilBlocked;+    };+    end;++def toLeftEdge =+    turn north;+    move;+    turn left;+    moveUntilBlocked;+    turn north;+    end;++def goUp =+    toLeftEdge;+    move; move; move;+    end;++def grabBitcoin =+    move; move;+    turn right;+    move; move;+    grab;+    end;++def go =+    moveToLock;+    cycleCombos 3;+    goUp;+    cycleCombos 3;+    goUp;+    cycleCombos 3;+    goUp;+    cycleCombos 3;++    toLeftEdge;+    grabBitcoin;+    end;++go;

@@ -0,0 +1,15 @@+def go =+    move;+    go;+    end;++def start =+    turn right;+    wait 5;+    try {+        go;+    } {};+    grab;+    end;++start;

@@ -16,7 +16,7 @@         As an itinerant merchant, you may exploit market asymmetry         for profit.       - |-        Amass a fortune of 100 paperclips.+        Amass a fortune of 100 `paperclip`{=entity}s.     condition: |       as base {         pcount <- count "paperclip";

@@ -8,10 +8,10 @@   - teaser: Get amulet     goal:       - |-        `grab` the Amulet of Yoneda from the northwest sanctum while-        timing your passage carefully to avoid Side Effects (X) on patrol.+        `grab` the `Amulet of Yoneda`{=entity} from the northwest sanctum while+        timing your passage carefully to avoid Side Effects (**X**) on patrol.       - |-        To unlock a red door, `drill` it with the "door key" equipped.+        To unlock a red door, `drill` it with the `door key`{=entity} equipped.     condition: |       as base {has "Amulet of Yoneda"}     prerequisite:

@@ -55,7 +55,7 @@   - id: hammer_time     teaser: Hammer time     goal:-      - Produce an obsidian shard.+      - Produce an `obsidian shard`{=entity}.     optional: true     hidden: true     condition: |@@ -87,14 +87,14 @@   - id: get_map     teaser: Get the map     goal:-      - As a humble peat farmer, you subsist in a simple cabin by the bog.+      - As a humble `peat`{=entity} farmer, you subsist in a simple cabin by the `bog`{=entity}.         Though long content with this ascetic lifestyle, recently the barren walls have         left you restless. Something is missing...       - "The majestic landscape that is your back yard is insufficient to distract you---not-        even the ferocious, lava-spewing volcano little more than a stone's throw from+        even the ferocious, `lava`{=entity}-spewing volcano little more than a stone's throw from         your porch.         You are preoccupied by one task: to find the perfect household decoration."-      - First, grab a map to orient yourself.+      - First, grab a `map`{=entity} to orient yourself.     condition: |       as base {         has "map";@@ -103,18 +103,18 @@     teaser: Find the temple     prerequisite: get_map     goal:-      - You study the map.-      - Glacier-bound mountains tower in the east,-        a volcano oozes a river of lava to the north, and beyond that lies a mountain lake, punctuated with islands+      - You study the `map`{=entity}.+      - Glacier-bound mountains tower in the `east`,+        a volcano oozes a river of `lava`{=entity} to the `north`, and beyond that lies a mountain lake, punctuated with islands         in the northwest.         Iron mines penetrate the base of the volcano. They could be useful, but how will you get there?-      - A jungle abuts the volcano, ensconcing an ancient ruin.+      - A `jungle`{=entity} abuts the volcano, ensconcing an ancient ruin.         The map notes that bygone travelers have stashed tools among the northeasterly mountains to         blaze a path through the jungle.-      - Your only neighbor, a hemp farmer to the northwest, has evacuated since the sudden volcanic eruption.-      - A disused quarry and clay pit flanks your cabin to the west, as does the familiar, swampy bog to the east.-        A highly-prized flower is said to grow in the caves beyond the bog.-      - Your mind is made up. You will pillage the ruins for treasure! Head to the ruins and "scan" them.+      - Your only neighbor, a `hemp`{=entity} farmer to the northwest, has evacuated since the sudden volcanic eruption.+      - A disused quarry and clay pit flanks your cabin to the `west`, as does the familiar, swampy `bog`{=entity} to the `east`.+        A highly-prized `flower`{=entity} is said to grow in the caves beyond the bog.+      - Your mind is made up. You will pillage the ruins for treasure! Head to the ruins and `scan` them.         Ingenuity and endurance are your allies as you forge paths through varied obstacles.         Study your "recipes" for clues!     condition: |@@ -126,8 +126,8 @@     prerequisite: find_temple     goal:       - "A note on the door says:"-      - '"Greetings, intrepid traveler. Encircle this temple with the rare "flower" of the southeastern-        caves, and the treasure of this temple shall be revealed."'+      - '"Greetings, intrepid traveler. Encircle this temple with the rare `flower`{=entity} of the southeastern+        caves, and the treasure of this `temple`{=entity} shall be revealed."'       - Plant a ring of flowers around the jungle temple.     condition: |       as base {

@@ -57,14 +57,14 @@   - id: deliver_coal_lump     teaser: Get coal to base     goal:-      - Deliver a "coal lump" to the base.+      - Deliver a `coal lump`{=entity} to the base.       - |-        To excavate coal from the "lignite mine" (M), a robot needs to-        `drill` while in posession of a "bucketwheel excavator".+        To excavate coal from the `lignite mine`{=entity} (**M**), a robot needs to+        `drill` while in possession of a `bucketwheel excavator`{=entity}.       - |         To assemble the excavator, you'll need to repurpose-        some "treads".-        Unfortunately, you have only one set of "treads".+        some `treads`{=entity}.+        Unfortunately, you have only one set of `treads`{=entity}.         You'll have to make do...     condition: |       as base {has "coal lump"}

@@ -4,8 +4,8 @@ description: In this quirky challenge, you move as the chess knight piece. Can you capture the enemy king? objectives:   - goal:-      - Robots can use the 'move' command to move.-        But they only 'turn' in cardinal directions. +      - Robots can use the `move` command to move.+        But they only `turn` in cardinal directions.       - You are special. You are a knight.        - Go forth and capture the King!     condition: |

@@ -0,0 +1,135 @@+version: 1+name: Combination locks+author: Karl Ostmo+description: |+  Unlock the gates+creative: false+seed: 4+objectives:+  - goal:+      - |+        Several combination-locked gates lie between you+        and treasure.+      - |+        Each "dial" can be one of three colors.+        `drill` a dial to cycle to its next color.+        The adjacent `gate`{=entity} opens when the correct+        combination is set.+      - |+        Unlock all of the combination locks and `grab`+        the `bitcoin`{=entity}.+    condition: |+      as base {has "bitcoin"};+robots:+  - name: base+    dir: [1, 0]+    display:+      invisible: false+    devices:+      - ADT calculator+      - branch predictor+      - hourglass+      - comparator+      - compass+      - dictionary+      - drill+      - grabber+      - lambda+      - lodestone+      - logger+      - keyboard+      - net+      - scanner+      - strange loop+      - treads+  - name: lockbot+    system: true+    dir: [1, 0]+    display:+      invisible: true+    program: |+      run "scenarios/Challenges/_combo-lock/setup.sw"+solution: |+   run "scenarios/Challenges/_combo-lock/solution.sw"+entities:+  - name: gate+    display:+      char: '#'+    description:+      - A locked door+    properties: [known, unwalkable]+  - name: "dial (R)"+    display:+      char: '•'+      attr: red+    description:+      - A red dial+    properties: [known]+  - name: "dial (G)"+    display:+      char: '•'+      attr: green+    description:+      - A green dial+    properties: [known]+  - name: "dial (B)"+    display:+      char: '•'+      attr: blue+    description:+      - A blue dial+    properties: [known]+recipes:+  - in:+    - [1, "dial (R)"]+    out:+    - [1, "dial (G)"]+    required:+    - [1, drill]+    time: 0+  - in:+    - [1, "dial (G)"]+    out:+    - [1, "dial (B)"]+    required:+    - [1, drill]+    time: 0+  - in:+    - [1, "dial (B)"]+    out:+    - [1, "dial (R)"]+    required:+    - [1, drill]+    time: 0+known: [boulder, water, bitcoin]+world:+  dsl: |+    {water}+  upperleft: [-1, -1]+  offset: false+  palette:+    '.': [grass, erase]+    '$': [grass, bitcoin]+    '@': [grass, boulder]+    '#': [grass, gate]+    'B': [grass, erase, base]+    'c': [grass, dial (R)]+    'a': [grass, erase, lockbot]+  map: |+    .......$......+    @@@@@......@@@+    ....@######@..+    ....acccccc...+    ..............+    @@@@@.....@@@@+    ....@#####@...+    ....accccc....+    ..............+    @@@@@....@@@@@+    ....@####@....+    ....acccc.....+    ..............+    @@@@@...@@@@@@+    ....@###@.....+    ..B.accc......+    ..............

@@ -88,6 +88,8 @@     '*': [grass, flower]     '@': [stone, boulder]   upperleft: [-20, 2]+  dsl: |+    "classic"   map: |-     c,..,,,,,,..,,,,...,.     ,..,,,,,,,...........

@@ -10,12 +10,12 @@     teaser: Defeat gopher     goal:       - |-        A gopher (G) is defiling your immaculate garden!+        A gopher (**G**) is defiling your immaculate garden!       - |-        He will burrow (o) underground awhile, then pop up+        He will burrow (**o**) underground awhile, then pop up         anywhere within the rectangular grassy region-        to gloat atop his "mound" of dirt for a short time.-        `drill` the "mound" while he sits to drive him+        to gloat atop his `mound`{=entity} of dirt for a short time.+        `drill` the `mound`{=entity} while he sits to drive him         away. Eventually you should wear down his resolve!     condition: |       try {@@ -129,12 +129,14 @@    run "scenarios/Challenges/_gopher/solution.sw" known: [] world:+  dsl: |+    "classic"   upperleft: [-1, 1]   offset: false   palette:-    'x': [dirt]-    '.': [grass]-    'g': [dirt, null, gopher]+    'x': [dirt, erase]+    '.': [grass, erase]+    'g': [dirt, erase, gopher]   map: |     xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx     x............................x

@@ -19,10 +19,10 @@   - teaser: Get pellets     goal:       - |-        Pick up all of the caffeine "pellets" so that Hackman can write more code.+        Pick up all of the caffeine `pellet`{=entity}s so that Hackman can write more code.       - |         Pay no mind to the colorful ghosts meandering about. That is, unless-        you are feeling generous with your "donuts"...+        you are feeling generous with your `donut`{=entity}s...       - |         Can you find all of the secret objectives?     condition: |

@@ -11,15 +11,15 @@     goal:       - |         Congratulations on the grand opening of your new ice cream shop.-        You have advertised: "All you can eat, for 1 bitcoin!"+        You have advertised: "All you can eat, for 1 `bitcoin`{=entity}!"       - |-        A customer is approaching the "Counter". They look hungry!+        A customer is approaching the `Counter`{=entity}. They look hungry!       - "..."       - |         Customer: "`give` me a cone, and then I'll tell you how many scoops I want."       - "..."       - |-        Oh dear, you've forgotten to stock your shop with a "calculator".+        Oh dear, you've forgotten to provision your shop with a `calculator`{=entity}.         Let's hope this order is simple.     condition: |       customer <- robotnamed "customer";

@@ -19,7 +19,7 @@     teaser: Around you go!     goal:       - |-        Go around the maypole several times counter-clockwise.+        Go around the `maypole`{=entity} several times counter-clockwise.     condition: |       monitor <- robotnamed "monitor";       as monitor {has "dizzy"};

@@ -4,7 +4,7 @@ description: An impossible challenge - can you magically jump across the water? objectives:   - goal:-      - Get to the other room and grab the lambda.+      - Get to the other room and grab the `lambda`{=entity}.       - Oh wait.       - The tunnel is flooded.       - Just give up then. It is impossible to get there.

@@ -0,0 +1,89 @@+version: 1+name: Wave+author: Karl Ostmo+description: |+  Ride the wave+creative: false+objectives:+  - goal:+      - |+        Grab the `bitcoin`{=entity} at the east end of the path.+        Don't let the patrolling robots catch you!+    prerequisite:+      not: got_caught+    condition: |+      as base {has "bitcoin"};+  - id: got_caught+    teaser: Got caught+    optional: true+    hidden: true+    goal:+      - |+        The robots caught you!+    condition: |+      as base {x <- meet; return $ case x (\_. false) (\_. true)};+robots:+  - name: base+    dir: [0, 1]+    devices:+      - branch predictor+      - comparator+      - dictionary+      - grabber+      - hourglass+      - clock+      - lambda+      - logger+      - net+      - scanner+      - strange loop+      - treads+  - name: wavebot+    system: true+    dir: [0, 1]+    display:+      invisible: false+      attr: 'plant'+    program: |+      def crossPath =+          move; move; move; move; move; move;+          turn back;+          wait 5;+          end;+      def go =+          crossPath;+          go;+          end;+      def start =+          pos <- whereami;+          wait $ fst pos;+          go;+          end;+      start;+solution: |+   run "scenarios/Challenges/_wave/solution.sw"+entities: []+known: [wavy water, water, bitcoin]+world:+  dsl: |+    overlay+    [ {dirt, water}+    , if (x + y / 2) % 5 == 0 then {dirt, wavy water} else {blank}+    ]+  upperleft: [-3, 6]+  offset: false+  palette:+    'B': [grass, erase, base]+    'w': [grass, erase, wavebot]+    'x': [dirt, water]+    'z': [grass, bitcoin]+    '.': [grass, erase]+  map: |+    xxxxxx..................................................................................................................................................................................................................................................xxxxxx+    xxx........................................................................................................................................................................................................................................................xxx+    x............................................................................................................................................................................................................................................................x+    B............................................................................................................................................................................................................................................................z+    x............................................................................................................................................................................................................................................................x+    xxx........................................................................................................................................................................................................................................................xxx+    xxxxxxwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwxxxxxx+    

@@ -40,11 +40,11 @@ objectives:   - goal:       - |-        Ferry all three of the wolf, goat, and cabbage across the lake.+        Ferry all three of the `wolf`{=entity}, `goat`{=entity}, and `cabbage`{=entity} across the lake.         However, only one of these can be carried at a time.       - |-        Furthermore, if left unattended together, the wolf will eat the goat,-        or the goat will eat the cabbage.+        Furthermore, if left unattended together, the `wolf`{=entity} will eat the `goat`{=entity},+        or the `goat`{=entity} will eat the `cabbage`{=entity}.     condition: |       run "data/scenarios/Challenges/_wolf-goat-cabbage/together-on-east-bank.sw";     prerequisite:

@@ -7,9 +7,9 @@ creative: false objectives:   - goal:-      - Use the `drill` command (e.g. "drill down" when on top of the+      - Use the `drill` command (e.g. `drill down` when on top of the         intended letter) to mark the sequence of letters that-        spells COW within the designated playfield.+        spells `C`{=entity}`O`{=entity}`W`{=entity} within the designated playfield.       - |         The sequence may appear horizontally in either the         leftward or rightward direction,

@@ -1,7 +1,7 @@ version: 1 name: Curry author: Brent Yorgey-description: Race to make a bowl of curry as quickly as possible.+description: Race to make a bowl of `curry`{=entity} as quickly as possible.   See the Swarm wiki for more information on Swarm speedrunning. objectives:   - goal:

@@ -1,11 +1,11 @@ version: 1 name: Forester author: Brent Yorgey-description: Race to harvest 1024 trees as quickly as possible.+description: Race to harvest 1024 `tree`{=entity}s as quickly as possible.   See the Swarm wiki for more information on Swarm speedrunning. objectives:   - goal:-      - Harvest 1024 trees as quickly as possible!+      - Harvest 1024 `tree`{=entity}s as quickly as possible!     condition: as base {n <- count "tree"; return (n >= 1024)} robots:   - name: base

@@ -1,11 +1,11 @@ version: 1 name: Mithril author: Brent Yorgey-description: Race to mine some mithril.+description: Race to mine some `mithril`{=entity}.   See the Swarm wiki for more information on Swarm speedrunning. objectives:   - goal:-      - Mine some mithril as quickly as possible!+      - Mine some `mithril`{=entity} as quickly as possible!     condition: as base {has "mithril"} robots:   - name: base

@@ -1,3 +1,4 @@+Achievements 373-drill.yaml 394-build-drill.yaml 428-drowning-destroy.yaml@@ -40,5 +41,11 @@ 1320-world-DSL 1356-portals 144-subworlds+836-pathfinding+1341-command-count.yaml+1355-combustion.yaml 1379-single-world-portal-reorientation.yaml 1399-backup-command.yaml+1430-built-robot-ownership.yaml+1536-custom-unwalkable-entities.yaml+1535-ping

@@ -0,0 +1,107 @@+version: 1+name: Count commands+creative: true+description: |+  Count commands and demonstrate various "duty cycles"+  with system robots. The four robots should have duty+  cycles of 100%, 50%, 33%, and 25% based on the number+  of ticks that they `wait`.+objectives:+  - goal:+    - |+      `grab` the "tree".+    condition: |+      as base {has "tree"}+solution: |+    move;+    move;+    wait 10;+    x <- harvest;+    if (x == "flower") {+      turn right;+      move;+      grab;+    } {+      return "";+    };+robots:+  - name: base+    dir: [1, 0]+    devices:+      - treads+      - grabber+      - harvester+      - logger+      - comparator+      - hourglass+      - branch predictor+  - name: idler1+    dir: [1, 0]+    system: true+    devices:+      - dictionary+      - strange loop+      - hourglass+    program: |+      def go =+          wait 1;+          go;+          end;+      go;+  - name: idler2+    dir: [1, 0]+    system: true+    devices:+      - dictionary+      - strange loop+      - hourglass+    program: |+      def go =+          wait 2;+          go;+          end;+      go;+  - name: idler3+    dir: [1, 0]+    system: true+    devices:+      - dictionary+      - strange loop+      - hourglass+    program: |+      def go =+          wait 3;+          go;+          end;+      go;+  - name: idler4+    dir: [1, 0]+    system: true+    devices:+      - dictionary+      - strange loop+      - hourglass+    program: |+      def go =+          wait 4;+          go;+          end;+      go;+known: [flower, tree]+world:+  default: [blank]+  palette:+    '.': [grass]+    'f': [grass, flower]+    'T': [grass, tree]+    'B': [grass, null, base]+    '1': [grass, null, idler1]+    '2': [grass, null, idler2]+    '3': [grass, null, idler3]+    '4': [grass, null, idler4]+  upperleft: [-1, 1]+  map: |+    ........1+    .B.fff..2+    ...T....3+    ........4

@@ -0,0 +1,133 @@+version: 1+name: Combustion+creative: false+seed: 0+description: Demo of spreading fire+objectives:+  - goal:+      - Blow up the dynamite+    condition: |+      j <- robotnamed "judge";+      as j {+        ishere "crater";+      };+solution: |+  def doN = \n. \f. if (n > 0) {f; doN (n - 1) f} {}; end;++  move;+  ignite forward;+  turn right;+  move;+  ignite forward;+  turn right;+  move; move; move;+  turn right;+  move;+  ignite left;+  move;+  turn right;+  doN 2 (move; ignite left);+  doN 14 move;+  turn left;+  doN 5 move;+  turn left;+  ignite right;+  doN 8 move;+  ignite right;+  doN 10 move;+  ignite right;+  doN 8 move;+  ignite right;+robots:+  - name: base+    dir: [1, 0]+    devices:+      - branch predictor+      - calculator+      - dictionary+      - comparator+      - logger+      - treads+      - torch+  - name: judge+    dir: [1, 0]+    system: true+    display:+      invisible: true+      char: J+entities:+- name: torch+  display:+    attr: wood+    char: 't'+  description:+    - Can set things on fire+  properties: [known, portable]+  capabilities: [ignite]+- name: fuse+  display:+    attr: wood+    char: '~'+  description:+    - Reliably combustible+  combustion:+    ignition: 1+    duration: [8, 8]+    product: null+  properties: [known, portable, combustible]+- name: dynamite+  display:+    attr: red+    char: '!'+  description:+    - Explosive material+  combustion:+    ignition: 1+    duration: [2, 2]+    product: crater+  properties: [known, portable, combustible]+- name: crater+  display:+    attr: rock+    char: '@'+  description:+    - Result of explosive excavation+  properties: [known]+known: [ash, tree, log, board, paper, cotton]+world:+  palette:+    'Ω': [grass, null, base]+    'T': [grass, tree]+    'q': [grass, paper]+    'l': [grass, log]+    'b': [grass, board]+    'i': [grass, cotton]+    'F': [grass, fuse]+    'd': [grass, dynamite, judge]+    '.': [grass]+  upperleft: [0, 0]+  map: |+   ..iiii....bbbb..TT..llll....iiii.....+   ..iiii....bbbb..TT..llll....iiii.....+   ..iiii....bbbb..TT..llll....iiii.....+   ..iiii....bbbb..TT..llll....iiii.....+   ..iiii....bbbb..TT..llll....iiii.....+   ..iiii....bbbb..TT..llll....iiii.....+   ..TTTT....TTTT..TT..TTTT....TTTT.....+   ..TTTT....TTTT..TT..TTTT....TTTT.....+   ................TT...................+   ................TT...................+   iiiiiiiiiii.....TT....FFFFF...FFFFF..+   ......iiiiii....TT....F...F...F...F..+   iiiiiiiiiiiii...TT....F...F...F...F..+   ......iiiiiiii........F...F...F...F..+   iiiiiiiiiiiiiii..Ω.FFFF...FFFFF...d..+   ......iiiiiiii.......................+   iiiiiiiiiiiii.....qqqqqqqqqqqqqqqq...+   ......iiiiii......qqqqqqqqqqqqqqqq...+   iiiiiiiiiii.......qqqqqqqqqqqqqqqq...+   ..................qqqqqqqqqqqqqqqq...+   ..................qqqqqqqqqqqqqqqq...+   ..................qqqqqqqqqqqqqqqq...+   ..................qqqqqqqqqqqqqqqq...+   ..................qqqqqqqqqqqqqqqq...

@@ -0,0 +1,64 @@+version: 1+name: Ownership of system-built robots+creative: true+description: Demo of system robot construction+robots:+  - name: base+    dir: [1, 0]+    display:+      char: Ω+      attr: robot+    inventory:+      - [5, logger]+      - [5, compass]+      - [5, solar panel]+      - [5, treads]+      - [5, grabber]+    devices:+      - logger+      - 3D printer+      - dictionary+      - grabber+      - hearing aid+  - name: sysbot+    dir: [-1, 0]+    system: true+    display:+      char: j+      attr: robot+      invisible: true+    devices:+      - treads+      - solar panel+      - logger+      - 3D printer+    inventory:+      - [1, solar panel]+      - [1, logger]+      - [1, treads]+      - [1, string]+    program: |+      build {move; say (format parent)}+solution: |+    listen; build {move; say (format parent)}+objectives:+  - goal:+    - Check that system robots build system robots and normal robots do not.+    - This check is performed in integration tests.+    condition: |+      r2 <- robotNumbered 2;+      r3 <- robotNumbered 3;+      return true+known: []+world:+  palette:+    'Ω': [grass, null, base]+    'r': [stone, null, sysbot]+    '.': [grass]+  upperleft: [0, 0]+  map: |+   .........+   .........+   ...Ω..r..+   .........+   .........

@@ -0,0 +1,2 @@+1535-in-range.yaml+1535-out-of-range.yaml

@@ -0,0 +1,87 @@+version: 1+name: Ping command - Demo+description: |+  Robot is in range for ping+creative: false+objectives:+  - teaser: Follow buddy+    goal:+      - You and your buddy each have half of a map to a cache of buried treasure.+      - |+        `give` him your `map piece`{=entity}, which he will use to+        locate the `bitcoin`{=entity}, which you must `grab`.+    condition: |+      as base {+        has "bitcoin";+      }+solution: |+  run "scenarios/Testing/1535-ping/_1535-in-range/solution.sw"+entities:+  - name: transponder+    display:+      char: 'x'+    description:+      - Enables `ping` command+    properties: [known, portable]+    capabilities: [ping]+  - name: map piece+    display:+      char: 'm'+    description:+      - Half of a treasure map+    properties: [known, portable]+robots:+  - name: base+    dir: [1,0]+    devices:+      - ADT calculator+      - antenna+      - branch predictor+      - comparator+      - compass+      - dictionary+      - grabber+      - hourglass+      - logger+      - transponder+      - treads+    inventory:+      - [1, map piece]+  - name: buddy+    dir: [-1, 0]+    system: true+    display:+      invisible: false+    devices:+      - ADT calculator+      - antenna+      - bitcoin+      - branch predictor+      - comparator+      - counter+      - dictionary+      - grabber+      - hourglass+      - logger+      - transponder+      - treads+    inventory:+      - [1, map piece]+      - [1, bitcoin]+    program: |+      run "scenarios/Testing/1535-ping/_1535-in-range/buddy.sw"+known: [bitcoin]+world:+  dsl: |+    overlay+    [ {terrain: stone}+    , if (x/5 + y/5) % 2 == 0 then {terrain: dirt} else {blank}+    , if ((x + 3) % 19)/12 + (y % 19)/12 == 0 then {terrain: grass} else {blank}+    ]+  palette:+    'B': [blank, null, base]+    'r': [blank, null, buddy]+    '.': [blank]+  upperleft: [-1, 0]+  map: |+    B.r

@@ -0,0 +1,67 @@+version: 1+name: Ping command - Range limits+description: |+  Demo effect of antenna on ping range+creative: false+objectives:+  - teaser: Escape+    goal:+      - Get out of `ping` range of your buddy's `transponder`{=entity}+    condition: |+      r <- robotnamed "buddy";+      as r {+        response <- ping base;+        return $ case response (\_. true) (\_. false);+      }+solution: |+  run "scenarios/Testing/1535-ping/_1535-out-of-range/solution.sw"+entities:+  - name: transponder+    display:+      char: 'x'+    description:+      - Enables `ping` command+    properties: [known, portable]+    capabilities: [ping]+robots:+  - name: base+    dir: [-1,0]+    devices:+      - calculator+      - antenna+      - branch predictor+      - comparator+      - dictionary+      - grabber+      - hourglass+      - logger+      - transponder+      - welder+  - name: buddy+    dir: [1, 0]+    devices:+      - ADT calculator+      - grabber+      - hourglass+      - logger+      - transponder+    inventory:+      - [1, treads]+    program:+      give base "treads";+known: []+world:+  dsl: |+    overlay+    [ {terrain: blank}+    , if (x/4 + y/4) % 2 == 0 then {terrain: dirt} else {blank}+    , if ((x + 3) % 19)/12 + (y % 19)/12 == 0 then {terrain: grass} else {blank}+    ]+  palette:+    'B': [stone, null, base]+    'r': [blank, null, buddy]+    '.': [ice]+    'x': [stone]+  upperleft: [0, 0]+  map: |+    rB.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x.x

@@ -0,0 +1,41 @@+def doN = \n. \f. if (n > 0) {f; doN (n - 1) f} {}; end;++def waitForMap =+    mapPieceCount <- count "map piece";+    if (mapPieceCount < 2) {+        wait 1;+        waitForMap;+    } {};+    end;++def randomReverse =+    x <- random 2;+    if (x == 0) {+        turn back;+    } {}+    end;++def goToTreasure = \dirMin. \dirMax.+    let randAmplitude = dirMax - dirMin in++    xRand <- random randAmplitude;+    let xDist = dirMin + xRand in+    randomReverse;+    doN xDist move;++    turn left;++    yRand <- random randAmplitude;+    let yDist = dirMin + yRand in+    randomReverse;+    doN yDist move;++    place "bitcoin";+    end;++def go =+    waitForMap;+    goToTreasure 10 40;+    end;++go;

@@ -0,0 +1,57 @@+def doN = \n. \f. if (n > 0) {f; doN (n - 1) f} {}; end;++def goToBuddy = \loc.++    // log $ format loc;+    +    let longitudinalDist = snd loc in+    absFwd <- if (longitudinalDist < 0) {+        turn back;+        return $ -longitudinalDist;+    } {+        return longitudinalDist;+    };+    doN absFwd move;+    if (longitudinalDist < 0) {+        turn back;+    } {};++    let lateralDist = fst loc in+    absSide <- if (lateralDist < 0) {+        turn left;+        return $ -lateralDist;+    } {+        turn right;+        return lateralDist;+    };+    doN absSide move;+    end;++def checkNeedToMove = \f. \loc.+    wait 3;+    if (loc == (0, 0)) {+        return ()+    } {+        goToBuddy loc;+        f;+    }+    end;++def pingLoop = \buddy.+    maybeLoc <- ping buddy;+    case maybeLoc return $ checkNeedToMove $ pingLoop buddy;+    end;++def giveToBuddy = \buddy.+    give buddy "map piece";+    pingLoop buddy;+    end;++def go =+    move;+    maybeBuddy <- meet;+    case maybeBuddy return giveToBuddy;+    grab;+    end;++go;

@@ -0,0 +1,11 @@+def doN = \n. \f. if (n > 0) {f; doN (n - 1) f} {}; end;++def go =+    wait 2;+    equip "treads";+    turn back;+    doN 64 move;+    unequip "antenna";+    end;++go;

@@ -0,0 +1,50 @@+version: 1+name: Custom unwalkability+description: The base robot cannot walk through trees.+  The scenario shall be failed if the robot+  manages to walk through the tree by moving+  three cells to the east.+objectives:+  - goal:+      - Get the flower+    condition: |+      as base {has "flower"};+    prerequisite:+      not: has_bitcoin+  - id: has_bitcoin+    optional: true+    goal:+      - Do not get the bitcoin+    condition: |+      as base {has "bitcoin"};+solution: |+  def tryMove = try {move} {}; end;+  tryMove;+  tryMove;+  tryMove;+  grab;+robots:+  - name: base+    dir: [1, 0]+    display:+      attr: robot+    devices:+      - logger+      - grabber+      - treads+      - dictionary+      - net+    unwalkable:+       - tree+known: [tree, flower, bitcoin]+world:+  palette:+    'B': [grass, null, base]+    '.': [grass]+    'T': [grass, tree]+    'b': [grass, bitcoin]+    'f': [grass, flower]+  upperleft: [0, 0]+  map: |+    BfTb+    

@@ -0,0 +1,8 @@+836-path-exists-find-location.yaml+836-path-exists-find-entity.yaml+836-path-exists-find-entity-unwalkable.yaml+836-path-exists-distance-limit-unreachable.yaml+836-path-exists-distance-limit-reachable.yaml+836-no-path-exists1.yaml+836-no-path-exists2.yaml+836-automatic-waypoint-navigation.yaml

@@ -0,0 +1,154 @@+version: 1+name: Automatic navigation between waypoints+description: |+  Demonstrate shortest-path patrolling between waypoints+creative: false+solution: |+  run "scenarios/Testing/836-pathfinding/_836-automatic-waypoint-navigation/patrol.sw"+objectives:+  - goal:+      - Collect 64 eggs+    condition: |+      as base {+        eggCount <- count "egg";+        return $ eggCount >= 64;+      };+attrs:+  - name: easter_egg+    fg: "#ffff88"+    bg: "#eebbff"+entities:+  - name: wayfinder+    display:+      char: 'w'+    description:+      - Enables `path` command+    properties: [known, portable]+    capabilities: [path]+  - name: atlas+    display:+      char: 'a'+    description:+      - Enables `waypoint` command+    properties: [known, portable]+    capabilities: [waypoint]+  - name: kudzu+    display:+      char: 'k'+      attr: plant+    description:+      - Dense, impassable plant.+    properties: [known, unwalkable, growable]+    growth: [30, 50]+  - name: egg+    display:+      char: 'o'+      attr: easter_egg+    description:+      - A colorful egg laid by the rabbit+    properties: [known, portable]+    growth: [5, 10]+robots:+  - name: base+    loc: [0, 0]+    dir: [1, 0]+    devices:+      - ADT calculator+      - atlas+      - branch predictor+      - comparator+      - compass+      - dictionary+      - grabber+      - logger+      - net+      - scanner+      - treads+      - wayfinder+  - name: gardener+    description: Periodically chops down the kudzu plant+    dir: [1, 0]+    system: true+    devices:+      - ADT calculator+      - branch predictor+      - comparator+      - compass+      - dictionary+      - harvester+      - treads+      - logger+    display:+      invisible: true+    program: |+      run "scenarios/Testing/836-pathfinding/_836-automatic-waypoint-navigation/gardener.sw"+  - name: rabbit+    dir: [1, 0]+    loc: [2, -2]+    system: true+    devices:+      - treads+      - logger+    inventory:+      - [64, egg]+    display:+      invisible: false+      attr: snow+      char: R+    program: |+      run "scenarios/Testing/836-pathfinding/_836-automatic-waypoint-navigation/rabbit.sw"+known: [flower, boulder, kudzu]+world:+  upperleft: [-1, 1]+  palette:+    '.': [grass]+    'k': [stone, kudzu, gardener]+    '┌': [stone, upper left corner]+    '┐': [stone, upper right corner]+    '└': [stone, lower left corner]+    '┘': [stone, lower right corner]+    '─': [stone, horizontal wall]+    '│': [stone, vertical wall]+  structures:+    - name: cornerbox+      structure:+        palette:+          '.': [dirt]+          '@': [dirt, boulder]+          'w':+            cell: [dirt]+            waypoint:+              name: wp+        map: |+          @@@+          @w.+          @.@+  placements:+    - src: cornerbox+      offset: [2, -2]+      orient:+        up: north+    - src: cornerbox+      offset: [8, -2]+      orient:+        up: east+    - src: cornerbox+      offset: [8, -6]+      orient:+        up: south+    - src: cornerbox+      offset: [2, -6]+      orient:+        up: west+  map: |+    ┌───────────┐+    │...........│+    │...........│+    │.....k.....│+    │...........│+    │...........│+    │...........│+    │.....k.....│+    │...........│+    │...........│+    └───────────┘

@@ -0,0 +1,48 @@+version: 1+name: Builtin pathfinding, unreachable goal, enclosed robot+description: |+  There is finite area to explore, so+  this will terminate quickly.+creative: false+objectives:+  - goal:+      - Flower must not be reachable.+    condition: |+      as base {+        nextDir <- path (inL ()) (inR "flower");+        return $ case nextDir (\_. true) (\_. false);+      };+solution: |+  noop;+entities:+  - name: wayfinder+    display:+      char: 'w'+    description:+      - Enables `path` command+    properties: [known, portable]+    capabilities: [path]+robots:+  - name: base+    dir: [1,0]+    devices:+      - treads+      - logger+      - ADT calculator+      - dictionary+      - wayfinder+known: [mountain, flower, tree]+world:+  palette:+    'B': [grass, null, base]+    '.': [grass]+    'x': [stone, mountain]+    'f': [grass, flower]+    'T': [grass, tree]+  upperleft: [0, 0]+  map: |+    xxxxx......+    x...x......+    x.B.x...f..+    x...x......+    xxxxx......

@@ -0,0 +1,52 @@+version: 1+name: Builtin pathfinding, unreachable goal, enclosed goal+description: |+  There is infinite area to explore, so+  this will fail to terminate unless+  a limit is set on the max distance.++  In this scenario, we fall back onto the internal distance limit.+  Normally, it would be very expensive to allow this goal condition+  check to run upon every tick. But in this case, we should+  have won the scenario by the first tick.+creative: false+objectives:+  - goal:+      - Flower must not be reachable.+    condition: |+      as base {+        nextDir <- path (inL ()) (inR "flower");+        return $ case nextDir (\_. true) (\_. false);+      };+solution: |+  noop;+entities:+  - name: wayfinder+    display:+      char: 'w'+    description:+      - Enables `path` command+    properties: [known, portable]+    capabilities: [path]+robots:+  - name: base+    dir: [1,0]+    devices:+      - treads+      - logger+      - ADT calculator+      - dictionary+      - wayfinder+world:+  palette:+    'B': [grass, null, base]+    '.': [grass]+    'x': [stone, mountain]+    'f': [grass, flower]+  upperleft: [0, 0]+  map: |+    ......xxxxx+    ......x...x+    ..B...x.f.x+    ......x...x+    ......xxxxx

@@ -0,0 +1,33 @@+version: 1+name: Builtin pathfinding - entity target+description: |+  Use distance limit with `path` command+creative: false+objectives:+  - goal:+      - Flower must be reachable within 3 cells.+    condition: |+      as base {+        nextDir <- path (inR 3) (inR "flower");+        return $ case nextDir (\_. false) (\_. true);+      };+solution: |+  move;+robots:+  - name: base+    dir: [1,0]+    devices:+      - treads+      - logger+      - dictionary+      - grabber+world:+  palette:+    'B': [grass, null, base]+    '.': [grass]+    'f': [grass, flower]+  upperleft: [0, 0]+  map: |+    .......+    .B...f.+    .......

@@ -0,0 +1,35 @@+version: 1+name: Builtin pathfinding - entity target+description: |+  Use distance limit with `path` command+creative: false+objectives:+  - goal:+      - Flower must NOT be reachable within 3 cells.+    condition: |+      as base {+        nextDir <- path (inR 3) (inR "flower");+        return $ case nextDir (\_. true) (\_. false);+      };+solution: |+  turn back;+  move;+robots:+  - name: base+    dir: [1,0]+    devices:+      - treads+      - logger+      - dictionary+      - grabber+world:+  palette:+    'B': [grass, null, base]+    '.': [grass]+    'f': [grass, flower]+  upperleft: [0, 0]+  map: |+    .......+    ..B..f.+    .......+

@@ -0,0 +1,51 @@+version: 1+name: Builtin pathfinding - entity target+description: |+  Use `path` command to navigate to an entity+creative: false+objectives:+  - goal:+      - Reach and face the water.+    condition: |+      as base {+        itemAhead <- scan forward;+        return $ case itemAhead (\_. false) (\item. item == "water");+      };+solution: |+  run "scenarios/Testing/836-pathfinding/_836-path-exists/find-entity-unwalkable-solution.sw";+entities:+  - name: wayfinder+    display:+      char: 'w'+    description:+      - Enables `path` command+    properties: [known, portable]+    capabilities: [path]+robots:+  - name: base+    dir: [1,0]+    devices:+      - ADT calculator+      - branch predictor+      - comparator+      - compass+      - dictionary+      - logger+      - grabber+      - scanner+      - treads+      - wayfinder+known: [water, boulder]+world:+  dsl: |+    {blank, boulder}+  palette:+    'B': [grass, erase, base]+    '.': [grass, erase]+    'x': [stone, boulder]+    'w': [grass, water]+  upperleft: [0, 0]+  map: |+    Bx...+    .x.x.+    ...xw

@@ -0,0 +1,47 @@+version: 1+name: Builtin pathfinding - entity target+description: |+  Use `path` command to navigate to an entity+creative: false+objectives:+  - goal:+      - Get the flower.+    condition: |+      as base {has "flower";}+solution: |+  run "scenarios/Testing/836-pathfinding/_836-path-exists/find-entity-solution.sw";+entities:+  - name: wayfinder+    display:+      char: 'w'+    description:+      - Enables `path` command+    properties: [known, portable]+    capabilities: [path]+robots:+  - name: base+    dir: [1,0]+    devices:+      - ADT calculator+      - branch predictor+      - comparator+      - compass+      - dictionary+      - logger+      - grabber+      - treads+      - wayfinder+known: [flower, mountain]+world:+  palette:+    'B': [grass, null, base]+    '.': [grass]+    'x': [stone, mountain]+    'f': [grass, flower]+  upperleft: [0, 0]+  map: |+    xxxxfx+    x.Bx.x+    x.xx.x+    x....x+    xxxxxx

@@ -0,0 +1,47 @@+version: 1+name: Builtin pathfinding - location target+description: |+  Use `path` command to navigate to a location+creative: false+objectives:+  - goal:+      - Get the flower.+    condition: |+      as base {has "flower";}+solution: |+  run "scenarios/Testing/836-pathfinding/_836-path-exists/find-location-solution.sw";+entities:+  - name: wayfinder+    display:+      char: 'w'+    description:+      - Enables `path` command+    properties: [known, portable]+    capabilities: [path]+robots:+  - name: base+    dir: [1,0]+    devices:+      - ADT calculator+      - branch predictor+      - comparator+      - compass+      - dictionary+      - logger+      - grabber+      - treads+      - wayfinder+known: [flower, mountain]+world:+  palette:+    'B': [grass, null, base]+    '.': [grass]+    'x': [stone, mountain]+    'f': [grass, flower]+  upperleft: [0, 0]+  map: |+    xxxxfx+    x.Bx.x+    x.xx.x+    x....x+    xxxxxx

@@ -0,0 +1,18 @@+def harvestPlant =+  emptyHere <- isempty;+  if emptyHere {+    watch down;+    wait 1000;+  } {+    wait 50;+    harvest;+    return ();+  };+  end;++def go =+    harvestPlant;+    go;+    end;++go;

@@ -0,0 +1,35 @@+def goDir = \f. \d.+  if (d == down) {+    eggHere <- ishere "egg";+    if eggHere {grab; return ()} {};+    return ()+  } {+    turn d;++    // An obstruction might arise after+    // navigation direction is determined+    // but before we move.+    try {+      move;+    } {};+    f;+  }+  end;++def followRoute = \loc.+    nextDir <- path (inL ()) (inL loc);+    case nextDir return $ goDir $ followRoute loc;+    end;++def visitNextWaypoint = \nextWpIdx.+    nextWaypointQuery <- waypoint "wp" nextWpIdx;+    followRoute $ snd nextWaypointQuery;++    visitNextWaypoint $ nextWpIdx + 1;+    end;++def go =+    visitNextWaypoint 0;+    end;++go;

@@ -0,0 +1,16 @@++def visitNextWaypoint = \nextWpIdx.+    emptyHere <- isempty;+    if emptyHere {+      try {+        place "egg";+      } {};+    } {};+    watch down;+    nextWaypointQuery <- waypoint "wp" nextWpIdx;+    teleport self $ snd nextWaypointQuery;+    wait 1000;+    visitNextWaypoint $ nextWpIdx + 1;+    end;++visitNextWaypoint 0;

@@ -0,0 +1,14 @@+def goDir = \f. \d.+  if (d == down) {+    grab; return ()+  } {+    turn d; move; f;+  }+  end;++def followRoute =+    nextDir <- path (inL ()) (inR "flower");+    case nextDir return $ goDir followRoute;+    end;++followRoute;

@@ -0,0 +1,22 @@+def goDir = \goalItem. \f. \d.+  if (d == down) {+    grab; return ()+  } {+    turn d;+    itemAhead <- scan forward;+    let isGoalAhead = case itemAhead (\_. false) (\item. item == goalItem) in+    if isGoalAhead {+      return ();+    } {+      move; f;+    };+  }+  end;++def followRoute =+    let goalItem = "water" in+    nextDir <- path (inL ()) (inR goalItem);+    case nextDir return $ goDir goalItem followRoute;+    end;++followRoute;

@@ -0,0 +1,14 @@+def goDir = \f. \d.+  if (d == down) {+    grab; return ()+  } {+    turn d; move; f;+  }+  end;++def followRoute =+    nextDir <- path (inL ()) (inL (4, 0));+    case nextDir return $ goDir followRoute;+    end;++followRoute;

@@ -0,0 +1,1 @@+RobotIntoWater.yaml

@@ -0,0 +1,48 @@+version: 1+name: RobotIntoWater achievement test+description: Drive a robot into the water+objectives:+  - id: build+    goal:+      - Build a robot+    condition: |+      try {robotNumbered 1; return True} {return False}+  - goal:+      - Drown it+    prerequisite: build+    condition: |+      try {robotNumbered 1; return False} {return True}+solution: |+  build { turn right; move; move; move }+robots:+  - name: base+    loc: [0,0]+    dir: [0,1]+    heavy: true+    display:+      char: Ω+      attr: robot+    devices:+      - 3D printer+      - dictionary+      - grabber+      - welder+      - life support system+      - logger+      - toolkit+      - solar panel+      - workbench+      - clock+    inventory:+      - [5, 3D printer]+      - [100, treads]+      - [70, grabber]+      - [100, solar panel]+      - [50, scanner]+      - [50, clock]+      - [5, toolkit]+seed: 0+world:+  offset: true+  dsl: |+    "classic"

@@ -14,6 +14,7 @@       char: 'Y'     description:       - Your scooter+robots: [] world:   palette:     'x': [grass, null, base]

@@ -8,7 +8,7 @@         Let's see what happens when you enter something that does not type check.         Try typing `turn 1`{=snippet} at the REPL prompt.  Clearly this is nonsense, and         the expression will be highlighted in red.  To see what the error is, hit **Enter**.-        A box will pop up with a type (or parser) error.+        The REPL will print out a type error.       - "Some other type errors for you to try:"       - |         `turn move`{=snippet}

@@ -12,7 +12,8 @@         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} type (also written `()`).+        returns a value of the `unit`{=type} type (the only value of+        type `unit`{=type} is called `()`).       - 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.

@@ -0,0 +1,36 @@+def tB = turn back end+def tR = turn right end+def tL = turn left end++def m = move end+def m2 = m;m end+def m4 = m2;m2 end+def m8 = m4;m4 end+def m9 = m8;m end+def m10 = m8;m2 end++def mg = m; grab end++def get_3_trees : cmd unit =+  tB; m; mg; mg; mg; tB; m4+end++def make_harvester : cmd unit =+  make "log"; make "log"; make "log";+  make "board"; make "board"; make "board";+  make "box";+  make "wooden gear"; make "wooden gear";+  make "harvester"+end++def get_lambda : cmd unit =+  m10; tR; m9; harvest; tB; m9; tL; m10+end++def solution : cmd unit =+  build {get_3_trees}; wait 16; salvage;+  make_harvester;+  build {get_lambda}; wait 50; salvage+end;++solution

@@ -31,16 +31,16 @@   - id: get_harvester     teaser: Make a harvester     goal:-      - Nice work!  Now, use the trees to make a harvester device.+      - Nice work!  Now, use the `tree`{=entity}s to make a `harvester`{=entity} device.         This will require several intermediate products; try making-        various things, and take a look at your available recipes (F3)+        various things, and take a look at your available recipes (**F3**)         and at the recipes listed for items in your inventory.  Of course,         you may end up needing some additional trees.     condition: |       try { as base {has "harvester"} } {return false}     prerequisite: get_trees   - goal:-      - Now that you have a harvester, you can use `harvest` instead of `grab`+      - Now that you have a `harvester`{=entity}, 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@@ -56,6 +56,8 @@     condition: |       try { as base {has "lambda"} } {return false}     prerequisite: get_harvester+solution: |+  run "scenarios/Tutorials/world101.sw" robots:   - name: base     display:

@@ -55,12 +55,15 @@                "selfdestruct"                "move"                "backup"+               "path"                "push"                "stride"                "turn"                "grab"                "harvest"+               "ignite"                "place"+               "ping"                "give"                "equip"                "unequip"

@@ -0,0 +1,8 @@+if vim.fn.executable('swarm') == 1 then+    vim.lsp.start({+        name = 'Swarm Language Server',+        cmd = { 'swarm', 'lsp' },+    })+end++

@@ -0,0 +1,24 @@+syn keyword Keyword def end let in require+syn keyword Builtins self parent base if inl inr case fst snd force undefined fail not format chars split charat tochar key+syn keyword Command noop wait selfdestruct move backup path push stride turn grab harvest ignite place ping give equip unequip make has equipped count drill use build salvage reprogram say listen log view appear create halt time scout whereami waypoint detect resonate density sniff chirp watch surveil heading blocked scan upload ishere isempty meet meetall whoami setname random run return try swap atomic instant installkeyhandler teleport as robotnamed robotnumbered knows+syn keyword Direction east north west south down forward left back right+syn keyword Type int text dir bool cmd void unit actor+++syn match Comment "//.*$"+syn region MultilineComment start="/\*" end="\*/"+syn match Brackets "[\[\]\(\)\{\}]"+syn match Colon ":"+syn match String "\".*\""+syn match Number "\<[-]\=\d\+\>"++hi def link Keyword Statement+hi def link Builtins Keyword+hi def link Command Function+hi def link Direction Function+hi def link Comment Comment+hi def link MultilineComment Comment+hi def link Brackets Keyword+hi def link Colon Keyword+hi def link String String +hi def link Number Number

@@ -58,7 +58,7 @@ 				}, 				{ 				"name": "keyword.other",-				"match": "\\b(?i)(self|parent|base|if|inl|inr|case|fst|snd|force|undefined|fail|not|format|chars|split|charat|tochar|key|noop|wait|selfdestruct|move|backup|push|stride|turn|grab|harvest|place|give|equip|unequip|make|has|equipped|count|drill|use|build|salvage|reprogram|say|listen|log|view|appear|create|halt|time|scout|whereami|waypoint|detect|resonate|density|sniff|chirp|watch|surveil|heading|blocked|scan|upload|ishere|isempty|meet|meetall|whoami|setname|random|run|return|try|swap|atomic|instant|installkeyhandler|teleport|as|robotnamed|robotnumbered|knows)\\b"+				"match": "\\b(?i)(self|parent|base|if|inl|inr|case|fst|snd|force|undefined|fail|not|format|chars|split|charat|tochar|key|noop|wait|selfdestruct|move|backup|path|push|stride|turn|grab|harvest|ignite|place|ping|give|equip|unequip|make|has|equipped|count|drill|use|build|salvage|reprogram|say|listen|log|view|appear|create|halt|time|scout|whereami|waypoint|detect|resonate|density|sniff|chirp|watch|surveil|heading|blocked|scan|upload|ishere|isempty|meet|meetall|whoami|setname|random|run|return|try|swap|atomic|instant|installkeyhandler|teleport|as|robotnamed|robotnumbered|knows)\\b" 				} 			] 			},

@@ -19,8 +19,8 @@ import Data.Text.IO qualified as T import Graphics.Vty qualified as V import Swarm.Game.Failure (SystemFailure)-import Swarm.Game.Robot (ErrorLevel (..), LogSource (ErrorTrace, Said)) import Swarm.Language.Pretty (prettyText)+import Swarm.Log (LogSource (SystemLog), Severity (..)) import Swarm.ReadableIORef (mkReadonly) import Swarm.TUI.Controller import Swarm.TUI.Model@@ -33,7 +33,8 @@  type EventHandler = BrickEvent Name AppEvent -> EventM Name AppState () --- | The definition of the app used by the @brick@ library.+-- | The configuration of the Swarm app which we pass to the @brick@+--   library. app :: EventHandler -> App AppState AppEvent Name app eventHandler =   App@@ -86,8 +87,8 @@           (mkReadonly appStateRef)           chan -      let logP p = logEvent Said ("Web API", -2) ("started on :" <> T.pack (show p))-      let logE e = logEvent (ErrorTrace Error) ("Web API", -2) (T.pack e)+      let logP p = logEvent SystemLog Info "Web API" ("started on :" <> T.pack (show p))+      let logE e = logEvent SystemLog Error "Web API" (T.pack e)       let s' =             s               & runtimeState@@ -110,7 +111,7 @@       void $ customMain initialVty buildVty (Just chan) (app eventHandler) s'  -- | A demo program to run the web service directly, without the terminal application.--- This is useful to live update the code using `ghcid -W --test "Swarm.App.demoWeb"`+--   This is useful to live update the code using @ghcid -W --test "Swarm.App.demoWeb"@. demoWeb :: IO () demoWeb = do   let demoPort = 8080

@@ -3,21 +3,25 @@ -- | -- SPDX-License-Identifier: BSD-3-Clause ----- Constants used throughout the UI and game+-- Constants used throughout the UI and game. module Swarm.Constant where  import Data.Text (Text)  -- * Website constants +-- $convention -- By convention, all URL constants include trailing slashes -- when applicable. +-- | The URL for the Swarm repository. swarmRepoUrl :: Text swarmRepoUrl = "https://github.com/swarm-game/swarm/" +-- | The URL for the Swarm wiki. wikiUrl :: Text wikiUrl = swarmRepoUrl <> "wiki/" +-- | The URL for the Swarm commands cheat sheet. wikiCheatSheet :: Text wikiCheatSheet = wikiUrl <> "Commands-Cheat-Sheet"

@@ -4,27 +4,28 @@  -- | -- SPDX-License-Identifier: BSD-3-Clause+--+-- Auto-generation of various forms of documentation. module Swarm.Doc.Gen (+  -- ** Main document generation function + types   generateDocs,   GenerateDocs (..),   EditorType (..),   SheetType (..),+  loadStandaloneScenario,    -- ** Formatted keyword lists   keywordsCommands,   keywordsDirections,   operatorNames,   builtinFunctionList,-  editorList,    -- ** Wiki pages   PageAddress (..),-  commandsPage,-  capabilityPage,-  noPageAddresses, ) where  import Control.Effect.Lift+import Control.Effect.Throw (Throw, throwError) import Control.Lens (view, (^.)) import Control.Lens.Combinators (to) import Control.Monad (zipWithM, zipWithM_)@@ -33,8 +34,7 @@ import Data.List (transpose) import Data.Map.Lazy (Map, (!)) import Data.Map.Lazy qualified as Map-import Data.Maybe (fromMaybe, isJust)-import Data.Sequence (Seq)+import Data.Maybe (fromMaybe, isJust, listToMaybe) import Data.Set (Set) import Data.Set qualified as Set import Data.Text (Text, unpack)@@ -42,15 +42,16 @@ import Data.Text.IO qualified as T import Data.Tuple (swap) import Swarm.Doc.Pedagogy+import Swarm.Doc.Schema.Render+import Swarm.Doc.Util import Swarm.Game.Display (displayChar) import Swarm.Game.Entity (Entity, EntityMap (entitiesByName), entityDisplay, entityName, loadEntities) import Swarm.Game.Entity qualified as E-import Swarm.Game.Failure (SystemFailure)-import Swarm.Game.Recipe (Recipe, loadRecipes, recipeInputs, recipeOutputs, recipeRequirements, recipeTime, recipeWeight)+import Swarm.Game.Failure (SystemFailure (CustomFailure))+import Swarm.Game.Recipe (Recipe, loadRecipes, recipeCatalysts, recipeInputs, recipeOutputs, recipeTime, recipeWeight) import Swarm.Game.Robot (Robot, equippedDevices, instantiateRobot, robotInventory)-import Swarm.Game.Scenario (Scenario, loadScenario, scenarioRobots)+import Swarm.Game.Scenario (Scenario, loadStandaloneScenario, scenarioRobots) import Swarm.Game.World.Gen (extractEntities)-import Swarm.Game.World.Load (loadWorlds) import Swarm.Game.World.Typecheck (Some (..), TTerm) import Swarm.Language.Capability (Capability) import Swarm.Language.Capability qualified as Capability@@ -61,7 +62,8 @@ import Swarm.Language.Text.Markdown as Markdown (docToMark) import Swarm.Language.Typecheck (inferConst) import Swarm.Util (both, listEnums, quote)-import Swarm.Util.Effect (ignoreWarnings, simpleErrorHandle)+import Swarm.Util.Effect (simpleErrorHandle)+import Swarm.Web (swarmApiMarkdown) import Text.Dot (Dot, NodeId, (.->.)) import Text.Dot qualified as Dot @@ -73,24 +75,33 @@ -- -- ---------------------------------------------------------------------------- +-- | An enumeration of the kinds of documentation we can generate. data GenerateDocs where   -- | Entity dependencies by recipes.   RecipeGraph :: GenerateDocs   -- | Keyword lists for editors.   EditorKeywords :: Maybe EditorType -> GenerateDocs-  -- | List of special key names recognized by 'key' command+  -- | List of special key names recognized by 'Swarm.Language.Syntax.Key' command   SpecialKeyNames :: GenerateDocs+  -- | Cheat sheets for inclusion on the Swarm wiki.   CheatSheet :: PageAddress -> Maybe SheetType -> GenerateDocs   -- | List command introductions by tutorial   TutorialCoverage :: GenerateDocs+  -- | Web API endpoints+  WebAPIEndpoints :: GenerateDocs   deriving (Eq, Show) -data EditorType = Emacs | VSCode+-- | An enumeration of the editors supported by Swarm (currently,+--   Emacs and VS Code).+data EditorType = Emacs | VSCode | Vim   deriving (Eq, Show, Enum, Bounded) -data SheetType = Entities | Commands | Capabilities | Recipes+-- | An enumeration of the kinds of cheat sheets we can produce.+data SheetType = Entities | Commands | Capabilities | Recipes | Scenario   deriving (Eq, Show, Enum, Bounded) +-- | A configuration record holding the URLs of the various cheat+--   sheets, to facilitate cross-linking. data PageAddress = PageAddress   { entityAddress :: Text   , commandsAddress :: Text@@ -99,9 +110,7 @@   }   deriving (Eq, Show) -noPageAddresses :: PageAddress-noPageAddresses = PageAddress "" "" "" ""-+-- | Generate the requested kind of documentation to stdout. generateDocs :: GenerateDocs -> IO () generateDocs = \case   RecipeGraph -> generateRecipe >>= putStrLn@@ -131,12 +140,16 @@         entities <- loadEntities         recipes <- loadRecipes entities         sendIO $ T.putStrLn $ recipePage address recipes+      Scenario -> genScenarioSchemaDocs   TutorialCoverage -> renderTutorialProgression >>= putStrLn . T.unpack+  WebAPIEndpoints -> putStrLn swarmApiMarkdown  -- ---------------------------------------------------------------------------- -- GENERATE KEYWORDS: LIST OF WORDS TO BE HIGHLIGHTED -- ---------------------------------------------------------------------------- +-- | Generate a list of keywords in the format expected by one of the+--   supported editors. generateEditorKeywords :: EditorType -> IO () generateEditorKeywords = \case   Emacs -> do@@ -153,6 +166,13 @@     T.putStrLn $ keywordsDirections VSCode     putStrLn "\nOperators:"     T.putStrLn operatorNames+  Vim -> do+    putStr "syn keyword Builtins "+    T.putStr $ builtinFunctionList Vim+    putStr "\nsyn keyword Command "+    T.putStr $ keywordsCommands Vim+    putStr "\nsyn keyword Direction "+    T.putStrLn $ keywordsDirections Vim  commands :: [Const] commands = filter Syntax.isCmd Syntax.allConst@@ -170,6 +190,7 @@ editorList = \case   Emacs -> T.unlines . map (("  " <>) . quote)   VSCode -> T.intercalate "|"+  Vim -> T.intercalate " "  constSyntax :: Const -> Text constSyntax = Syntax.syntax . Syntax.constInfo@@ -182,6 +203,7 @@ keywordsDirections :: EditorType -> Text keywordsDirections e = editorList e $ map Syntax.directionSyntax Syntax.allDirs +-- | A list of the names of all the operators in the language. operatorNames :: Text operatorNames = T.intercalate "|" $ map (escape . constSyntax) operators  where@@ -204,12 +226,6 @@ -- GENERATE TABLES: COMMANDS, ENTITIES AND CAPABILITIES TO MARKDOWN TABLE -- ---------------------------------------------------------------------------- -wrap :: Char -> Text -> Text-wrap c = T.cons c . flip T.snoc c--codeQuote :: Text -> Text-codeQuote = wrap '`'- escapeTable :: Text -> Text escapeTable = T.concatMap (\c -> if c == '|' then T.snoc "\\" c else T.singleton c) @@ -224,12 +240,6 @@ maxWidths :: [[Text]] -> [Int] maxWidths = map (maximum . map T.length) . transpose -addLink :: Text -> Text -> Text-addLink l t = T.concat ["[", t, "](", l, ")"]--tshow :: (Show a) => a -> Text-tshow = T.pack . show- -- --------- -- COMMANDS -- ---------@@ -391,7 +401,7 @@     escapeTable     [ T.intercalate ", " (map formatCE $ view recipeInputs r)     , T.intercalate ", " (map formatCE $ view recipeOutputs r)-    , T.intercalate ", " (map formatCE $ view recipeRequirements r)+    , T.intercalate ", " (map formatCE $ view recipeCatalysts r)     , tshow $ view recipeTime r     , tshow $ view recipeWeight r     ]@@ -412,20 +422,23 @@ recipePage :: PageAddress -> [Recipe Entity] -> Text recipePage = recipeTable +getBaseRobot :: Has (Throw SystemFailure) sig m => Scenario -> m Robot+getBaseRobot s = case listToMaybe $ view scenarioRobots s of+  Just r -> pure $ instantiateRobot 0 r+  Nothing -> throwError $ CustomFailure "Scenario contains no robots"+ -- ---------------------------------------------------------------------------- -- GENERATE GRAPHVIZ: ENTITY DEPENDENCIES BY RECIPES -- ----------------------------------------------------------------------------  generateRecipe :: IO String generateRecipe = simpleErrorHandle $ do-  entities <- loadEntities-  recipes <- loadRecipes entities-  worlds <- ignoreWarnings @(Seq SystemFailure) $ loadWorlds entities-  classic <- fst <$> loadScenario "data/scenarios/classic.yaml" entities worlds-  return . Dot.showDot $ recipesToDot classic (worlds ! "classic") entities recipes+  (classic, (worlds, entities, recipes)) <- loadStandaloneScenario "data/scenarios/classic.yaml"+  baseRobot <- getBaseRobot classic+  return . Dot.showDot $ recipesToDot baseRobot (worlds ! "classic") entities recipes -recipesToDot :: Scenario -> Some (TTerm '[]) -> EntityMap -> [Recipe Entity] -> Dot ()-recipesToDot classic classicTerm emap recipes = do+recipesToDot :: Robot -> Some (TTerm '[]) -> EntityMap -> [Recipe Entity] -> Dot ()+recipesToDot baseRobot classicTerm emap recipes = do   Dot.attribute ("rankdir", "LR")   Dot.attribute ("ranksep", "2")   world <- diamond "World"@@ -443,8 +456,8 @@   -- --------------------------------------------------------------------------   -- Get the starting inventories, entities present in the world and compute   -- how hard each entity is to get - see 'recipeLevels'.-  let devs = startingDevices classic-      inv = startingInventory classic+  let devs = startingDevices baseRobot+      inv = startingInventory baseRobot       worldEntities = case classicTerm of Some _ t -> extractEntities t       levels = recipeLevels recipes (Set.unions [worldEntities, devs])   -- --------------------------------------------------------------------------@@ -490,19 +503,19 @@   -- order entities into clusters based on how "far" they are from   -- what is available at the start - see 'recipeLevels'.   bottom <- wrapBelowAbove worldEntities-  ls <- zipWithM subLevel [1 ..] (tail levels)+  ls <- zipWithM subLevel [1 ..] (drop 1 levels)   let invisibleLine = zipWithM_ (.~>.)   tls <- mapM (const hiddenNode) levels   bls <- mapM (const hiddenNode) levels   invisibleLine tls bls-  invisibleLine bls (tail tls)+  invisibleLine bls (drop 1 tls)   let sameBelowAbove (b1, t1) (b2, t2) = Dot.same [b1, b2] >> Dot.same [t1, t2]   zipWithM_ sameBelowAbove (bottom : ls) (zip bls tls)   -- --------------------------------------------------------------------------   -- add node for the world and draw a line to each entity found in the wild   -- finally draw recipes   let recipeInOut r = [(snd i, snd o) | i <- r ^. recipeInputs, o <- r ^. recipeOutputs]-      recipeReqOut r = [(snd q, snd o) | q <- r ^. recipeRequirements, o <- r ^. recipeOutputs]+      recipeReqOut r = [(snd q, snd o) | q <- r ^. recipeCatalysts, o <- r ^. recipeOutputs]       recipesToPairs f rs = both nid <$> nubOrd (concatMap f rs)   mapM_ (uncurry (.->.)) (recipesToPairs recipeInOut recipes)   mapM_ (uncurry (---<>)) (recipesToPairs recipeReqOut recipes)@@ -526,7 +539,7 @@ recipeLevels :: [Recipe Entity] -> Set Entity -> [Set Entity] recipeLevels recipes start = levels  where-  recipeParts r = ((r ^. recipeInputs) <> (r ^. recipeRequirements), r ^. recipeOutputs)+  recipeParts r = ((r ^. recipeInputs) <> (r ^. recipeCatalysts), r ^. recipeOutputs)   m :: [(Set Entity, Set Entity)]   m = map (both (Set.fromList . map snd) . recipeParts) recipes   levels :: [Set Entity]@@ -540,14 +553,11 @@             then ls             else go (n : ls) (Set.union n known) -startingHelper :: Scenario -> Robot-startingHelper = instantiateRobot 0 . head . view scenarioRobots--startingDevices :: Scenario -> Set Entity-startingDevices = Set.fromList . map snd . E.elems . view equippedDevices . startingHelper+startingDevices :: Robot -> Set Entity+startingDevices = Set.fromList . map snd . E.elems . view equippedDevices -startingInventory :: Scenario -> Map Entity Int-startingInventory = Map.fromList . map swap . E.elems . view robotInventory . startingHelper+startingInventory :: Robot -> Map Entity Int+startingInventory = Map.fromList . map swap . E.elems . view robotInventory  -- | Ignore utility entities that are just used for tutorials and challenges. ignoredEntities :: Set Text

@@ -6,8 +6,9 @@ -- Assess pedagogical soundness of the tutorials. -- -- Approach:+-- -- 1. Obtain a list of all of the tutorial scenarios, in order--- 2. Search their "solution" code for `commands`+-- 2. Search their \"solution\" code for `commands` -- 3. "fold" over the tutorial list, noting which tutorial was first to introduce each command module Swarm.Doc.Pedagogy (   renderTutorialProgression,@@ -38,7 +39,7 @@ import Swarm.Language.Module (Module (..)) import Swarm.Language.Pipeline (ProcessedTerm (..)) import Swarm.Language.Syntax-import Swarm.Language.Text.Markdown (findCode)+import Swarm.Language.Text.Markdown (docToText, findCode) import Swarm.Language.Types (Polytype) import Swarm.TUI.Controller (getTutorials) import Swarm.Util.Effect (ignoreWarnings, simpleErrorHandle)@@ -174,7 +175,7 @@     intercalate       [""]       [ pure . surround "`" . T.pack $ view scenarioPath si-      , pure . surround "*" . T.strip $ view scenarioDescription s+      , pure . surround "*" . T.strip . docToText $ view scenarioDescription s       , renderSection "Introduced in solution" . renderCmdList $ M.keysSet novelCmds       , renderSection "Referenced in description" $ renderCmdList dCmds       ]@@ -211,6 +212,10 @@ renderCmdList :: Set Const -> [Text] renderCmdList = renderList . map linkifyCommand . cmdSetToSortedText +-- | Generate a document which lists all the tutorial scenarios,+--   highlighting for each one which commands are introduced for the+--   first time in the canonical solution, and which commands are+--   referenced in the tutorial description. renderTutorialProgression :: IO Text renderTutorialProgression =   processAndRender <$> loadScenarioCollection

@@ -0,0 +1,42 @@+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Graph-based heuristics for arranging the+-- order of sections in the schema docs+module Swarm.Doc.Schema.Arrangement (sortAndPruneSchemas) where++import Data.Graph+import Data.Set qualified as Set+import Swarm.Doc.Schema.Parse+import Swarm.Doc.Schema.Refined+import Swarm.Doc.Schema.SchemaType++-- | Sort the schemas in topological order.+--+-- Only includes schema files that are reachable from+-- the root schema+-- (i.e. exclude @entities.json@ and @recipes.json@,+-- which are used independently to validate @entities.yaml@+-- and @recipes.yaml@).+sortAndPruneSchemas ::+  SchemaIdReference ->+  [SchemaData] ->+  [SchemaData]+sortAndPruneSchemas rootSchemaKey schemas =+  reverse . flattenSCCs . stronglyConnComp $ reachableEdges+ where+  rawEdgeList = map getNodeEdgesEntry schemas+  (graph, _nodeFromVertex, vertexFromKey) = graphFromEdges rawEdgeList+  reachableVertices = Set.fromList $ maybe [] (reachable graph) $ vertexFromKey rootSchemaKey++  reachableEdges = filter f rawEdgeList+  f (_, k, _) = maybe False (`Set.member` reachableVertices) . vertexFromKey $ k++getNodeEdgesEntry ::+  SchemaData ->+  (SchemaData, SchemaIdReference, [SchemaIdReference])+getNodeEdgesEntry sd@(SchemaData fp schem _) =+  ( sd+  , fromFilePath fp+  , Set.toList $ extractReferences $ content schem+  )

@@ -0,0 +1,52 @@+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- There are no modern, comprehensive JSON Schema parsing+-- libraries in Haskell, as explained in+-- <this post https://dev.to/sshine/a-review-of-json-schema-libraries-for-haskell-321>.+--+-- Therefore, a bespoke parser for a small subset of JSON Schema is implemented here,+-- simply for rendering Markdown documentation from Swarm's schema.+module Swarm.Doc.Schema.Parse where++import Control.Applicative ((<|>))+import Data.Aeson+import Data.Map (Map)+import Data.Maybe (fromMaybe)+import Data.Text (Text)+import Swarm.Doc.Schema.Refined+import Text.Pandoc++-- | Includes everything needed to+-- render the schema to markdown+data SchemaData = SchemaData+  { schemaPath :: FilePath+  , schemaContent :: ToplevelSchema+  , markdownFooters :: [Pandoc]+  }++data Members+  = ObjectProperties (Map Text SwarmSchema)+  | ListMembers (ItemDescription SwarmSchema)+  deriving (Eq, Ord, Show)++data ToplevelSchema = ToplevelSchema+  { title :: Text+  , description :: Maybe Pandoc+  , content :: SwarmSchema+  , members :: Maybe Members+  , footerPaths :: [FilePath]+  }+  deriving (Eq, Ord, Show)++instance FromJSON ToplevelSchema where+  parseJSON x = do+    rawSchema :: rawSchema <- parseJSON x+    swarmSchema <- toSwarmSchema rawSchema++    theTitle <- maybe (fail "Schema requires a title") return $ _title rawSchema+    let theFooters = fromMaybe [] $ _footers rawSchema+        maybeMembers =+          ObjectProperties <$> properties swarmSchema+            <|> ListMembers <$> itemsDescription swarmSchema+    return $ ToplevelSchema theTitle (objectDescription swarmSchema) swarmSchema maybeMembers theFooters

@@ -0,0 +1,145 @@+{-# LANGUAGE OverloadedStrings #-}++-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Refined JSON schema after converting+-- all JSON Value types to their specific sum types+module Swarm.Doc.Schema.Refined where++import Control.Applicative ((<|>))+import Data.Aeson+import Data.List.Extra (replace)+import Data.Map (Map)+import Data.Map qualified as M+import Data.Maybe (fromMaybe, mapMaybe)+import Data.Set (Set)+import Data.Set qualified as Set+import Data.Text (Text)+import Data.Text qualified as T+import GHC.Generics (Generic)+import Swarm.Doc.Schema.SchemaType+import System.FilePath (takeBaseName)+import Text.Pandoc+import Text.Pandoc.Builder++-- * Basic++schemaJsonOptions :: Options+schemaJsonOptions =+  defaultOptions+    { fieldLabelModifier = replace "S" "$" . drop 1 -- drops leading underscore+    }++-- | A single record that encompasses all possible objects+-- in a JSON schema. All fields are optional.+data SchemaRaw = SchemaRaw+  { _description :: Maybe Text+  , _default :: Maybe Value+  , _title :: Maybe Text+  , _type :: Maybe (SingleOrList Text)+  , _name :: Maybe Text+  , _properties :: Maybe (Map Text SwarmSchema)+  , _items :: Maybe (ItemDescription SwarmSchema)+  , _examples :: Maybe [Value]+  , _Sref :: Maybe Text+  , _oneOf :: Maybe [SchemaRaw]+  , _footers :: Maybe [FilePath]+  , _additionalProperties :: Maybe Bool+  }+  deriving (Eq, Ord, Show, Generic)++instance FromJSON SchemaRaw where+  parseJSON = genericParseJSON schemaJsonOptions++extractSchemaType :: SchemaRaw -> Maybe SchemaType+extractSchemaType rawSchema =+  mkReference <$> _Sref rawSchema+    <|> getTypeFromItems+    <|> Simple <$> _type rawSchema+    <|> Alternatives . mapMaybe extractSchemaType <$> _oneOf rawSchema+ where+  mkReference = Reference . SchemaIdReference . T.pack . takeBaseName . T.unpack++  getTypeFromItems :: Maybe SchemaType+  getTypeFromItems = do+    itemsThing <- _items rawSchema+    case itemsThing of+      ItemList _ -> Nothing+      ItemType x -> Just $ ListOf $ schemaType x++-- * Refined++data ItemDescription a+  = ItemList [a]+  | ItemType a+  deriving (Eq, Ord, Show)++instance (FromJSON a) => FromJSON (ItemDescription a) where+  parseJSON x =+    ItemList <$> parseJSON x+      <|> ItemType <$> parseJSON x++getSchemaReferences :: SchemaType -> [SchemaIdReference]+getSchemaReferences = \case+  Simple _ -> []+  Alternatives xs -> concatMap getSchemaReferences xs+  Reference x -> pure x+  ListOf x -> getSchemaReferences x++-- | A subset of all JSON schemas, conforming to internal Swarm conventions.+--+-- Conveniently, this extra representation layer+-- is able to enforce (via 'toSwarmSchema') that all "object"+-- definitions in the schema contain the @"additionalProperties": true@ attribute.+data SwarmSchema = SwarmSchema+  { schemaType :: SchemaType+  , defaultValue :: Maybe Value+  , objectDescription :: Maybe Pandoc+  , properties :: Maybe (Map Text SwarmSchema)+  , itemsDescription :: Maybe (ItemDescription SwarmSchema)+  , examples :: [Value]+  }+  deriving (Eq, Ord, Show)++instance FromJSON SwarmSchema where+  parseJSON x = do+    rawSchema :: rawSchema <- parseJSON x+    toSwarmSchema rawSchema++getMarkdown :: MonadFail m => Text -> m Pandoc+getMarkdown desc = case runPure (readMarkdown def desc) of+  Right d -> return d+  Left err -> fail $ T.unpack $ renderError err++toSwarmSchema :: MonadFail m => SchemaRaw -> m SwarmSchema+toSwarmSchema rawSchema = do+  theType <- maybe (fail "Unspecified sub-schema type") return maybeType+  markdownDescription <- mapM getMarkdown $ _description rawSchema++  if null (_properties rawSchema) || not (fromMaybe True (_additionalProperties rawSchema))+    then return ()+    else fail "All objects must specify '\"additionalProperties\": true'"++  return+    SwarmSchema+      { schemaType = theType+      , defaultValue = _default rawSchema+      , objectDescription = markdownDescription <|> doc . plain . text <$> _name rawSchema+      , examples = fromMaybe [] $ _examples rawSchema+      , properties = _properties rawSchema+      , itemsDescription = _items rawSchema+      }+ where+  maybeType = extractSchemaType rawSchema++-- * Utilities++-- | Recursively extract references to other schemas+extractReferences :: SwarmSchema -> Set SchemaIdReference+extractReferences s = thisRefList <> otherRefLists+ where+  thisRefList = Set.fromList . getSchemaReferences $ schemaType s++  otherSchemas = maybe [] M.elems $ properties s+  otherRefLists = Set.unions $ map extractReferences otherSchemas

@@ -0,0 +1,194 @@+{-# LANGUAGE OverloadedStrings #-}++-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Render a markdown document fragment+-- from the Scenario JSON schema files.+module Swarm.Doc.Schema.Render where++import Control.Arrow (left, (&&&))+import Control.Monad.Except (runExceptT)+import Control.Monad.IO.Class (liftIO)+import Control.Monad.Trans.Except (except)+import Data.Aeson+import Data.List (intersperse)+import Data.Map (Map)+import Data.Map.Strict qualified as M+import Data.Maybe (fromMaybe)+import Data.Scientific (FPFormat (..), Scientific, formatScientific)+import Data.Text qualified as T+import Data.Text.IO qualified as TIO+import Data.Vector qualified as V+import Swarm.Doc.Schema.Arrangement+import Swarm.Doc.Schema.Parse+import Swarm.Doc.Schema.Refined+import Swarm.Doc.Schema.SchemaType+import Swarm.Doc.Util+import Swarm.Util (applyWhen, brackets, quote, showT)+import System.Directory (listDirectory)+import System.FilePath (splitExtension, (<.>), (</>))+import Text.Pandoc+import Text.Pandoc.Builder+import Text.Pandoc.Walk (query)++scenariosDir :: FilePath+scenariosDir = "data/scenarios"++docFragmentsDir :: FilePath+docFragmentsDir = scenariosDir </> "doc-fragments"++schemasDir :: FilePath+schemasDir = "data/schema"++schemaExtension :: String+schemaExtension = ".json"++propertyColumnHeadings :: [T.Text]+propertyColumnHeadings =+  [ "Key"+  , "Default?"+  , "Type"+  , "Description"+  ]++listColumnHeadings :: [T.Text]+listColumnHeadings =+  [ "Index"+  , "Type"+  , "Description"+  ]++makeTitleMap :: [SchemaData] -> Map SchemaIdReference T.Text+makeTitleMap = M.fromList . map (fromFilePath . schemaPath &&& title . schemaContent)++makePandocTable :: Map SchemaIdReference T.Text -> SchemaData -> Pandoc+makePandocTable titleMap (SchemaData _ (ToplevelSchema theTitle theDescription _schema theMembers _) parsedFooters) =+  setTitle (text "JSON Schema for Scenarios") $+    doc (header 3 (text theTitle))+      <> fromMaybe mempty theDescription+      <> maybe mempty mkTable theMembers+      <> mconcat parsedFooters+ where+  renderItems someStuff = case someStuff of+    ItemType x -> plain $ text "List of " <> listToText titleMap (schemaType x)+    ItemList xs ->+      makePropsTable False listColumnHeadings titleMap+        . M.fromList+        $ zip (map tshow [0 :: Int ..]) xs++  mkTable x = doc $ case x of+    ObjectProperties props -> makePropsTable True propertyColumnHeadings titleMap props+    ListMembers someStuff -> renderItems someStuff++genPropsRow :: Bool -> Map SchemaIdReference T.Text -> (T.Text, SwarmSchema) -> [Blocks]+genPropsRow includeDefaultColumn titleMap (k, x) =+  firstColumn : applyWhen includeDefaultColumn (defaultColumn :) tailColumns+ where+  firstColumn = plain $ code k+  defaultColumn = maybe mempty (plain . code . renderValue) $ defaultValue x+  tailColumns =+    [ plain . listToText titleMap $ schemaType x+    , fromList $ maybe [] (query id) $ objectDescription x+    ]++makePropsTable ::+  Bool ->+  [T.Text] ->+  Map SchemaIdReference T.Text ->+  Map T.Text SwarmSchema ->+  Blocks+makePropsTable includeDefaultColumn headingsList titleMap =+  simpleTable headerRow . map (genPropsRow includeDefaultColumn titleMap) . M.toList+ where+  headerRow = map (plain . text) headingsList++type FileStemAndExtension = (FilePath, String)++recombineExtension :: FileStemAndExtension -> FilePath+recombineExtension (filenameStem, fileExtension) =+  filenameStem <.> fileExtension++genMarkdown :: [SchemaData] -> Either T.Text T.Text+genMarkdown schemaThings =+  left renderError $+    runPure $+      writeMarkdown (def {writerExtensions = extensionsFromList [Ext_pipe_tables]}) pd+ where+  titleMap = makeTitleMap schemaThings+  pd =+    mconcat $+      map (makePandocTable titleMap) $+        sortAndPruneSchemas (fromFilePath "scenario") schemaThings++parseSchemaFile :: FileStemAndExtension -> IO (Either T.Text ToplevelSchema)+parseSchemaFile stemAndExtension =+  left (prependPath . T.pack) <$> eitherDecodeFileStrict fullPath+ where+  prependPath = ((T.unwords ["in", quote (T.pack filename)] <> ": ") <>)+  filename = recombineExtension stemAndExtension+  fullPath = schemasDir </> filename++loadFooterContent :: (FilePath, ToplevelSchema) -> IO SchemaData+loadFooterContent (fp, schem) = do+  xs <- mapM (TIO.readFile . (scenariosDir </>)) $ footerPaths schem+  parsedFooters <- mapM getMarkdown xs+  return $+    SchemaData+      fp+      schem+      parsedFooters++genScenarioSchemaDocs :: IO ()+genScenarioSchemaDocs = do+  dirContents <- listDirectory schemasDir+  let inputFiles = filter ((== schemaExtension) . snd) $ map splitExtension dirContents+  xs <- mapM (sequenceA . (recombineExtension &&& parseSchemaFile)) inputFiles++  result <- runExceptT $ do+    schemaTuples <- except $ traverse sequenceA xs+    things <- liftIO $ mapM loadFooterContent schemaTuples+    myMarkdown <- except $ genMarkdown things+    docHeader <- liftIO $ TIO.readFile "data/scenarios/doc-fragments/header.md"+    liftIO . writeFile (docFragmentsDir </> "SCHEMA.md") . T.unpack $ docHeader <> myMarkdown++  case result of+    Left e -> print $ unwords ["Failed:", T.unpack e]+    Right _ -> return ()++renderValue :: Value -> T.Text+renderValue = \case+  Object obj -> showT obj+  Array arr -> brackets . T.intercalate ", " . map renderValue $ V.toList arr+  String t -> quote t+  Number num -> T.pack $ formatNumberCompact num+  Bool b -> showT b+  Null -> "null"++fragmentHref :: Map SchemaIdReference T.Text -> SchemaIdReference -> T.Text+fragmentHref titleMap r@(SchemaIdReference ref) =+  T.cons '#' . T.toLower . T.replace " " "-" $ x+ where+  x = M.findWithDefault ref r titleMap++listToText :: Map SchemaIdReference T.Text -> SchemaType -> Inlines+listToText titleMap = \case+  Simple xs -> renderAlternatives $ map code $ getList xs+  Alternatives xs -> renderAlternatives $ map (listToText titleMap) xs+  Reference r@(SchemaIdReference x) -> schemaLink r x+  ListOf x -> listToText titleMap x <> text " list"+ where+  renderAlternatives = mconcat . intersperse (text " or ")+  schemaLink r = link (fragmentHref titleMap r) "Link to object properties" . text++-- |+-- Strips trailing zeros and decimal point from a floating-point number+-- when possible.+--+-- Obtained from here: https://stackoverflow.com/a/35980995/105137+formatNumberCompact :: Scientific -> String+formatNumberCompact v+  | v == 0 = "0"+  | abs v < 1e-5 || abs v > 1e10 = formatScientific Exponent Nothing v+  | v - fromIntegral (floor v :: Integer) == 0 = formatScientific Fixed (Just 0) v+  | otherwise = formatScientific Generic Nothing v

@@ -0,0 +1,38 @@+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Representation of the "type" of a schema.+module Swarm.Doc.Schema.SchemaType where++import Control.Applicative ((<|>))+import Data.Aeson+import Data.Text (Text)+import Data.Text qualified as T+import System.FilePath (takeBaseName)++newtype SingleOrList a = SingleOrList+  { getList :: [a]+  }+  deriving (Eq, Ord, Show)++instance (FromJSON a) => FromJSON (SingleOrList a) where+  parseJSON x =+    fmap SingleOrList $+      pure <$> parseJSON x <|> parseJSON x++data SchemaType+  = -- | A basic built-in type+    Simple (SingleOrList Text)+  | -- | Any one of multiple possible schema types+    Alternatives [SchemaType]+  | -- | A reference to a schema defined elsewhere+    Reference SchemaIdReference+  | -- | Members of a list, all of the given schema type+    ListOf SchemaType+  deriving (Eq, Ord, Show)++newtype SchemaIdReference = SchemaIdReference Text+  deriving (Eq, Ord, Show)++fromFilePath :: FilePath -> SchemaIdReference+fromFilePath = SchemaIdReference . T.pack . takeBaseName

@@ -0,0 +1,22 @@+{-# LANGUAGE OverloadedStrings #-}++-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Utilities for generating doc markup+module Swarm.Doc.Util where++import Data.Text (Text)+import Data.Text qualified as T++wrap :: Char -> Text -> Text+wrap c = T.cons c . flip T.snoc c++codeQuote :: Text -> Text+codeQuote = wrap '`'++addLink :: Text -> Text -> Text+addLink l t = T.concat ["[", t, "](", l, ")"]++tshow :: (Show a) => a -> Text+tshow = T.pack . show

@@ -3,8 +3,13 @@ -- | -- SPDX-License-Identifier: BSD-3-Clause ----- Metadata about achievements that the player has obtained-module Swarm.Game.Achievement.Attainment where+-- Metadata about achievements that the player has obtained.+module Swarm.Game.Achievement.Attainment (+  Attainment (..),+  achievement,+  maybeScenarioPath,+  obtainedAt,+) where  import Control.Lens hiding (from, (<.>)) import Data.Aeson (@@ -19,11 +24,16 @@ import GHC.Generics (Generic) import Swarm.Game.Achievement.Definitions +-- | A record holding an achievement along with some metadata to+--   record the time at which the achievement was obtained, and the+--   scenario in which it was achieved. data Attainment = Attainment   { _achievement :: CategorizedAchievement+  -- ^ The achievement.   , _maybeScenarioPath :: Maybe FilePath-  -- ^ from which scenario was it obtained?+  -- ^ From which scenario was it obtained?   , _obtainedAt :: ZonedTime+  -- ^ What time was it obtained?   }   deriving (Generic) @@ -47,5 +57,5 @@ achievementJsonOptions :: Options achievementJsonOptions =   defaultOptions-    { fieldLabelModifier = tail -- drops leading underscore+    { fieldLabelModifier = drop 1 -- drops leading underscore     }

@@ -2,13 +2,28 @@ -- SPDX-License-Identifier: BSD-3-Clause -- -- Definitions of all possible achievements.-module Swarm.Game.Achievement.Definitions where+module Swarm.Game.Achievement.Definitions (+  -- * Achievements+  CategorizedAchievement (..),+  GlobalAchievement (..),+  GameplayAchievement (..),+  listAchievements, +  -- * Achievement info+  ExpectedEffort (..),+  Quotation (..),+  FlavorText (..),+  AchievementInfo (..),+) where+ import Data.Aeson import Data.Text (Text) import GHC.Generics (Generic)+import Swarm.Language.Syntax (Syntax)+import Swarm.Language.Text.Markdown (Document) import Swarm.Util +-- | How hard do we expect the achievement to be? data ExpectedEffort   = Trivial   | Easy@@ -16,20 +31,27 @@   | Gruelling   deriving (Eq, Ord, Show, Bounded, Enum, Generic, FromJSON, ToJSON) +-- | A quotation to spice up the description of an achievement. data Quotation = Quotation   { attribution :: Text   , content :: Text   }   deriving (Eq, Show, Generic, FromJSON, ToJSON) +-- | Flavor text to spice up the description of an achievement, either+--   freeform text or a quotation. data FlavorText-  = Freeform Text+  = Freeform (Document Syntax)   | FTQuotation Quotation   deriving (Eq, Show, Generic, FromJSON, ToJSON) +-- | Information about an achievement.  See+--   "Swarm.Game.Achievement.Description" for a mapping from+--   achievements to an corresponding 'AchievementInfo' record. data AchievementInfo = AchievementInfo   { title :: Text   -- ^ Guidelines:+  --   -- * prefer puns, pop culture references, etc.   -- * should be a phrase in Title Case.   -- * For achievements that are "obfuscated", this can be@@ -38,15 +60,17 @@   -- ^ Explain the reference, e.g. in the form of a full quote   -- from a movie, or something you might find   -- in a fortune cookie-  , attainmentProcess :: Text+  , attainmentProcess :: Document Syntax   -- ^ Precisely what must be done to obtain this achievement.   , effort :: ExpectedEffort+  -- ^ How hard the achievement is expected to be.   , isObfuscated :: Bool   -- ^ Hides the attainment process until after the achievement is attained.-  -- Best when the title + elaboration constitute a good clue.+  --   Best when the title + elaboration constitute a good clue.   }   deriving (Eq, Show, Generic, FromJSON, ToJSON) +-- | An achievement, categorized as either global or gameplay. data CategorizedAchievement   = GlobalAchievement GlobalAchievement   | GameplayAchievement GameplayAchievement@@ -64,8 +88,8 @@ instance FromJSON CategorizedAchievement where   parseJSON = genericParseJSON categorizedAchievementJsonOptions --- | Achievements that entail some aggregate of actions--- across scenarios+-- | Achievements that entail some aggregate of actions across+--   scenarios, or are independent of any particular scenario. data GlobalAchievement   = CompletedSingleTutorial   | CompletedAllTutorials@@ -75,7 +99,7 @@ instance FromJSON GlobalAchievement instance ToJSON GlobalAchievement --- | Achievements obtained while playing a single scenario+-- | Achievements obtained while playing a single scenario. data GameplayAchievement   = CraftedBitcoin   | RobotIntoWater@@ -83,11 +107,13 @@   | DestroyedBase   | LoseScenario   | GetDisoriented+  | SwapSame   deriving (Eq, Ord, Show, Bounded, Enum, Generic)  instance FromJSON GameplayAchievement instance ToJSON GameplayAchievement +-- | List of all possible achievements. listAchievements :: [CategorizedAchievement] listAchievements =   map GlobalAchievement listEnums

@@ -8,79 +8,90 @@  import Swarm.Game.Achievement.Definitions +-- | Function mapping each 'CategorizedAchievement' to an appropriate+--   'AchievementInfo' record.  This function must be updated whenever+--   a new type of achievement is added. describe :: CategorizedAchievement -> AchievementInfo-describe (GlobalAchievement CompletedSingleTutorial) =-  AchievementInfo-    "Welcome Freshmen"-    (Just $ Freeform "School is in session!")-    "Complete one of the tutorials."-    Easy-    False-describe (GlobalAchievement CompletedAllTutorials) =-  AchievementInfo-    "Autodidact"-    ( Just $-        FTQuotation $-          Quotation-            "Terry Pratchet"-            "I didn't go to university... But I have sympathy for those who did."-    )-    "Complete all of the tutorials."-    Moderate-    False-describe (GlobalAchievement LookedAtAboutScreen) =-  AchievementInfo-    "About time!"-    Nothing-    "View the About screen."-    Trivial-    True-describe (GameplayAchievement CraftedBitcoin) =-  -- Bitcoin is the deepest level of the recipes-  -- hierarchy.-  AchievementInfo-    "Master of Your Craft"-    Nothing-    "Make a Bitcoin"-    Moderate-    True-describe (GameplayAchievement RobotIntoWater) =-  AchievementInfo-    "Watery Grave"-    (Just $ Freeform "This little robot thinks he's a submarine.")-    "Destroy a robot by sending it into the water."-    Easy-    True-describe (GameplayAchievement AttemptSelfDestructBase) =-  AchievementInfo-    "Call of the Void"-    (Just $ Freeform "What does that big red button do?")-    "Attempt to self-destruct your base."-    Easy-    True-describe (GameplayAchievement DestroyedBase) =-  AchievementInfo-    "That Could Have Gone Better"-    (Just $ Freeform "Boom.")-    "Actually destroy your base."-    Moderate-    True-describe (GameplayAchievement LoseScenario) =-  AchievementInfo-    "Silver Lining"-    (Just $ Freeform "Here's your consolation prize.")-    "Lose at a scenario."-    Easy-    True-describe (GameplayAchievement GetDisoriented) =-  AchievementInfo-    "Playing Ostrich"-    ( Just $-        FTQuotation $-          Quotation-            "Lil Jon"-            "Fire up that loud / Another round of shots / Turn down for what?"-    )-    "'turn down' without a compass. Congratulations, you are 'disoriented'. How are you supposed to move now?"-    Easy-    True+describe = \case+  GlobalAchievement CompletedSingleTutorial ->+    AchievementInfo+      "Welcome Freshmen"+      (Just $ Freeform "School is in session!")+      "Complete one of the tutorials."+      Easy+      False+  GlobalAchievement CompletedAllTutorials ->+    AchievementInfo+      "Autodidact"+      ( Just $+          FTQuotation $+            Quotation+              "Terry Pratchet"+              "I didn't go to university... But I have sympathy for those who did."+      )+      "Complete all of the tutorials."+      Moderate+      False+  GlobalAchievement LookedAtAboutScreen ->+    AchievementInfo+      "About time!"+      Nothing+      "View the About screen."+      Trivial+      True+  GameplayAchievement CraftedBitcoin ->+    -- Bitcoin is the deepest level of the recipes+    -- hierarchy.+    AchievementInfo+      "Master of Your Craft"+      Nothing+      "Make a Bitcoin"+      Moderate+      True+  GameplayAchievement RobotIntoWater ->+    AchievementInfo+      "Watery Grave"+      (Just $ Freeform "This little robot thinks he's a submarine.")+      "Destroy a robot by sending it into the water."+      Easy+      True+  GameplayAchievement AttemptSelfDestructBase ->+    AchievementInfo+      "Call of the Void"+      (Just $ Freeform "What does that big red button do?")+      "Attempt to self-destruct your base."+      Easy+      True+  GameplayAchievement DestroyedBase ->+    AchievementInfo+      "That Could Have Gone Better"+      (Just $ Freeform "Boom.")+      "Actually destroy your base."+      Moderate+      True+  GameplayAchievement LoseScenario ->+    AchievementInfo+      "Silver Lining"+      (Just $ Freeform "Here's your consolation prize.")+      "Lose at a scenario."+      Easy+      True+  GameplayAchievement GetDisoriented ->+    AchievementInfo+      "Playing Ostrich"+      ( Just $+          FTQuotation $+            Quotation+              "Lil Jon"+              "Fire up that loud / Another round of shots / Turn down for what?"+      )+      "`turn down` without a compass. Congratulations, you are \"disoriented\". How are you supposed to move now?"+      Easy+      True+  GameplayAchievement SwapSame ->+    AchievementInfo+      "Fair Trade"+      (Just $ Freeform "The *Law of Equivalent Exchange*... taken literally.")+      "`swap` an item for itself."+      Easy+      True

@@ -4,6 +4,8 @@ -- SPDX-License-Identifier: BSD-3-Clause -- -- Load/save logic for achievements.+-- Each achievement is saved to its own file to better+-- support forward-compatibility. module Swarm.Game.Achievement.Persistence where  import Control.Arrow (left)@@ -16,17 +18,18 @@ import Swarm.Game.Achievement.Definitions import Swarm.Game.Failure import Swarm.Game.ResourceLoading (getSwarmXdgDataSubdir)-import Swarm.Util.Effect (forMW, warn)+import Swarm.Util.Effect (forMW) import System.Directory (doesDirectoryExist, doesFileExist, listDirectory) import System.FilePath ((</>)) --- | Get path to swarm achievements, optionally creating necessary---   directories.+-- | Get a path to the directory where achievement records are+--   stored. If the argument is set to @True@, create the directory if+--   it does not exist. getSwarmAchievementsPath :: Bool -> IO FilePath getSwarmAchievementsPath createDirs = getSwarmXdgDataSubdir createDirs "achievement"  -- | Load saved info about achievements from XDG data directory.--- Returns a tuple of warnings and attained achievements.+--   Returns a list of attained achievements. loadAchievementsInfo ::   (Has (Accum (Seq SystemFailure)) sig m, Has (Lift IO) sig m) =>   m [Attainment]@@ -45,7 +48,6 @@             return $ left (AssetNotLoaded Achievement p . CanNotParseYaml) eitherDecodedFile           else return . Left $ AssetNotLoaded Achievement p (EntryNot File)     else do-      warn $ AssetNotLoaded Achievement "." $ DoesNotExist Directory       return []  -- | Save info about achievements to XDG data directory.

@@ -53,8 +53,6 @@   Cont,    -- ** Wrappers for creating delayed change of state--  --    See 'FImmediate'.   WorldUpdate (..),   RobotUpdate (..), @@ -62,10 +60,10 @@   Store,   Addr,   emptyStore,-  Cell (..),+  MemCell (..),   allocate,-  lookupCell,-  setCell,+  lookupStore,+  setStore,    -- * CESK machine states   CESK (..),@@ -85,6 +83,7 @@ import Control.Lens ((^.)) import Control.Lens.Combinators (pattern Empty) import Data.Aeson (FromJSON, ToJSON)+import Data.Int (Int64) import Data.IntMap.Strict (IntMap) import Data.IntMap.Strict qualified as IM import GHC.Generics (Generic)@@ -100,13 +99,20 @@ import Swarm.Language.Syntax import Swarm.Language.Types import Swarm.Language.Value as V+import Swarm.Util.WindowedCounter (Offsettable (..)) -newtype TickNumber = TickNumber {getTickNumber :: Integer}+-- | A newtype representing a count of ticks (typically since the+--   start of a game).+newtype TickNumber = TickNumber {getTickNumber :: Int64}   deriving (Eq, Ord, Show, Read, Generic, FromJSON, ToJSON) -addTicks :: Integer -> TickNumber -> TickNumber-addTicks i (TickNumber n) = TickNumber $ n + i+-- | Add an offset to a 'TickNumber'.+addTicks :: Int -> TickNumber -> TickNumber+addTicks i (TickNumber n) = TickNumber $ n + fromIntegral i +instance Offsettable TickNumber where+  offsetBy = addTicks+ instance Pretty TickNumber where   pretty (TickNumber i) = pretty i @@ -184,7 +190,7 @@     --   already been evaluated; we are focusing on evaluating one     --   field; and some fields have yet to be evaluated.     FRcd Env [(Var, Value)] Var [(Var, Maybe Term)]-  | -- | We are in the middle of evaluating a record field projection.(:*:)+  | -- | We are in the middle of evaluating a record field projection.     FProj Var   deriving (Eq, Show, Generic, FromJSON, ToJSON) @@ -197,11 +203,13 @@  type Addr = Int --- | 'Store' represents a store, indexing integer locations to 'Cell's.-data Store = Store {next :: Addr, mu :: IntMap Cell} deriving (Show, Eq, Generic, FromJSON, ToJSON)+-- | 'Store' represents a store, /i.e./ memory, indexing integer+--   locations to 'MemCell's.+data Store = Store {next :: Addr, mu :: IntMap MemCell}+  deriving (Show, Eq, Generic, FromJSON, ToJSON)  -- | A memory cell can be in one of three states.-data Cell+data MemCell   = -- | A cell starts out life as an unevaluated term together with     --   its environment.     E Term Env@@ -219,7 +227,7 @@     --   'Blackhole' can be reset to 'E'.     Blackhole Term Env   | -- | Once evaluation is complete, we cache the final 'Value' in-    --   the 'Cell', so that subsequent lookups can just use it+    --   the 'MemCell', so that subsequent lookups can just use it     --   without recomputing anything.     V Value   deriving (Show, Eq, Generic, FromJSON, ToJSON)@@ -234,19 +242,19 @@ allocate e t (Store n m) = (n, Store (n + 1) (IM.insert n (E t e) m))  -- | Look up the cell at a given index.-lookupCell :: Addr -> Store -> Maybe Cell-lookupCell n = IM.lookup n . mu+lookupStore :: Addr -> Store -> Maybe MemCell+lookupStore n = IM.lookup n . mu  -- | Set the cell at a given index.-setCell :: Addr -> Cell -> Store -> Store-setCell n c (Store nxt m) = Store nxt (IM.insert n c m)+setStore :: Addr -> MemCell -> Store -> Store+setStore n c (Store nxt m) = Store nxt (IM.insert n c m)  ------------------------------------------------------------ -- CESK machine ------------------------------------------------------------  -- | The overall state of a CESK machine, which can actually be one of---   three kinds of states. The CESK machine is named after the first+--   four kinds of states. The CESK machine is named after the first --   kind of state, and it would probably be possible to inline a --   bunch of things and get rid of the second state, but I find it --   much more natural and elegant this way.  Most tutorial@@ -405,14 +413,17 @@ -- Runtime robot update -------------------------------------------------------------- --- | Update the robot in an inspectable way.------ This type is used for changes by e.g. the drill command at later--- tick. Using ADT allows us to serialize and inspect the updates.+-- | Enumeration of robot updates.  This type is used for changes by+--   /e.g./ the @drill@ command which must be carried out at a later+--   tick. Using a first-order representation (as opposed to /e.g./+--   just a @Robot -> Robot@ function) allows us to serialize and+--   inspect the updates. ----- Note that this can not be in 'Swarm.Game.Robot' as it would create--- a cyclic dependency.+--   Note that this can not be in 'Swarm.Game.Robot' as it would create+--   a cyclic dependency. data RobotUpdate-  = AddEntity Count Entity-  | LearnEntity Entity+  = -- | Add copies of an entity to the robot's inventory.+    AddEntity Count Entity+  | -- | Make the robot learn about an entity.+    LearnEntity Entity   deriving (Eq, Ord, Show, Generic, FromJSON, ToJSON)

@@ -13,16 +13,19 @@ -- are mutually recursive (an inventory contains entities, which can -- have inventories). module Swarm.Game.Entity (-  -- * Properties+  -- * Entity properties+  EntityName,   EntityProperty (..),   GrowthTime (..),   defaultGrowthTime,+  Combustibility (..),+  defaultCombustibility,    -- * Entities   Entity,   mkEntity, -  -- ** Lenses+  -- ** Fields   -- $lenses   entityDisplay,   entityName,@@ -31,6 +34,7 @@   entityDescription,   entityOrientation,   entityGrowth,+  entityCombustion,   entityYields,   entityProperties,   hasProperty,@@ -122,6 +126,10 @@ -- Properties ------------------------------------------------------------ +-- | A type representing entity names, currently a synonym for 'Text'.+--   In the future it is conceivable that it might become more complex.+type EntityName = Text+ -- | Various properties that an entity can have, which affect how --   robots can interact with it. data EntityProperty@@ -133,6 +141,9 @@     Opaque   | -- | Regrows from a seed after it is harvested.     Growable+  | -- | Can burn when ignited (either via 'Swarm.Language.Syntax.Ignite' or by+    --   an adjacent burning entity).+    Combustible   | -- | Regenerates infinitely when grabbed or harvested.     Infinite   | -- | Robots drown if they walk on this without a boat.@@ -159,9 +170,34 @@ newtype GrowthTime = GrowthTime (Integer, Integer)   deriving (Eq, Ord, Show, Read, Generic, Hashable, FromJSON, ToJSON) +-- | The default growth time (100, 200) for a growable entity with no+--   growth time specification. defaultGrowthTime :: GrowthTime defaultGrowthTime = GrowthTime (100, 200) +-- | Properties of combustion.+data Combustibility = Combustibility+  { ignition :: Double+  -- ^ Rate of ignition by a neighbor, per tick.+  --   If this rate is denoted \(\lambda\), the probability of+  --   ignition over a period of \(t\) ticks is \(1 - e^{-\lambda t}\).+  --   See <https://math.stackexchange.com/a/1243629>.+  , duration :: (Integer, Integer)+  -- ^ min and max tick counts for combustion to persist+  , product :: Maybe EntityName+  -- ^ what entity, if any, is left over after combustion+  }+  deriving (Eq, Ord, Show, Read, Generic, Hashable, FromJSON, ToJSON)++-- | The default combustion specification for a combustible entity+--   with no combustion specification:+--+--   * ignition rate 0.5+--   * duration (100, 200)+--   * product @ash@+defaultCombustibility :: Combustibility+defaultCombustibility = Combustibility 0.5 (100, 200) (Just "ash")+ ------------------------------------------------------------ -- Entity ------------------------------------------------------------@@ -210,7 +246,7 @@   -- ^ A hash value computed from the other fields   , _entityDisplay :: Display   -- ^ The way this entity should be displayed on the world map.-  , _entityName :: Text+  , _entityName :: EntityName   -- ^ The name of the entity, used /e.g./ in an inventory display.   , _entityPlural :: Maybe Text   -- ^ The plural of the entity name, in case it is irregular.  If@@ -224,6 +260,8 @@   --   a robot moves, it moves in the direction of its orientation.   , _entityGrowth :: Maybe GrowthTime   -- ^ If this entity grows, how long does it take?+  , _entityCombustion :: Maybe Combustibility+  -- ^ If this entity is combustible, how spreadable is it?   , _entityYields :: Maybe Text   -- ^ The name of a different entity obtained when this entity is   -- grabbed.@@ -243,7 +281,7 @@ -- | The @Hashable@ instance for @Entity@ ignores the cached hash --   value and simply combines the other fields. instance Hashable Entity where-  hashWithSalt s (Entity _ disp nm pl descr orient grow yld props caps inv) =+  hashWithSalt s (Entity _ disp nm pl descr orient grow combust yld props caps inv) =     s       `hashWithSalt` disp       `hashWithSalt` nm@@ -251,6 +289,7 @@       `hashWithSalt` docToText descr       `hashWithSalt` orient       `hashWithSalt` grow+      `hashWithSalt` combust       `hashWithSalt` yld       `hashWithSalt` props       `hashWithSalt` caps@@ -284,7 +323,20 @@   [Capability] ->   Entity mkEntity disp nm descr props caps =-  rehashEntity $ Entity 0 disp nm Nothing descr Nothing Nothing Nothing (Set.fromList props) (Set.fromList caps) empty+  rehashEntity $+    Entity+      0+      disp+      nm+      Nothing+      descr+      Nothing+      Nothing+      Nothing+      Nothing+      (Set.fromList props)+      (Set.fromList caps)+      empty  ------------------------------------------------------------ -- Entity map@@ -345,6 +397,7 @@               <*> (v .: "description")               <*> v .:? "orientation"               <*> v .:? "growth"+              <*> v .:? "combustion"               <*> v .:? "yields"               <*> v .:? "properties" .!= mempty               <*> v .:? "capabilities" .!= mempty@@ -413,7 +466,7 @@ entityDisplay = hashedLens _entityDisplay (\e x -> e {_entityDisplay = x})  -- | The name of the entity.-entityName :: Lens' Entity Text+entityName :: Lens' Entity EntityName entityName = hashedLens _entityName (\e x -> e {_entityName = x})  -- | The irregular plural version of the entity's name, if there is@@ -445,6 +498,10 @@ entityGrowth :: Lens' Entity (Maybe GrowthTime) entityGrowth = hashedLens _entityGrowth (\e x -> e {_entityGrowth = x}) +-- | Susceptibility to and duration of combustion+entityCombustion :: Lens' Entity (Maybe Combustibility)+entityCombustion = hashedLens _entityCombustion (\e x -> e {_entityCombustion = x})+ -- | The name of a different entity yielded when this entity is --   grabbed, if any. entityYields :: Lens' Entity (Maybe Text)@@ -509,8 +566,8 @@  -- | Look up an entity by name in an inventory, returning a list of --   matching entities.  Note, if this returns some entities, it does---   *not* mean we necessarily have any in our inventory!  It just---   means we *know about* them.  If you want to know whether you have+--   /not/ mean we necessarily have any in our inventory!  It just+--   means we /know about/ them.  If you want to know whether you have --   any, use 'lookup' and see whether the resulting 'Count' is --   positive, or just use 'countByName' in the first place. lookupByName :: Text -> Inventory -> [Entity]@@ -569,7 +626,9 @@ contains :: Inventory -> Entity -> Bool contains inv e = lookup e inv > 0 --- | Check whether an inventory has an entry for entity (used by robots).+-- | Check whether an inventory has an entry for the given entity,+--   even if there are 0 copies.  In particular this is used to+--   indicate whether a robot "knows about" an entity. contains0plus :: Entity -> Inventory -> Bool contains0plus e = isJust . IM.lookup (e ^. entityHash) . counts 

@@ -17,6 +17,7 @@  import Control.Lens ((^.)) import Data.Aeson (FromJSON, ToJSON)+import Data.List.NonEmpty (NonEmpty ((:|))) import Data.Map qualified as M import Data.Set qualified as S import Data.Text (Text)@@ -47,9 +48,10 @@  -- ------------------------------------------------------------------ --- | Suggested way to fix incapable error.+-- | Suggested way to fix things when a robot does not meet the+--   requirements to run a command. data IncapableFix-  = -- | Equip the missing device on yourself/target+  = -- | 'Swarm.Language.Syntax.Equip' the missing device on yourself/target     FixByEquip   | -- | Add the missing device to your inventory     FixByObtain@@ -66,13 +68,16 @@     InfiniteLoop   | -- | A robot tried to do something for which it does not have some     --   of the required capabilities.  This cannot be caught by a-    --   @try@ block.+    --   @try@ block.  Also contains the missing requirements, the+    --   term that caused the problem, and a suggestion for how to fix+    --   things.     Incapable IncapableFix Requirements Term-  | -- | A command failed in some "normal" way (/e.g./ a 'Move'-    --   command could not move, or a 'Grab' command found nothing to-    --   grab, /etc./).+  | -- | A command failed in some "normal" way (/e.g./ a 'Swarm.Language.Syntax.Move'+    --   command could not move, or a 'Swarm.Language.Syntax.Grab' command found nothing to+    --   grab, /etc./).  Can be caught by a @try@ block.     CmdFailed Const Text (Maybe GameplayAchievement)-  | -- | The user program explicitly called 'Undefined' or 'Fail'.+  | -- | The user program explicitly called 'Swarm.Language.Syntax.Undefined' or 'Swarm.Language.Syntax.Fail'. Can+    --   be caught by a @try@ block.     User Text   deriving (Eq, Show, Generic, FromJSON, ToJSON) @@ -94,6 +99,7 @@ -- INCAPABLE HELPERS -- ------------------------------------------------------------------ +-- | Pretty-print an 'IncapableFix': either "equip" or "obtain". formatIncapableFix :: IncapableFix -> Text formatIncapableFix = \case   FixByEquip -> "equip"@@ -137,29 +143,29 @@ formatIncapable :: EntityMap -> IncapableFix -> Requirements -> Term -> Text formatIncapable em f (Requirements caps _ inv) tm   | CGod `S.member` caps =-      unlinesExText-        [ "Thou shalt not utter such blasphemy:"-        , squote $ prettyText tm-        , "If God in troth thou wantest to play, try thou a Creative game."-        ]+      unlinesExText $+        "Thou shalt not utter such blasphemy:"+          :| [ squote $ prettyText tm+             , "If God in troth thou wantest to play, try thou a Creative game."+             ]   | not (null capsNone) =-      unlinesExText-        [ "Missing the " <> capMsg <> " for:"-        , squote $ prettyText tm-        , "but no device yet provides it. See"-        , swarmRepoUrl <> "issues/26"-        ]+      unlinesExText $+        "Missing the " <> capMsg <> " for:"+          :| [ squote $ prettyText tm+             , "but no device yet provides it. See"+             , swarmRepoUrl <> "issues/26"+             ]   | not (S.null caps) =       unlinesExText         ( "You do not have the devices required for:"-            : squote (prettyText tm)+            :| squote (prettyText tm)             : "Please " <> formatIncapableFix f <> ":"             : (("- " <>) . formatDevices <$> filter (not . null) deviceSets)         )   | otherwise =       unlinesExText         ( "You are missing required inventory for:"-            : squote (prettyText tm)+            :| squote (prettyText tm)             : "Please obtain:"             : (("- " <>) . formatEntity <$> M.assocs inv)         )@@ -177,5 +183,5 @@   formatEntity (e, n) = e <> " (" <> from (show n) <> ")"  -- | Exceptions that span multiple lines should be indented.-unlinesExText :: [Text] -> Text-unlinesExText ts = T.unlines . (head ts :) . map ("  " <>) $ tail ts+unlinesExText :: NonEmpty Text -> Text+unlinesExText (t :| ts) = T.unlines $ (t :) $ map ("  " <>) ts

@@ -3,7 +3,8 @@ -- | -- SPDX-License-Identifier: BSD-3-Clause ----- A data type to represent system failures.+-- A data type to represent system failures (as distinct from robot+-- program failures). -- -- These failures are often not fatal and serve -- to create common infrastructure for logging.@@ -31,15 +32,19 @@ ------------------------------------------------------------ -- Failure descriptions +-- | Enumeration of various assets we can attempt to load. data AssetData = AppAsset | NameGeneration | Entities | Recipes | Worlds | Scenarios | Script   deriving (Eq, Show) +-- | Overarching enumeration of various assets we can attempt to load. data Asset = Achievement | Data AssetData | History | Save   deriving (Eq, Show) +-- | Enumeration type to distinguish between directories and files. data Entry = Directory | File   deriving (Eq, Show) +-- | An error that occurred while attempting to load some kind of asset. data LoadingFailure   = DoesNotExist Entry   | EntryNot Entry@@ -58,12 +63,15 @@ -- would lead to an import cycle.  Instead, we choose to just -- pretty-print typechecking errors before storing them here. +-- | A warning that arose while processing an @00-ORDER.txt@ file. data OrderFileWarning   = NoOrderFile   | MissingFiles (NonEmpty FilePath)   | DanglingFiles (NonEmpty FilePath)   deriving (Eq, Show) +-- | An enumeration of various types of failures (errors or warnings)+--   that can occur. data SystemFailure   = AssetNotLoaded Asset FilePath LoadingFailure   | ScenarioNotFound FilePath@@ -86,7 +94,7 @@     a -> pretty (showLowT a)  instance PrettyPrec Entry where-  prettyPrec = const . prettyShowLow+  prettyPrec _ = prettyShowLow  instance PrettyPrec LoadingFailure where   prettyPrec _ = \case

@@ -16,6 +16,7 @@   applyTurn,   relativeTo,   toDirection,+  toAbsDirection,   nearestDirection,   fromDirection,   isCardinal,@@ -24,12 +25,12 @@   east,   west, -  -- ** utility functions+  -- ** Utility functions   manhattan,   euclidean,   getElemsInArea, -  -- ** reexports for convenience+  -- ** Re-exports for convenience   Affine (..),   Point (..),   origin,@@ -49,18 +50,20 @@  -- $setup -- >>> import qualified Data.Map as Map+-- >>> import Linear+-- >>> import Swarm.Language.Direction --- | A Location is a pair of (x,y) coordinates, both up to 32 bits.+-- | A t'Location' is a pair of @(x,y)@ coordinates, both up to 32 bits. --   The positive x-axis points east and the positive y-axis points --   north.  These are the coordinates that are shown to players. -----   See also the 'Coords' type defined in "Swarm.Game.World", which+--   See also the 'Swarm.Game.World.Coords' type defined in "Swarm.Game.World", which --   use a (row, column) format instead, which is more convenient for --   internal use.  The "Swarm.Game.World" module also defines---   conversions between 'Location' and 'Coords'.+--   conversions between t'Location' and 'Swarm.Game.World.Coords'. type Location = Point V2 Int32 --- | A convenient way to pattern-match on 'Location' values.+-- | A convenient way to pattern-match on t'Location' values. pattern Location :: Int32 -> Int32 -> Location pattern Location x y = P (V2 x y) @@ -74,13 +77,13 @@  -- | A @Heading@ is a 2D vector, with 32-bit coordinates. -----   'Location' and 'Heading' are both represented using types from+--   t'Location' and 'Heading' are both represented using types from --   the @linear@ package, so they can be manipulated using a large --   number of operators from that package.  For example: -- --   * Two headings can be added with '^+^'.---   * The difference between two 'Location's is a 'Heading' (via '.-.').---   * A 'Location' plus a 'Heading' is another 'Location' (via '.^+').+--   * The difference between two t'Location's is a 'Heading' (via '.-.').+--   * A t'Location' plus a 'Heading' is another t'Location' (via 'Linear.Affine..^+'). type Heading = V2 Int32  deriving instance ToJSON (V2 Int32)@@ -118,7 +121,12 @@  -- | The 'applyTurn' function gives the meaning of each 'Direction' by --   turning relative to the given heading or by turning to an absolute---   heading+--   heading.+--+--   >>> applyTurn (DRelative (DPlanar DLeft)) (V2 5 3)+--   V2 (-3) 5+--   >>> applyTurn (DAbsolute DWest) (V2 5 3)+--   V2 (-1) 0 applyTurn :: Direction -> Heading -> Heading applyTurn d = case d of   DRelative e -> case e of@@ -131,18 +139,32 @@  -- | Mapping from heading to their corresponding cardinal directions. --   Only absolute directions are mapped.-cardinalDirs :: M.Map Heading Direction+cardinalDirs :: M.Map Heading AbsoluteDir cardinalDirs =-  M.fromList $ map (toHeading &&& DAbsolute) Util.listEnums+  M.fromList $ map (toHeading &&& id) Util.listEnums  -- | Possibly convert a heading into a 'Direction'---that is, if the --   vector happens to be a unit vector in one of the cardinal --   directions.+--+--   >>> toDirection (V2 0 (-1))+--   Just (DAbsolute DSouth)+--   >>> toDirection (V2 3 7)+--   Nothing toDirection :: Heading -> Maybe Direction-toDirection v = M.lookup v cardinalDirs+toDirection = fmap DAbsolute . toAbsDirection --- | Example:---      DWest `relativeTo` DSouth == DRight+-- | Like 'toDirection', but preserve the type guarantee of an absolute direction+toAbsDirection :: Heading -> Maybe AbsoluteDir+toAbsDirection v = M.lookup v cardinalDirs++-- | Return the 'PlanarRelativeDir' which would result in turning to+--   the first (target) direction from the second (reference) direction.+--+--   >>> DWest `relativeTo` DSouth+--   DRight+--   >>> DWest `relativeTo` DWest+--   DForward relativeTo :: AbsoluteDir -> AbsoluteDir -> PlanarRelativeDir relativeTo targetDir referenceDir =   toEnum indexDiff@@ -150,20 +172,21 @@   enumCount = length (Util.listEnums :: [AbsoluteDir])   indexDiff = ((-) `on` fromEnum) targetDir referenceDir `mod` enumCount --- | Logic adapted from:--- https://gamedev.stackexchange.com/questions/49290/#comment213403_49300+-- | Compute the absolute direction nearest to a given 'Heading'.+--+--   Logic adapted from <https://gamedev.stackexchange.com/questions/49290/#comment213403_49300>. nearestDirection :: Heading -> AbsoluteDir nearestDirection coord =-  orderedDirs !! index+  Util.indexWrapNonEmpty orderedDirs index  where   angle :: Double   angle = unangle (fmap fromIntegral coord) / (2 * pi) -  index = round (fromIntegral enumCount * angle) `mod` enumCount-  orderedDirs = Util.listEnums-  enumCount = length orderedDirs+  index :: Int+  index = round $ fromIntegral (length orderedDirs) * angle+  orderedDirs = Util.listEnumsNonempty --- | Convert a 'Direction' into a corresponding heading.  Note that+-- | Convert a 'Direction' into a corresponding 'Heading'.  Note that --   this only does something reasonable for 'DNorth', 'DSouth', 'DEast', --   and 'DWest'---other 'Direction's return the zero vector. fromDirection :: Direction -> Heading@@ -179,7 +202,7 @@ euclidean :: Location -> Location -> Double euclidean p1 p2 = norm (fromIntegral <$> (p2 .-. p1)) --- | Get elements that are in manhattan distance from location.+-- | Get elements that are within a certain manhattan distance from location. -- -- >>> v2s i = [(p, manhattan origin p) | x <- [-i..i], y <- [-i..i], let p = Location x y] -- >>> v2s 0

@@ -1,76 +0,0 @@-{-# LANGUAGE QuasiQuotes #-}-{-# LANGUAGE TemplateHaskell #-}---- |--- SPDX-License-Identifier: BSD-3-Clause------ A data type to represent in-game logs by robots.------ Because of the use of system robots, we sometimes--- want to use special kinds of logs that will be--- shown to the player.------ TODO: #1039 Currently we abuse this system for system--- logs, which is fun, but we should eventually make--- a dedicated `SystemLogEntry` type for 'RuntimeState'--- message queue.-module Swarm.Game.Log (-  LogSource (..),-  ErrorLevel (..),--  -- * Robot log entries-  LogEntry (..),-  LogLocation (..),-  leText,-  leSource,-  leRobotName,-  leTime,-  leLocation,-  leRobotID,-) where--import Control.Lens hiding (contains)-import Data.Aeson (FromJSON, ToJSON)-import Data.Text (Text)-import GHC.Generics (Generic)-import Swarm.Game.CESK (TickNumber)-import Swarm.Game.Location (Location)-import Swarm.Game.Universe (Cosmic)---- | Severity of the error - critical errors are bugs---   and should be reported as Issues.-data ErrorLevel = Debug | Warning | Error | Critical-  deriving (Show, Eq, Ord, Generic, FromJSON, ToJSON)---- | Source of the robot log.-data LogSource-  = -- | Log produced by 'Swarm.Language.Syntax.Say'-    Said-  | -- | Log produced by 'Swarm.Language.Syntax.Log'-    Logged-  | -- | Log produced by an exception or system.-    ErrorTrace ErrorLevel-  deriving (Show, Eq, Ord, Generic, FromJSON, ToJSON)--data LogLocation a = Omnipresent | Located a-  deriving (Show, Eq, Ord, Generic, FromJSON, ToJSON)---- | An entry in a robot's log.-data LogEntry = LogEntry-  { _leTime :: TickNumber-  -- ^ The time at which the entry was created.-  --   Note that this is the first field we sort on.-  , _leSource :: LogSource-  -- ^ Whether this log records a said message.-  , _leRobotName :: Text-  -- ^ The name of the robot that generated the entry.-  , _leRobotID :: Int-  -- ^ The ID of the robot that generated the entry.-  , _leLocation :: LogLocation (Cosmic Location)-  -- ^ Location of the robot at log entry creation.-  , _leText :: Text-  -- ^ The text of the log entry.-  }-  deriving (Show, Eq, Ord, Generic, FromJSON, ToJSON)--makeLenses ''LogEntry

@@ -6,13 +6,30 @@ -- -- A recipe represents some kind of process for transforming -- some input entities into some output entities.+--+-- Recipes support a number of different game mechanics, including:+--+-- * crafting+-- * mining+-- * randomized "loot boxes"+-- * unlocking doors+--+-- == Synchronous vs Async+-- Recipes can be completed either within the same tick+-- as execution is started, or execution may span+-- multiple ticks. It is possible for the execution+-- of multi-tick recipes to be interrupted in one way or+-- another, in which case the recipe fails without producing+-- the "outputs". module Swarm.Game.Recipe (   -- * Ingredient lists and recipes   IngredientList,   Recipe (..),++  -- ** Fields   recipeInputs,   recipeOutputs,-  recipeRequirements,+  recipeCatalysts,   recipeTime,   recipeWeight, @@ -20,7 +37,7 @@   loadRecipes,   outRecipeMap,   inRecipeMap,-  reqRecipeMap,+  catRecipeMap,    -- * Looking up recipes   MissingIngredient (..),@@ -61,14 +78,12 @@ --   game is running. type IngredientList e = [(Count, e)] --- | A recipe is just a list of input entities and a list of output---   entities (both with multiplicity).  The idea is that it---   represents some kind of process where the inputs are---   transformed into the outputs.+-- | A recipe represents some kind of process where inputs are+--   transformed into outputs. data Recipe e = Recipe   { _recipeInputs :: IngredientList e   , _recipeOutputs :: IngredientList e-  , _recipeRequirements :: IngredientList e+  , _recipeCatalysts :: IngredientList e   , _recipeTime :: Integer   , _recipeWeight :: Integer   }@@ -89,8 +104,8 @@ recipeTime :: Lens' (Recipe e) Integer  -- | Other entities which the recipe requires you to have, but which---   are not consumed by the recipe (e.g. a furnace).-recipeRequirements :: Lens' (Recipe e) (IngredientList e)+--   are not consumed by the recipe (e.g. a @\"furnace\"@).+recipeCatalysts :: Lens' (Recipe e) (IngredientList e)  -- | How this recipe is weighted against other recipes.  Any time --   there are multiple valid recipes that fit certain criteria, one@@ -103,12 +118,12 @@ ------------------------------------------------------------  instance ToJSON (Recipe Text) where-  toJSON (Recipe ins outs reqs time weight) =+  toJSON (Recipe ins outs cats time weight) =     object $       [ "in" .= ins       , "out" .= outs       ]-        ++ ["required" .= reqs | not (null reqs)]+        ++ ["required" .= cats | not (null cats)]         ++ ["time" .= time | time /= 1]         ++ ["weight" .= weight | weight /= 1] @@ -185,9 +200,9 @@ inRecipeMap :: [Recipe Entity] -> IntMap [Recipe Entity] inRecipeMap = buildRecipeMap recipeInputs --- | Build a map of recipes indexed by requirements.-reqRecipeMap :: [Recipe Entity] -> IntMap [Recipe Entity]-reqRecipeMap = buildRecipeMap recipeRequirements+-- | Build a map of recipes indexed by catalysts.+catRecipeMap :: [Recipe Entity] -> IntMap [Recipe Entity]+catRecipeMap = buildRecipeMap recipeCatalysts  -- | Get a list of all the recipes for the given entity.  Look up an --   entity in either an 'inRecipeMap' or 'outRecipeMap' depending on@@ -196,28 +211,32 @@ recipesFor :: IntMap [Recipe Entity] -> Entity -> [Recipe Entity] recipesFor rm e = fromMaybe [] $ IM.lookup (e ^. entityHash) rm +-- | Record information about something missing from a recipe. data MissingIngredient = MissingIngredient MissingType Count Entity   deriving (Show, Eq) +-- | What kind of thing is missing? data MissingType = MissingInput | MissingCatalyst   deriving (Show, Eq)  -- | Figure out which ingredients (if any) are lacking from an---   inventory to be able to carry out the recipe.---   Requirements are not consumed and so can use equipped.+--   inventory to be able to carry out the recipe.  Catalysts are not+--   consumed and so can be used even when equipped. missingIngredientsFor :: (Inventory, Inventory) -> Recipe Entity -> [MissingIngredient]-missingIngredientsFor (inv, ins) (Recipe inps _ reqs _ _) =+missingIngredientsFor (inv, ins) (Recipe inps _ cats _ _) =   mkMissing MissingInput (findLacking inv inps)-    <> mkMissing MissingCatalyst (findLacking ins (findLacking inv reqs))+    <> mkMissing MissingCatalyst (findLacking ins (findLacking inv cats))  where   mkMissing k = map (uncurry (MissingIngredient k))   findLacking inven = filter ((> 0) . fst) . map (countNeeded inven)   countNeeded inven (need, entity) = (need - E.lookup entity inven, entity) --- | Figure out if a recipe is available, but it can be lacking items.+-- | Figure out if a recipe is available, /i.e./ if we at least know+--   about all the ingredients.  Note it does not matter whether we have+--   enough of the ingredients. knowsIngredientsFor :: (Inventory, Inventory) -> Recipe Entity -> Bool knowsIngredientsFor (inv, ins) recipe =-  knowsAll inv (recipe ^. recipeInputs) && knowsAll ins (recipe ^. recipeRequirements)+  knowsAll inv (recipe ^. recipeInputs) && knowsAll ins (recipe ^. recipeCatalysts)  where   knowsAll xs = all (E.contains xs . snd) @@ -227,12 +246,10 @@ --   or an inventory without inputs and function adding outputs if --   it was successful. make ::-  -- robots inventory and equipped devices+  -- | The robot's inventory and equipped devices   (Inventory, Inventory) ->-  -- considered recipe+  -- | The recipe we are trying to make   Recipe Entity ->-  -- failure (with count of missing) or success with a new inventory,-  -- a function to add results and the recipe repeated   Either     [MissingIngredient]     (Inventory, IngredientList Entity, Recipe Entity)

@@ -12,6 +12,7 @@ import Control.Exception (catch) import Control.Exception.Base (IOException) import Control.Monad (forM, when, (<=<))+import Data.Array (Array, listArray) import Data.Map (Map) import Data.Map qualified as M import Data.Maybe (mapMaybe)@@ -31,10 +32,16 @@ import System.FilePath import Witch +-- | Read-only lists of adjectives and words for use in building random robot names+data NameGenerator = NameGenerator+  { adjList :: Array Int Text+  , nameList :: Array Int Text+  }+ -- | Get subdirectory from swarm data directory. -- -- This will first look in Cabal generated path and then--- try a `data` directory in 'XdgData' path.+-- try a @data@ directory in 'XdgData' path. -- -- The idea is that when installing with Cabal/Stack the first -- is preferred, but when the players install a binary they@@ -75,7 +82,7 @@     then return fp     else throwError $ AssetNotLoaded (Data asset) fp $ DoesNotExist File --- | Get a nice message suggesting to download `data` directory to 'XdgData'.+-- | Get a nice message suggesting to download @data@ directory to 'XdgData'. dataNotFound :: FilePath -> IO LoadingFailure dataNotFound f = do   d <- getSwarmXdgDataSubdir False ""@@ -89,7 +96,7 @@  -- | Get path to swarm data, optionally creating necessary --   directories. This could fail if user has bad permissions---   on his own $HOME or $XDG_DATA_HOME which is unlikely.+--   on his own @$HOME@ or @$XDG_DATA_HOME@ which is unlikely. getSwarmXdgDataSubdir :: Bool -> FilePath -> IO FilePath getSwarmXdgDataSubdir createDirs subDir = do   swarmData <- (</> subDir) <$> getXdgDirectory XdgData "swarm"@@ -112,7 +119,7 @@ getSwarmHistoryPath :: Bool -> IO FilePath getSwarmHistoryPath createDirs = getSwarmXdgDataFile createDirs "history" --- | Read all the .txt files in the data/ directory.+-- | Read all the @.txt@ files in the @data/@ directory. readAppData ::   (Has (Throw SystemFailure) sig m, Has (Lift IO) sig m) =>   m (Map Text Text)@@ -126,3 +133,20 @@    filesList <- sendIO $ forM fs (\f -> (into @Text (dropExtension f),) <$> readFileMayT (d </> f))   return $ M.fromList . mapMaybe sequenceA $ filesList++initNameGenerator :: Has (Throw SystemFailure) sig m => Map Text Text -> m NameGenerator+initNameGenerator appDataMap = do+  adjs <- getDataLines "adjectives"+  names <- getDataLines "names"+  return $+    NameGenerator+      { adjList = makeArr adjs+      , nameList = makeArr names+      }+ where+  makeArr xs = listArray (0, length xs - 1) xs+  getDataLines f = case M.lookup f appDataMap of+    Nothing ->+      throwError $+        AssetNotLoaded (Data NameGeneration) (into @FilePath f <.> "txt") (DoesNotExist File)+    Just content -> return . drop 1 . T.lines $ content

@@ -13,9 +13,6 @@ module Swarm.Game.Robot (   -- * Robots data -  -- * Robot log entries-  module Swarm.Game.Log,-   -- * Robots   RobotPhase (..),   RID,@@ -38,6 +35,7 @@   robotEntity,   robotName,   trobotName,+  unwalkableEntities,   robotCreatedAt,   robotDisplay,   robotLocation,@@ -58,8 +56,13 @@   machine,   systemRobot,   selfDestruct,-  tickSteps,   runningAtomic,+  activityCounts,+  tickStepBudget,+  tangibleCommandCount,+  commandsHistogram,+  lifetimeStepCount,+  activityWindow,    -- ** Creation & instantiation   mkRobot,@@ -76,11 +79,12 @@   hearingDistance, ) where -import Control.Lens hiding (contains)-import Data.Aeson (FromJSON, ToJSON)+import Control.Lens hiding (Const, contains)+import Data.Aeson qualified as Ae (FromJSON, Key, KeyValue, ToJSON (..), object, (.=)) import Data.Hashable (hashWithSalt) import Data.Kind qualified-import Data.Maybe (fromMaybe, isNothing)+import Data.Map (Map)+import Data.Maybe (catMaybes, fromMaybe, isNothing) import Data.Sequence (Seq) import Data.Sequence qualified as Seq import Data.Set (Set)@@ -94,17 +98,19 @@ import Swarm.Game.Display (Display, curOrientation, defaultRobotDisplay, invisible) import Swarm.Game.Entity hiding (empty) import Swarm.Game.Location (Heading, Location, toDirection)-import Swarm.Game.Log import Swarm.Game.Universe import Swarm.Language.Capability (Capability) import Swarm.Language.Context qualified as Ctx+import Swarm.Language.Pipeline.QQ (tmQ) import Swarm.Language.Requirement (ReqCtx)-import Swarm.Language.Syntax (Syntax)+import Swarm.Language.Syntax (Const, Syntax) import Swarm.Language.Text.Markdown (Document) import Swarm.Language.Typed (Typed (..)) import Swarm.Language.Types (TCtx) import Swarm.Language.Value as V-import Swarm.Util.Lens (makeLensesExcluding)+import Swarm.Log+import Swarm.Util.Lens (makeLensesExcluding, makeLensesNoSigs)+import Swarm.Util.WindowedCounter import Swarm.Util.Yaml import System.Clock (TimeSpec) @@ -124,7 +130,7 @@   -- ^ A store containing memory cells allocated to hold   --   definitions.   }-  deriving (Eq, Show, Generic, FromJSON, ToJSON)+  deriving (Eq, Show, Generic, Ae.FromJSON, Ae.ToJSON)  makeLenses ''RobotContext @@ -167,6 +173,85 @@   | -- | The robot record represents a concrete robot in the world.     ConcreteRobot +data ActivityCounts = ActivityCounts+  { _tickStepBudget :: Int+  , _tangibleCommandCount :: Int+  , _commandsHistogram :: Map Const Int+  , _lifetimeStepCount :: Int+  , _activityWindow :: WindowedCounter TickNumber+  }+  deriving (Eq, Show, Generic, Ae.FromJSON, Ae.ToJSON)++emptyActivityCount :: ActivityCounts+emptyActivityCount =+  ActivityCounts+    { _tickStepBudget = 0+    , _tangibleCommandCount = 0+    , _commandsHistogram = mempty+    , _lifetimeStepCount = 0+    , -- NOTE: This value was chosen experimentally.+      -- TODO(#1341): Make this dynamic based on game speed.+      _activityWindow = mkWindow 64+    }++makeLensesNoSigs ''ActivityCounts++-- | A counter that is decremented upon each step of the robot within the+--   CESK machine. Initially set to 'Swarm.Game.State.robotStepsPerTick'+--   at each new tick.+--+--   The need for 'tickStepBudget' is a bit technical, and I hope I can+--   eventually find a different, better way to accomplish it.+--   Ideally, we would want each robot to execute a single+--   /command/ at every game tick, so that /e.g./ two robots+--   executing @move;move;move@ and @repeat 3 move@ (given a+--   suitable definition of @repeat@) will move in lockstep.+--   However, the second robot actually has to do more computation+--   than the first (it has to look up the definition of @repeat@,+--   reduce its application to the number 3, etc.), so its CESK+--   machine will take more steps.  It won't do to simply let each+--   robot run until executing a command---because robot programs+--   can involve arbitrary recursion, it is very easy to write a+--   program that evaluates forever without ever executing a+--   command, which in this scenario would completely freeze the+--   UI. (It also wouldn't help to ensure all programs are+--   terminating---it would still be possible to effectively do+--   the same thing by making a program that takes a very, very+--   long time to terminate.)  So instead, we allocate each robot+--   a certain maximum number of computation steps per tick+--   (defined in 'Swarm.Game.Step.evalStepsPerTick'), and it+--   suspends computation when it either executes a command or+--   reaches the maximum number of steps, whichever comes first.+--+--   It seems like this really isn't something the robot should be+--   keeping track of itself, but that seemed the most technically+--   convenient way to do it at the time.  The robot needs some+--   way to signal when it has executed a command, which it+--   currently does by setting tickStepBudget to zero.  However, that+--   has the disadvantage that when tickStepBudget becomes zero, we+--   can't tell whether that happened because the robot ran out of+--   steps, or because it executed a command and set it to zero+--   manually.+--+--   Perhaps instead, each robot should keep a counter saying how+--   many commands it has executed.  The loop stepping the robot+--   can tell when the counter increments.+tickStepBudget :: Lens' ActivityCounts Int++-- | Total number of tangible commands executed over robot's lifetime+tangibleCommandCount :: Lens' ActivityCounts Int++-- | Histogram of commands executed over robot's lifetime+commandsHistogram :: Lens' ActivityCounts (Map Const Int)++-- | Total number of CESK steps executed over robot's lifetime.+-- This could be thought of as "CPU cycles" consumed, and is labeled+-- as "cycles" in the F2 dialog in the UI.+lifetimeStepCount :: Lens' ActivityCounts Int++-- | Sliding window over a span of ticks indicating ratio of activity+activityWindow :: Lens' ActivityCounts (WindowedCounter TickNumber)+ -- | With a robot template, we may or may not have a location.  With a --   concrete robot we must have a location. type family RobotLocation (phase :: RobotPhase) :: Data.Kind.Type where@@ -197,8 +282,9 @@   , _machine :: CESK   , _systemRobot :: Bool   , _selfDestruct :: Bool-  , _tickSteps :: Int+  , _activityCounts :: ActivityCounts   , _runningAtomic :: Bool+  , _unwalkableEntities :: Set EntityName   , _robotCreatedAt :: TimeSpec   }   deriving (Generic)@@ -206,8 +292,6 @@ deriving instance (Show (RobotLocation phase), Show (RobotID phase)) => Show (RobotR phase) deriving instance (Eq (RobotLocation phase), Eq (RobotID phase)) => Eq (RobotR phase) -deriving instance (ToJSON (RobotLocation phase), ToJSON (RobotID phase)) => ToJSON (RobotR phase)- -- See https://byorgey.wordpress.com/2021/09/17/automatically-updated-cached-views-with-lens/ -- for the approach used here with lenses. @@ -221,7 +305,25 @@ type Robot = RobotR 'ConcreteRobot  instance ToSample Robot where-  toSamples _ = SD.noSamples+  toSamples _ = SD.singleSample sampleBase+   where+    sampleBase :: Robot+    sampleBase =+      mkRobot+        0+        Nothing+        "base"+        "The starting robot."+        defaultCosmicLocation+        zero+        defaultRobotDisplay+        (initMachine [tmQ| move |] mempty emptyStore)+        []+        []+        False+        False+        mempty+        0  -- In theory we could make all these lenses over (RobotR phase), but -- that leads to lots of type ambiguity problems later.  In practice@@ -239,11 +341,15 @@ --   . 'entityName'@. robotEntity :: Lens' (RobotR phase) Entity +-- | Entities that the robot cannot move onto+unwalkableEntities :: Lens' Robot (Set EntityName)+ -- | The creation date of the robot. robotCreatedAt :: Lens' Robot TimeSpec --- robotName and trobotName could be generalized to robotName' ::--- Lens' (RobotR phase) Text.  However, type inference does not work+-- robotName and trobotName could be generalized to+-- @robotName' :: Lens' (RobotR phase) Text@.+-- However, type inference does not work -- very well with the polymorphic version, so we export both -- monomorphic versions instead. @@ -269,22 +375,22 @@       & curOrientation .~ ((r ^. robotOrientation) >>= toDirection)   setDisplay r d = r & robotEntity . entityDisplay .~ d --- | The robot's current location, represented as (x,y).  This is only+-- | The robot's current location, represented as @(x,y)@.  This is only --   a getter, since when changing a robot's location we must remember---   to update the 'robotsByLocation' map as well.  You can use the---   'updateRobotLocation' function for this purpose.+--   to update the 'Swarm.Game.State.robotsByLocation' map as well.  You can use the+--   'Swarm.Game.Step.updateRobotLocation' function for this purpose. robotLocation :: Getter Robot (Cosmic Location)  -- | Set a robot's location.  This is unsafe and should never be---   called directly except by the 'updateRobotLocation' function.---   The reason is that we need to make sure the 'robotsByLocation'+--   called directly except by the 'Swarm.Game.Step.updateRobotLocation' function.+--   The reason is that we need to make sure the 'Swarm.Game.State.robotsByLocation' --   map stays in sync. unsafeSetRobotLocation :: Cosmic Location -> Robot -> Robot unsafeSetRobotLocation loc r = r {_robotLocation = loc}  -- | A template robot's location.  Unlike 'robotLocation', this is a --   lens, since when dealing with robot templates there is as yet no---   'robotsByLocation' map to keep up-to-date.+--   'Swarm.Game.State.robotsByLocation' map to keep up-to-date. trobotLocation :: Lens' TRobot (Maybe (Cosmic Location)) trobotLocation = lens _robotLocation (\r l -> r {_robotLocation = l}) @@ -344,8 +450,8 @@       }  -- | The robot's own private message log, most recent message last.---   Messages can be added both by explicit use of the 'Log' command,---   and by uncaught exceptions.  Stored as a "Data.Sequence" so that+--   Messages can be added both by explicit use of the 'Swarm.Language.Syntax.Log' command,+--   and by uncaught exceptions.  Stored as a 'Seq' so that --   we can efficiently add to the end and also process from beginning --   to end.  Note that updating via this lens will also set the --   'robotLogUpdated'.@@ -396,43 +502,8 @@ -- | Does this robot wish to self destruct? selfDestruct :: Lens' Robot Bool --- | The need for 'tickSteps' is a bit technical, and I hope I can---   eventually find a different, better way to accomplish it.---   Ideally, we would want each robot to execute a single---   /command/ at every game tick, so that /e.g./ two robots---   executing @move;move;move@ and @repeat 3 move@ (given a---   suitable definition of @repeat@) will move in lockstep.---   However, the second robot actually has to do more computation---   than the first (it has to look up the definition of @repeat@,---   reduce its application to the number 3, etc.), so its CESK---   machine will take more steps.  It won't do to simply let each---   robot run until executing a command---because robot programs---   can involve arbitrary recursion, it is very easy to write a---   program that evaluates forever without ever executing a---   command, which in this scenario would completely freeze the---   UI. (It also wouldn't help to ensure all programs are---   terminating---it would still be possible to effectively do---   the same thing by making a program that takes a very, very---   long time to terminate.)  So instead, we allocate each robot---   a certain maximum number of computation steps per tick---   (defined in 'Swarm.Game.Step.evalStepsPerTick'), and it---   suspends computation when it either executes a command or---   reaches the maximum number of steps, whichever comes first.------   It seems like this really isn't something the robot should be---   keeping track of itself, but that seemed the most technically---   convenient way to do it at the time.  The robot needs some---   way to signal when it has executed a command, which it---   currently does by setting tickSteps to zero.  However, that---   has the disadvantage that when tickSteps becomes zero, we---   can't tell whether that happened because the robot ran out of---   steps, or because it executed a command and set it to zero---   manually.------   Perhaps instead, each robot should keep a counter saying how---   many commands it has executed.  The loop stepping the robot---   can tell when the counter increments.-tickSteps :: Lens' Robot Int+-- | Diagnostic and operational tracking of CESK steps or other activity+activityCounts :: Lens' Robot ActivityCounts  -- | Is the robot currently running an atomic block? runningAtomic :: Lens' Robot Bool@@ -463,10 +534,12 @@   Bool ->   -- | Is this robot heavy?   Bool ->+  -- | Unwalkable entities+  Set EntityName ->   -- | Creation date   TimeSpec ->   RobotR phase-mkRobot rid pid name descr loc dir disp m devs inv sys heavy ts =+mkRobot rid pid name descr loc dir disp m devs inv sys heavy unwalkables ts =   RobotR     { _robotEntity =         mkEntity disp name descr [] []@@ -485,8 +558,9 @@     , _machine = m     , _systemRobot = sys     , _selfDestruct = False-    , _tickSteps = 0+    , _activityCounts = emptyActivityCount     , _runningAtomic = False+    , _unwalkableEntities = unwalkables     }  where   inst = fromList devs@@ -512,10 +586,46 @@       <*> v ..:? "inventory" ..!= []       <*> pure sys       <*> liftE (v .:? "heavy" .!= False)+      <*> liftE (v .:? "unwalkable" ..!= mempty)       <*> pure 0    where     mkMachine Nothing = Out VUnit emptyStore []     mkMachine (Just pt) = initMachine pt mempty emptyStore++(.=?) :: (Ae.KeyValue a, Ae.ToJSON v, Eq v) => Ae.Key -> v -> v -> Maybe a+(.=?) n v defaultVal = if defaultVal /= v then Just $ n Ae..= v else Nothing++(.==) :: (Ae.KeyValue a, Ae.ToJSON v) => Ae.Key -> v -> Maybe a+(.==) n v = Just $ n Ae..= v++instance Ae.ToJSON Robot where+  toJSON r =+    Ae.object $+      catMaybes+        [ "id" .== (r ^. robotID)+        , "name" .== (r ^. robotEntity . entityDisplay)+        , "description" .=? (r ^. robotEntity . entityDescription) $ mempty+        , "loc" .== (r ^. robotLocation)+        , "dir" .=? (r ^. robotEntity . entityOrientation) $ zero+        , "display" .=? (r ^. robotDisplay) $ (defaultRobotDisplay & invisible .~ sys)+        , "program" .== (r ^. machine)+        , "devices" .=? (map (^. _2 . entityName) . elems $ r ^. equippedDevices) $ []+        , "inventory" .=? (map (_2 %~ view entityName) . elems $ r ^. robotInventory) $ []+        , "system" .=? sys $ False+        , "heavy" .=? (r ^. robotHeavy) $ False+        , "log" .=? (r ^. robotLog) $ mempty+        , -- debug+          "capabilities" .=? (r ^. robotCapabilities) $ mempty+        , "logUpdated" .=? (r ^. robotLogUpdated) $ False+        , "context" .=? (r ^. robotContext) $ emptyRobotContext+        , "parent" .=? (r ^. robotParentID) $ Nothing+        , "createdAt" .=? (r ^. robotCreatedAt) $ 0+        , "selfDestruct" .=? (r ^. selfDestruct) $ False+        , "activity" .=? (r ^. activityCounts) $ emptyActivityCount+        , "runningAtomic" .=? (r ^. runningAtomic) $ False+        ]+   where+    sys = r ^. systemRobot  -- | Is the robot actively in the middle of a computation? isActive :: Robot -> Bool

@@ -44,6 +44,7 @@   loadScenario,   loadScenarioFile,   getScenarioPath,+  loadStandaloneScenario, ) where  import Control.Arrow ((&&&))@@ -57,6 +58,7 @@ import Data.List.NonEmpty qualified as NE import Data.Map qualified as M import Data.Maybe (catMaybes, isNothing, listToMaybe)+import Data.Sequence (Seq) import Data.Text (Text) import Data.Text qualified as T import Swarm.Game.Entity@@ -74,11 +76,14 @@ import Swarm.Game.Scenario.Topography.Structure qualified as Structure import Swarm.Game.Scenario.Topography.WorldDescription import Swarm.Game.Universe+import Swarm.Game.World.Load (loadWorlds) import Swarm.Game.World.Typecheck (WorldMap) import Swarm.Language.Pipeline (ProcessedTerm) import Swarm.Language.Pretty (prettyText)+import Swarm.Language.Syntax (Syntax)+import Swarm.Language.Text.Markdown (Document) import Swarm.Util (binTuples, failT)-import Swarm.Util.Effect (throwToMaybe, withThrow)+import Swarm.Util.Effect (ignoreWarnings, throwToMaybe, withThrow) import Swarm.Util.Lens (makeLensesNoSigs) import Swarm.Util.Yaml import System.Directory (doesFileExist)@@ -94,7 +99,7 @@   { _scenarioVersion :: Int   , _scenarioName :: Text   , _scenarioAuthor :: Maybe Text-  , _scenarioDescription :: Text+  , _scenarioDescription :: Document Syntax   , _scenarioCreative :: Bool   , _scenarioSeed :: Maybe Int   , _scenarioAttrs :: [CustomAttr]@@ -203,7 +208,7 @@  -- | A high-level description of the scenario, shown /e.g./ in the --   menu.-scenarioDescription :: Lens' Scenario Text+scenarioDescription :: Lens' Scenario (Document Syntax)  -- | Whether the scenario should start in creative mode. scenarioCreative :: Lens' Scenario Bool@@ -287,3 +292,14 @@     decodeFileEitherE (em, worldMap) fileName  where   adaptError = AssetNotLoaded (Data Scenarios) fileName . CanNotParseYaml++loadStandaloneScenario ::+  (Has (Throw SystemFailure) sig m, Has (Lift IO) sig m) =>+  FilePath ->+  m (Scenario, (WorldMap, EntityMap, [Recipe Entity]))+loadStandaloneScenario fp = do+  entities <- loadEntities+  recipes <- loadRecipes entities+  worlds <- ignoreWarnings @(Seq SystemFailure) $ loadWorlds entities+  scene <- fst <$> loadScenario fp entities worlds+  return (scene, (worlds, entities, recipes))

@@ -35,17 +35,17 @@   -- explain the broader intention behind potentially multiple   -- prerequisites.   ---  -- Set this to option True to display this goal in the "upcoming" section even+  -- Set this option to 'True' to display this goal in the "upcoming" section even   -- if the objective has currently unmet prerequisites.   , logic :: Prerequisite ObjectiveLabel   -- ^ Boolean expression of dependencies upon other objectives. Variables in this expression   -- are the "id"s of other objectives, and become "true" if the corresponding objective is completed.   -- The "condition" of the objective at hand shall not be evaluated until its-  -- prerequisite expression evaluates as True.+  -- prerequisite expression evaluates as 'True'.   --   -- Note that the achievement of these objective dependencies is   -- persistent; once achieved, they still count even if their "condition"-  -- might not still hold. The condition is never re-evaluated once True.+  -- might not still hold. The condition is never re-evaluated once true.   }   deriving (Eq, Show, Generic, ToJSON) @@ -115,7 +115,7 @@ -- This attribute often goes along with an Achievement. objectiveHidden :: Lens' Objective Bool --- | An optional Achievement that is to be registered globally+-- | An optional achievement that is to be registered globally -- when this objective is completed. objectiveAchievement :: Lens' Objective (Maybe AchievementInfo) 

@@ -3,7 +3,7 @@ -- | -- SPDX-License-Identifier: BSD-3-Clause ----- Validity checking for Objective prerequisites+-- Validity checking for 'Objective' prerequisites module Swarm.Game.Scenario.Objective.Validation where  import Control.Monad (unless)@@ -19,9 +19,10 @@ -- | Performs monadic validation before returning -- the "pure" construction of a wrapper record. -- This validation entails:--- 1) Ensuring that all goal references utilized in prerequisites+--+-- 1. Ensuring that all goal references utilized in prerequisites --    actually exist--- 2) Ensuring that the graph of dependencies is acyclic.+-- 2. Ensuring that the graph of dependencies is acyclic. validateObjectives ::   MonadFail m =>   [Objective] ->

@@ -2,7 +2,10 @@ {-# LANGUAGE TemplateHaskell #-} {-# OPTIONS_GHC -Wno-orphans #-} --- | Types and records for updating and retrieving+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Types and records for updating and retrieving -- the best scores for a scenario. module Swarm.Game.Scenario.Scoring.Best where 

@@ -1,5 +1,8 @@--- | Types and utilities to compute code size--- in terms of textual length and AST.+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Types and utilities to compute code size+-- in terms of textual length and AST nodes. module Swarm.Game.Scenario.Scoring.CodeSize where  import Control.Monad (guard)

@@ -1,6 +1,9 @@ {-# LANGUAGE TemplateHaskell #-} --- | Data types and instances for specific scoring methods+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Data types and instances for specific scoring methods module Swarm.Game.Scenario.Scoring.ConcreteMetrics where  import Control.Lens hiding (from, (<.>))

@@ -1,4 +1,7 @@--- | Data types and functions applicable across different+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Data types and functions applicable across different -- scoring methods. module Swarm.Game.Scenario.Scoring.GenericMetrics where @@ -36,10 +39,10 @@ -- for incomplete games (rationale: more play = more fun), --  whereas "smaller inputs are better" for completed games. ----- Since "Maybe" has its own "Ord" instance where+-- Since 'Maybe' has its own 'Ord' instance where -- @Nothing < Just x@ regardless of @x@, when we want to--- choose the minimum value we `fmap Down` to ensure that--- the `Just` is selected while inverting the ordering of+-- choose the minimum value we @fmap Down@ to ensure that+-- the 'Just' is selected while inverting the ordering of -- the inner member. chooseBetter ::   Ord a =>

@@ -2,7 +2,10 @@ {-# LANGUAGE TemplateHaskell #-} {-# OPTIONS_GHC -Wno-orphans #-} --- | High-level status of scenario play.+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- High-level status of scenario play. -- Representation of progress, logic for updating. module Swarm.Game.Scenario.Status where @@ -26,8 +29,9 @@ import Swarm.Util.Lens (makeLensesNoSigs)  -- | These launch parameters are used in a number of ways:+-- -- * Serializing the seed/script path for saves--- * Holding parse status from form fields, including Error info+-- * Holding parse status from form fields, including error info -- * Carrying fully-validated launch parameters. -- -- Type parameters are utilized to support all of these use cases.@@ -45,9 +49,9 @@ deriving instance FromJSON SerializableLaunchParams deriving instance ToJSON SerializableLaunchParams --- | A "ScenarioStatus" stores the status of a scenario along with---   appropriate metadata: "NotStarted", or "Played".---   The "Played" status has two sub-states: "Attempted" or "Completed".+-- | A 'ScenarioStatus' stores the status of a scenario along with+--   appropriate metadata: 'NotStarted', or 'Played'.+--   The 'Played' status has two sub-states: 'Attempted' or 'Completed'. data ScenarioStatus   = NotStarted   | Played@@ -63,14 +67,17 @@   toEncoding = genericToEncoding scenarioOptions   toJSON = genericToJSON scenarioOptions +emptyLaunchParams :: Applicative f => ParameterizableLaunchParams a f+emptyLaunchParams = LaunchParams (pure Nothing) (pure Nothing)+ getLaunchParams :: ScenarioStatus -> SerializableLaunchParams getLaunchParams = \case-  NotStarted -> LaunchParams (pure Nothing) (pure Nothing)+  NotStarted -> emptyLaunchParams   Played x _ _ -> x --- | A "ScenarioInfo" record stores metadata about a scenario: its+-- | A 'ScenarioInfo' record stores metadata about a scenario: its -- canonical path and status.--- By way of the "ScenarioStatus" record, it stores the+-- By way of the 'ScenarioStatus' record, it stores the -- most recent status and best-ever status. data ScenarioInfo = ScenarioInfo   { _scenarioPath :: FilePath@@ -95,11 +102,11 @@ -- | The status of the scenario. scenarioStatus :: Lens' ScenarioInfo ScenarioStatus --- | Update the current "ScenarioInfo" record when quitting a game.+-- | Update the current 'ScenarioInfo' record when quitting a game. -- -- Note that when comparing \"best\" times, shorter is not always better! -- As long as the scenario is not completed (e.g. some do not have win condition)--- we consider having fun _longer_ to be better.+-- we consider having fun /longer/ to be better. updateScenarioInfoOnFinish ::   CodeSizeDeterminators ->   ZonedTime ->

@@ -1,5 +1,7 @@ -- | -- SPDX-License-Identifier: BSD-3-Clause+--+-- Types for styling custom entity attributes module Swarm.Game.Scenario.Style where  import Data.Aeson@@ -30,6 +32,8 @@ instance ToJSON StyleFlag where   toJSON = genericToJSON styleFlagJsonOptions +-- | Hexadecimal color notation.+-- May include a leading hash symbol (see 'Data.Colour.SRGB.sRGB24read'). newtype HexColor = HexColor Text   deriving (Eq, Show, Generic, FromJSON, ToJSON) 

@@ -1,5 +1,7 @@ {-# LANGUAGE OverloadedStrings #-} +-- |+-- SPDX-License-Identifier: BSD-3-Clause module Swarm.Game.Scenario.Topography.Area where  import Data.Int (Int32)@@ -8,6 +10,7 @@ import Linear (V2 (..)) import Swarm.Game.Location +-- | Height and width of a 2D map region data AreaDimensions = AreaDimensions   { rectWidth :: Int32   , rectHeight :: Int32@@ -20,9 +23,9 @@ invertY :: V2 Int32 -> V2 Int32 invertY (V2 x y) = V2 x (-y) --- | Incorporates an offset by -1, since the area is+-- | Incorporates an offset by @-1@, since the area is -- "inclusive" of the lower-right coordinate.--- Inverse of "cornersToArea".+-- Inverse of 'cornersToArea'. upperLeftToBottomRight :: AreaDimensions -> Location -> Location upperLeftToBottomRight (AreaDimensions w h) upperLeft =   upperLeft .+^ displacement@@ -30,18 +33,20 @@   displacement = invertY $ subtract 1 <$> V2 w h  -- | Converts the displacement vector between the two--- diagonal corners of the rectangle into an "AreaDimensions" record.+-- diagonal corners of the rectangle into an 'AreaDimensions' record. -- Adds one to both dimensions since the corner coordinates are "inclusive".--- Inverse of "upperLeftToBottomRight".+-- Inverse of 'upperLeftToBottomRight'. cornersToArea :: Location -> Location -> AreaDimensions cornersToArea upperLeft lowerRight =   AreaDimensions x y  where   V2 x y = (+ 1) <$> invertY (lowerRight .-. upperLeft) +-- | Has zero width or height. isEmpty :: AreaDimensions -> Bool isEmpty (AreaDimensions w h) = w == 0 || h == 0 +-- | Extracts the dimensions of a map grid. getAreaDimensions :: [[a]] -> AreaDimensions getAreaDimensions cellGrid =   AreaDimensions w h

@@ -11,8 +11,8 @@ ) where  import Control.Lens hiding (from, (.=), (<.>))-import Control.Monad (when) import Control.Monad.Extra (mapMaybeM)+import Data.List.NonEmpty qualified as NE import Data.Maybe (catMaybes, listToMaybe) import Data.Text (Text) import Data.Vector qualified as V@@ -31,8 +31,8 @@  -- | A single cell in a world map, which contains a terrain value, --   and optionally an entity and robot.---   It is parameterized on the Entity type to facilitate less---   stateful versions of the Entity type in rendering scenario data.+--   It is parameterized on the 'Entity' type to facilitate less+--   stateful versions of the 'Entity' type in rendering scenario data. data PCell e = Cell   { cellTerrain :: TerrainType   , cellEntity :: Erasable e@@ -51,7 +51,7 @@   }   deriving (Eq, Show) --- | Re-usable serialization for variants of "PCell"+-- | Re-usable serialization for variants of 'PCell' mkPCellJson :: ToJSON b => (Erasable a -> Maybe b) -> PCell a -> Value mkPCellJson modifier x =   toJSON $@@ -69,10 +69,12 @@  instance FromJSONE (EntityMap, RobotMap) Cell where   parseJSONE = withArrayE "tuple" $ \v -> do-    let tup = V.toList v-    when (null tup) $ fail "palette entry must nonzero length (terrain, optional entity and then robots if any)"+    let tupRaw = V.toList v+    tup <- case NE.nonEmpty tupRaw of+      Nothing -> fail "palette entry must have nonzero length (terrain, optional entity and then robots if any)"+      Just x -> return x -    terr <- liftE $ parseJSON (head tup)+    terr <- liftE $ parseJSON (NE.head tup)      ent <- case tup ^? ix 1 of       Nothing -> return ENothing@@ -87,7 +89,7 @@           mrName <- liftE $ parseJSON @(Maybe RobotName) r           traverse (localE snd . getRobot) mrName -    robs <- mapMaybeM name2rob (drop 2 tup)+    robs <- mapMaybeM name2rob (drop 2 tupRaw)      return $ Cell terr ent robs @@ -115,7 +117,7 @@ -- for rendering. type CellPaintDisplay = PCell EntityFacade --- Note: This instance is used only for the purpose of WorldPalette+-- Note: This instance is used only for the purpose of 'WorldPalette' instance ToJSON CellPaintDisplay where   toJSON = mkPCellJson $ \case     ENothing -> Nothing

@@ -1,6 +1,9 @@ {-# LANGUAGE DerivingVia #-} --- | Stand-in type for an "Entity" for purposes+-- |+-- SPDX-License-Identifier: BSD-3-Clause+--+-- Stand-in type for an "Entity" for purposes -- that do not require carrying around the entire state -- of an Entity. --@@ -9,19 +12,16 @@ module Swarm.Game.Scenario.Topography.EntityFacade where  import Control.Lens ((^.))-import Data.Text (Text) import Data.Yaml as Y (ToJSON (toJSON)) import Swarm.Game.Display (Display) import Swarm.Game.Entity qualified as E -type EntityName = Text- -- | This datatype is a lightweight stand-in for the -- full-fledged "Entity" type without the baggage of all -- of its other fields. -- It contains the bare minimum display information -- for rendering.-data EntityFacade = EntityFacade EntityName Display+data EntityFacade = EntityFacade E.EntityName Display   deriving (Eq)  -- Note: This instance is used only for the purpose of WorldPalette

@@ -3,6 +3,15 @@  -- | -- SPDX-License-Identifier: BSD-3-Clause+--+-- Type definitions and validation logic for portals.+--+-- Portals can be inter-world or intra-world.+-- It is legal for a portal exit to be on the same cell as its entrance.+--+-- By default, passage through a portal preserves the orientation+-- of the robot, but an extra portal parameter can specify+-- that the robot should be re-oriented. module Swarm.Game.Scenario.Topography.Navigation.Portal where  import Control.Arrow ((&&&))@@ -40,12 +49,14 @@  -- | Parameterized on waypoint dimensionality ('additionalDimension') and -- on the portal location specification method ('portalExitLoc').+-- -- == @additionalDimension@--- As a member of the 'WorldDescription', waypoints are only known within a+-- As a member of the 'Swarm.Game.Scenario.Topography.WorldDescription.WorldDescription', waypoints are only known within a -- a single subworld, so 'additionalDimension' is 'Identity' for the map -- of waypoint names to planar locations. -- At the Scenario level, in contrast, we have access to all subworlds, so -- we nest this map to planar locations in additional mapping layer by subworld.+-- -- == @portalExitLoc@ -- At the subworld parsing level, we only can obtain the planar location -- for portal /entrances/, but the /exits/ remain as waypoint names.@@ -110,14 +121,15 @@  -- | -- The following constraints must be enforced:+-- -- * portals based on plural waypoint multiplicity can have multiple entrances but only a single exit -- * no two portals share the same entrance location -- * waypoint uniqueness within a subworld when the 'unique' flag is specified ----- == Data flow:+-- == Data flow -- -- Waypoints are defined within a subworld and are namespaced by it.--- Optional intra-subworld uniqueness of Waypoints is enforced at WorldDescription+-- Optional intra-subworld uniqueness of Waypoints is enforced at 'Swarm.Game.Scenario.Topography.WorldDescription.WorldDescription' -- parse time. -- Portals are declared within a subworld. The portal entrance must be a waypoint -- within this subworld.@@ -128,7 +140,7 @@ --   no entrances overlap can also be performed at that level. -- * However, enforcement of single-multiplicity on portal /exits/ must be performed --   at scenario-parse level, because for a portal exit that references a waypoint in---   another subworld, we can't know at the single-WorldDescription level whether+--   another subworld, we can't know at the single-'Swarm.Game.Scenario.Topography.WorldDescription.WorldDescription' level whether --   that waypoint has plural multiplicity. validatePartialNavigation ::   (MonadFail m, Traversable t) =>@@ -217,6 +229,7 @@ -- -- Verifying this is simple: -- For all of the portals between Subworlds A and B:+-- -- * The coordinates of all \"consistent\" portal locations in Subworld A --   are subtracted from the corresponding coordinates in Subworld B. It --   does not matter which are exits vs. entrances.@@ -271,6 +284,7 @@ -- -- == Discussion -- Compare to the 'Traversable' instance of 'Signed':+-- -- @ -- instance Traversable Signed where --   traverse f (Positive x) = Positive <$> f x@@ -278,6 +292,7 @@ -- @ -- -- if we were to substitute 'id' for f:+-- -- @ --   traverse id (Positive x) = Positive <$> id x --   traverse id (Negative x) = Negative <$> id x

@@ -0,0 +1,44 @@+-- |+-- SPDX-License-Identifier: BSD-3-Clause+module Swarm.Game.Scenario.Topography.Navigation.Util where++import Control.Lens (view)+import Data.Function (on)+import Data.Int (Int32)+import Linear (V2)+import Swarm.Game.Location+import Swarm.Game.Robot+import Swarm.Game.Universe (Cosmic, planar)+import Swarm.Language.Direction++-- |+-- Computes the relative offset vector between a 'Robot' and a 'Location'+-- (presumed to be in the same subworld, though the contrary will+-- not result in failure), then re-interpret that vector based on the+-- 'Robot'\'s current orientation.+--+-- If the robot is not oriented in a cardinal direction, returns 'Nothing'.+--+-- = Re-orientation semantics+--+-- Given a displacement vector @(x, y)@ where:+--+-- * positive @x@-coordinate represents @east@+-- * negative @x@-coordinate represents @west@+-- * positive @y@-coordinate represents @north@+-- * negative @y@-coordinate represents @south@+--+-- the re-interpreted vector @(x', y')@ becomes:+--+-- * positive @x'@-coordinate represents @right@+-- * negative @x'@-coordinate represents @left@+-- * positive @y'@-coordinate represents @forward@+-- * negative @y'@-coordinate represents @back@+orientationBasedRelativePosition :: Robot -> Cosmic Location -> Maybe (V2 Int32)+orientationBasedRelativePosition selfRobot otherLocation =+  (`applyTurn` relativeCoords) <$> maybeSelfDirRelativeToNorth+ where+  maybeSelfDirection = view robotOrientation selfRobot >>= toAbsDirection+  maybeSelfDirRelativeToNorth = DRelative . DPlanar . relativeTo DNorth <$> maybeSelfDirection++  relativeCoords = ((.-.) `on` view planar) otherLocation (view robotLocation selfRobot)

@@ -2,6 +2,22 @@  -- | -- SPDX-License-Identifier: BSD-3-Clause+--+-- Landmarks that are used to specify portal locations+-- and can serve as navigation aids via the `waypoint` command.+--+-- = Waypoint ordering+--+-- The sequence of waypoints of a given name is dictated by criteria in the following order:+--+-- 1. Ordering of structure placements+--    (see implementation of 'Swarm.Game.Scenario.Topography.Structure.mergeStructures');+--    later placements are ordered first.+-- 2. Placement of cells within a map. Map locations go by row-major order+--    (compare to docs for 'Swarm.Game.State.genRobotTemplates').+--+-- TODO (#1366): May be useful to have a mechanism for more+-- precise control of ordering. module Swarm.Game.Scenario.Topography.Navigation.Waypoint where  import Data.Int (Int32)

@@ -2,6 +2,9 @@  -- | -- SPDX-License-Identifier: BSD-3-Clause+--+-- Descriptions of the orientation and offset by+-- which a structure should be placed. module Swarm.Game.Scenario.Topography.Placement where  import Data.List (transpose)

@@ -2,6 +2,9 @@  -- | -- SPDX-License-Identifier: BSD-3-Clause+--+-- Definitions of "structures" for use within a map,+-- as well as logic for combining them. module Swarm.Game.Scenario.Topography.Structure where  import Control.Applicative ((<|>))@@ -94,7 +97,7 @@           else drop $ abs integralOffset  -- | Overlays all of the "child placements", such that the children encountered earlier--- in the YAML file supersede the later ones (due to use of "foldr" instead of "foldl").+-- in the YAML file supersede the later ones (due to use of 'foldr' instead of 'foldl'). mergeStructures ::   M.Map StructureName (PStructure (Maybe a)) ->   Maybe Placement ->@@ -121,8 +124,8 @@     (maskedArea, mapWaypoints) <- liftE $ (v .:? "map" .!= "") >>= paintMap maybeMaskChar pal     return $ Structure maskedArea localStructureDefs placementDefs $ waypointDefs <> mapWaypoints --- | "Paint" a world map using a 'WorldPalette', turning it from a raw---   string into a nested list of 'Cell' values by looking up each+-- | \"Paint\" a world map using a 'WorldPalette', turning it from a raw+--   string into a nested list of 'PCell' values by looking up each --   character in the palette, failing if any character in the raw map --   is not contained in the palette. paintMap ::