Tiny Yurts¶

Isometric grid, BFS path-following agents, drawable routes.

Upstream: https://github.com/burntcustard/tiny-yurts

Licence: this port's own code is offered under MIT, not the SimVX Examples Licence the rest of the gallery carries. See ATTRIBUTION.md for the upstream it re-implements, the terms of anything it bundles, and the credit each one requires.

Ports live in the repository only, not in the simvx-examples distribution, because each is a derivative work licensed individually against the game it re-implements. Read it with git clone https://git.simvx.com/simvx/simvx.

Tags: port tier-1

Tiny Yurts (SimVX port)¶

A SimVX port of burntcustard/tiny-yurts, a Mini-Motorways-inspired routing puzzle from js13kGames 2023.

The original is HTML-CSS-SVG-in-JS and 13 KB zipped. This port keeps the gameplay shape (drag paths, settlers walk routes, farms overflow if unfed) but adds an isometric (~30 deg) projection, three farm/yurt pairs, and a menu plus HUD around the board.

Licensing: a clean re-implementation under MIT. The board, the backdrop and the HUD bar are procedural on_draw calls, and the text uses the engine’s own font and widgets, so nothing from upstream (art, audio, fonts, or data) is bundled. See ATTRIBUTION.md and UPSTREAM_LICENSE.md.

Run¶

# from the repo root
uv run python examples/ports/tiny_yurts/main.py            # interactive
uv run python examples/ports/tiny_yurts/main.py --test     # headless capture (3 frames)
uv run python examples/ports/tiny_yurts/harness.py         # scripted-input capture (7 stages)
uv run simvx export web examples/ports/tiny_yurts/main.py \
    -o /tmp/tiny_yurts.html

Controls¶

Action	Input
Draw a path	Drag (mouse or touch) from cell to adjacent cell
Remove a path tile	Right-click near it
Restart	`R`
Back to menu	`ESC` (in game)
Quit	`ESC` (on the menu)
Start	`ENTER` or `SPACE`

Win / lose¶

Reach 12 deliveries to win.
If any farm’s demand exceeds its capacity, you lose.
Settlers spawn at yurts, walk paths to matching farms, deliver, return.

What this shows in SimVX¶

Retained 2D drawing. The board is one Node2D.on_draw body. It reads plain (non-Property) state that changes every tick, so World sets dynamic = True to re-collect its draw ops each frame; the menu and the HUD backdrop are static and call queue_redraw() only when the layout moves.
Named input actions. TinyYurtsRoot.input_actions declares every binding on the root, which is where the scene tree picks them up (the web runtime instantiates the root directly and never calls main()). Touch arrives as MouseButton.LEFT, so place_path covers mouse and finger alike.
Signals. World emits delivery_made, game_over, and victory; the game scene connects each to the one piece of HUD it owns, and polls only the clock and the path budget, which have no event behind them.
Resize-aware layout. Both scenes connect tree.screen_resized and re-run a single _apply_layout, which re-anchors the controls strip, re-centres the text, and re-anchors the isometric projection origin.
BFS routing. Grid.find_route runs a breadth-first search over the path graph the player has drawn, not over free space, so settlers only ever walk on laid paths.

File map¶

tiny_yurts/
├── main.py              # entry point: root, menu and game scenes, HUD
├── harness.py           # scripted-input capture (7 stages)
└── nodes/
    ├── iso.py           # isometric projection helpers + colour palette
    ├── grid.py          # path graph, farm/yurt entities, BFS routing
    ├── world.py         # World node: input, simulation, draw
    └── settler.py       # animated agent that walks a precomputed route

Source files¶

File	Summary	Lines
`main.py`	Tiny Yurts: Isometric grid, BFS path-following agents, drawable routes.	289
`harness.py`	Scripted-input harness for Tiny Yurts.	139
`nodes/__init__.py`		0
`nodes/grid.py`	Grid state: path graph, farms, yurts, and BFS pathfinder.	143
`nodes/iso.py`	Isometric projection helpers and the colour palette.	77
`nodes/settler.py`	Settler: an agent that walks a precomputed cell path between yurt and farm.	117
`nodes/world.py`	World: owns the Grid, dispatches Settlers, and renders everything iso.	335

Source¶

"""Tiny Yurts: Isometric grid, BFS path-following agents, drawable routes.

# /// simvx
# tags = ["port", "tier-1"]
# upstream = "https://github.com/burntcustard/tiny-yurts"
# web = { width = 1280, height = 720, responsive = true }
# ///

Routing puzzle in the spirit of Mini Motorways, after burntcustard's js13kGames
2023 entry "Tiny Yurts". Drag paths between the animal farms (ox, goat, fish)
and the yurt of the same kind; settlers walk those paths and work each farm's
demand back down. Let one farm's demand pass its capacity and you lose; land 12
deliveries and you win.

The port shows an isometric projection drawn through the retained 2D renderer
(the board node is marked ``dynamic`` so its hover preview and demand bars
re-collect every frame), drag input polled through named input actions so mouse
and touch share one code path, BFS routing over a graph the player builds,
Signals carrying the score and the win/lose banner into the HUD, and a
menu-to-game swap under a single root node. Both scenes re-lay out on resize.

Run (from the repo root):
    uv run python examples/ports/tiny_yurts/main.py
    uv run python examples/ports/tiny_yurts/main.py --test    # headless frame captures
"""

from __future__ import annotations

import sys
from pathlib import Path

# Allow running from any cwd
_PORT_DIR = Path(__file__).parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from nodes import iso  # noqa: E402
from nodes.world import DELIVERIES_TO_WIN, World, world_centre_origin  # noqa: E402

from simvx.core import Input, Key, MouseButton, Node, Node2D, Text2D  # noqa: E402
from simvx.core.ui.enums import AnchorPreset  # noqa: E402
from simvx.core.ui.widgets import Label, Panel  # noqa: E402
from simvx.graphics import App  # noqa: E402

WIDTH = 1280
HEIGHT = 720

HUD_HEIGHT = 44
CONTROLS_HEIGHT = 44


# ---------------------------------------------------------------------------
# Menu
# ---------------------------------------------------------------------------


class TinyYurtsMenu(Node2D):
    """Landing screen: title, how-to-play lines, and the start prompt."""

    INSTRUCTIONS = (
        "Drag from cell to cell to draw paths between farms and yurts.",
        "Settlers walk the path to feed the farm of their own kind.",
        "Right-click a path tile to remove it.",
        f"Lose if any farm overflows. Reach {DELIVERIES_TO_WIN} deliveries to win.",
    )

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.title = self._add_line("Tiny Yurts", 3.6, (0.95, 0.92, 0.78, 1.0))
        self.subtitle = self._add_line(
            "A SimVX port of burntcustard's js13k routing puzzle", 1.1, (0.85, 0.85, 0.78, 1.0)
        )
        self.lines = [self._add_line(text, 1.05, (0.93, 0.93, 0.85, 1.0)) for text in self.INSTRUCTIONS]
        self.prompt = self._add_line("ENTER  start    ·    ESC  quit", 1.2, (1.0, 0.95, 0.55, 1.0))

    def _add_line(self, text: str, font_scale: float, colour) -> Text2D:
        """Add one centred line of text. ``align`` centres on ``position.x``."""
        node = Text2D(text=text, font_scale=font_scale, colour=colour, align="centre")
        self.add_child(node)
        return node

    def on_ready(self) -> None:
        self._apply_layout(self.tree.screen_size)
        self.tree.screen_resized.connect(self._apply_layout)

    def on_exit_tree(self) -> None:
        self.tree.screen_resized.disconnect(self._apply_layout)

    def _apply_layout(self, size) -> None:
        """Centre the text block and the iso board on the current viewport."""
        w, h = size
        world_centre_origin(w, h)
        self.title.position = (w / 2, h * 0.30)
        self.subtitle.position = (w / 2, h * 0.30 + 70)
        for idx, node in enumerate(self.lines):
            node.position = (w / 2, h * 0.30 + 130 + 28 * idx)
        self.prompt.position = (w / 2, h * 0.78)
        # The backdrop tiles below are drawn from the (plain, non-Property) iso
        # origin, so the draw has to be re-collected once per layout change.
        self.queue_redraw()

    def on_draw(self, renderer) -> None:
        # Soft grass backdrop and a few static tiles for flavour
        w, h = self.tree.screen_size
        renderer.draw_rect((0, 0), (w, h), colour=iso.COLOUR_GRASS_DARK, filled=True)
        for j in range(iso.GRID_ROWS):
            for i in range(iso.GRID_COLS):
                if (i + j) & 1:
                    continue
                corners = iso.tile_corners(i, j)
                renderer.draw_polygon(corners, colour=(0.42, 0.66, 0.34, 0.5))


# ---------------------------------------------------------------------------
# Game
# ---------------------------------------------------------------------------


class TinyYurtsGame(Node2D):
    """In-game scene: world + HUD + bottom controls strip."""

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.world = World()
        self.add_child(self.world)

        # HUD text overlays (Text2D goes through MSDF pass, sits above on_draw)
        self.score_text = Text2D(text="Score 0", position=(20, 14), font_scale=1.4, colour=(0.98, 0.98, 0.92, 1.0))
        self.budget_text = Text2D(text="Paths 32", position=(180, 14), font_scale=1.4, colour=(0.98, 0.98, 0.92, 1.0))
        self.timer_text = Text2D(text="Time 0s", position=(340, 14), font_scale=1.4, colour=(0.98, 0.98, 0.92, 1.0))
        self.status_text = Text2D(text="", font_scale=2.4, align="centre", colour=(1.0, 0.95, 0.55, 1.0))
        self.add_child(self.score_text)
        self.add_child(self.budget_text)
        self.add_child(self.timer_text)
        self.add_child(self.status_text)

        # Bottom controls strip: a light bar so the controls read on any backdrop
        self.controls_panel = Panel()
        self.controls_panel.bg_colour = iso.COLOUR_CONTROLS_BG
        self.add_child(self.controls_panel)

        self.controls_label = Label(
            text="Drag = path  ·  Right-click = remove  ·  R = restart  ·  ESC = menu",
        )
        self.controls_label.text_colour = (0.18, 0.18, 0.20, 1.0)
        self.controls_label.font_size = 20.0
        self.controls_label.alignment = "center"
        self.add_child(self.controls_label)

    def on_ready(self) -> None:
        self._apply_layout(self.tree.screen_size)
        self.tree.screen_resized.connect(self._apply_layout)
        # State transitions arrive as signals; each one owns one piece of the HUD.
        self.world.delivery_made.connect(self._refresh_score)
        self.world.game_over.connect(self._show_defeat)
        self.world.victory.connect(self._show_victory)
        self._refresh_score()

    def on_exit_tree(self) -> None:
        self.tree.screen_resized.disconnect(self._apply_layout)

    def _apply_layout(self, size) -> None:
        """Apply anchors, banner placement, and iso origin for the viewport size."""
        w, h = size
        world_centre_origin(w, h)
        # Banner sits above the board (which world_centre_origin puts at ~55%)
        # so it never lands on top of the farms.
        self.status_text.position = (w / 2, h * 0.20)
        # Bottom-wide controls strip: anchors stretch horizontally, and a negative
        # margin_top lifts the panel its own height above the bottom edge.
        for ctl in (self.controls_panel, self.controls_label):
            ctl.set_anchor_preset(AnchorPreset.BOTTOM_WIDE)
            ctl.margin_left = 0
            ctl.margin_right = 0
            ctl.margin_top = -CONTROLS_HEIGHT
            ctl.margin_bottom = 0
            ctl.size_y = CONTROLS_HEIGHT
            # An anchored control's rect follows the viewport, not its own
            # Properties, so a pure resize leaves its retained draw stale.
            ctl.queue_redraw()
        # The backdrop below is drawn from the viewport size, not from Properties.
        self.queue_redraw()

    def on_update(self, dt: float) -> None:
        if Input.is_action_just_pressed("restart"):
            self.world.reset()
            self._refresh_score()
            self.status_text.text = ""
        # The two readouts with no signal behind them: the clock advances every
        # frame and the path budget moves with every drag.
        self.timer_text.text = f"Time {int(self.world.elapsed)}s"
        self.budget_text.text = f"Paths {self.world.path_budget}"

    def _refresh_score(self) -> None:
        self.score_text.text = f"Score {self.world.deliveries}/{DELIVERIES_TO_WIN}"

    def _show_defeat(self) -> None:
        self.status_text.text = "FARM OVERWHELMED  ·  R to retry"
        self.status_text.colour = (1.00, 0.45, 0.40, 1.0)

    def _show_victory(self) -> None:
        self.status_text.text = "YOU WIN  ·  R to play again"
        self.status_text.colour = (0.50, 1.00, 0.55, 1.0)

    def on_draw(self, renderer) -> None:
        # Dark grass to frame the iso board, plus the HUD strip along the top
        w, h = self.tree.screen_size
        renderer.draw_rect((0, 0), (w, h), colour=iso.COLOUR_GRASS_DARK, filled=True)
        renderer.draw_rect((0, 0), (w, HUD_HEIGHT), colour=iso.COLOUR_HUD_BG, filled=True)


# ---------------------------------------------------------------------------
# Root
# ---------------------------------------------------------------------------


class TinyYurtsRoot(Node):
    """Top-level scene; declares the input actions and toggles menu/game."""

    # Declared on the root so the scene tree registers them on mount: the web
    # runtime instantiates this class directly and never calls main().
    # Touch surfaces as MouseButton.LEFT, so "place_path" covers mouse and finger.
    input_actions = {
        "start": [Key.ENTER, Key.SPACE],
        "quit": [Key.ESCAPE],
        "restart": [Key.R],
        "place_path": [MouseButton.LEFT],
        "remove_path": [MouseButton.RIGHT],
    }

    def on_ready(self) -> None:
        self.state = "menu"
        self.menu = self.add_child(TinyYurtsMenu())
        self.game: TinyYurtsGame | None = None

    def on_update(self, dt: float) -> None:
        if self.state == "menu":
            if Input.is_action_just_pressed("start"):
                self._enter_game()
            elif Input.is_action_just_pressed("quit"):
                self.app.quit()
        elif self.state == "game":
            if Input.is_action_just_pressed("quit"):
                self._enter_menu()

    def _enter_game(self) -> None:
        self.menu.destroy()
        self.menu = None
        self.game = self.add_child(TinyYurtsGame())
        self.state = "game"

    def _enter_menu(self) -> None:
        if self.game is not None:
            self.game.destroy()
            self.game = None
        self.menu = self.add_child(TinyYurtsMenu())
        self.state = "menu"


# ---------------------------------------------------------------------------
# Entry / harness
# ---------------------------------------------------------------------------


def _run_headless() -> None:
    """Capture frame_30/60/120 into screenshots/."""
    from simvx.graphics import save_png

    captures = [30, 60, 120]
    app = App(width=WIDTH, height=HEIGHT, title="Tiny Yurts (SimVX)", visible=False)
    frames = app.run_headless(TinyYurtsRoot(), frames=130, capture_frames=captures)
    out_dir = _PORT_DIR / "screenshots"
    out_dir.mkdir(exist_ok=True)
    for idx, img in zip(captures, frames, strict=False):
        out_path = out_dir / f"frame_{idx}.png"
        save_png(img, out_path)
        print(f"saved {out_path}")


def main() -> None:
    if "--test" in sys.argv:
        _run_headless()
        return
    app = App(width=WIDTH, height=HEIGHT, title="Tiny Yurts (SimVX)")
    app.run(TinyYurtsRoot())


if __name__ == "__main__":
    main()