Skip to main content

Crate egui_pipes

Crate egui_pipes 

Source
Expand description

§egui-pipes

crates.io docs.rs deps.rs CI Rust version License Changelog Live demo

A self-contained pipe-connecting puzzle game library for egui.

Water enters the board on the left and has to come out at a marked point on the right. In between sit columns of pipe pieces: straights and 90-degree corners. The pieces themselves never rotate. The only move is scrolling a whole column down or up, wrapping around, until each column’s outlet lines up with the next column’s inlet. Some columns are locked and cannot be scrolled at all, so the movable ones have to be arranged around them. On some boards the water doubles back into a column it has already passed through before carrying on to the right.

The water is live feedback rather than a reward at the end: it always runs from the inlet as far as the pipework currently reaches, and stops at the first dead end. Connecting the last stretch is what carries it to the outlet.

§Features

  • Pure game logic struct (PipesGame) with no egui::Ui dependency, usable headlessly or with any renderer
  • Ready-to-use egui Widget (PipesWidget) drawing hollow, double-walled pipes that visibly fill with water
  • Procedural, seeded generation (PipesGame::random, or PipesGame::random_with_turn_backs to let the solution double back) that always produces a solvable board and verifies, per board, that exactly one combination of column scrolls solves it
  • An exact solution counter (PipesGame::solution_count, PipesGame::solve), fast enough to run on every generated candidate
  • No dangling corners, by construction: every column is a cyclic partition into self-contained runs, so scrolling can never produce an illegal board
  • Click a column to scroll it down, drag it up or down to follow the pointer one row per cell, or use the mouse wheel to scroll it either way
  • No losing state and no timer: every scroll is undone by scrolling back
  • Locked columns are drawn darker, outlined, and marked with a padlock

§Usage

Add the dependency:

[dependencies]
egui-pipes = "0.4"

Then use it in your egui app:

ⓘ
use egui_pipes::{PipesGame, PipesWidget};

// 7 columns, 6 rows, 60% of the columns locked, reproducible from a seed.
let mut game = PipesGame::random(7, 6, 0.6, 42);

// Or let the solution double back into a previous column, at most twice.
// The allowance is a ceiling: plenty of boards still come out straight.
let mut game = PipesGame::random_with_turn_backs(7, 6, 0.6, 2, 42);

// Inside your egui update/UI closure:
ui.add(PipesWidget::new(&mut game));

// Customize the water color and the win banner:
use egui::Color32;
ui.add(
    PipesWidget::new(&mut game)
        .water_color(Color32::from_rgb(0x3A, 0xC0, 0xA0))
        .win_message("Solved!"),
);

Check for a win after each frame:

ⓘ
use egui_pipes::GameStatus;

match game.status() {
    GameStatus::Playing => {}
    GameStatus::Won => println!("Connected!"),
}

To start over on the same puzzle:

ⓘ
game.reset();

To offer a hint, ask the solver where the columns need to end up:

ⓘ
if let Some(offsets) = game.solve() {
    // `offsets[col]` is where column `col` needs to end up; compare it with
    // `game.offset(col)` to see how far it still has to travel.
}

§How generation guarantees a single solution

Only a run’s entry cell has an opening on its left, and a run of signed displacement delta placed with its entry on row a always delivers the water to row a + delta. So a column offers exactly as many valid scroll positions for a required a -> b transition as it has runs of displacement b - a.

The generator lays the intended solution down first, then fills the rest of each column with random runs while keeping that displacement unique within every scrollable column. That makes each column individually unambiguous; a counting dynamic program over the whole board then confirms no globally different route exists either, and the board is regenerated if one does.

§egui version compatibility

egui-pipesegui
0.10.35
0.2 - 0.40.36

§License

Licensed under either of MIT or Apache-2.0 at your option.

Structs§

FlowStep
One cell the water passes through, in flow order.
PipesGame
A pipe puzzle: a columns x rows board of pipe pieces, plus a water inlet on the left edge and an outlet on the right edge.
PipesWidget
An egui widget that renders an interactive pipe board.

Enums§

GameStatus
Whether the puzzle is still being played or has been solved. There is no losing state: a scroll is always undoable by scrolling back.
Piece
A single pipe piece. Only straights and 90-degree corners exist: there are no tees and no crossings, so flow through a piece is always a function of the edge it entered by.
Rotation
Which way a column scroll moves its pieces.
Side
One of a cell’s four edges.

Constants§

DEFAULT_WATER_COLOR
The default color of the water, a mid cyan-blue that stays legible on both a light and a dark board. Override with PipesWidget::water_color.

Functions§

content_size
The footprint PipesWidget occupies for game at a given cell_size. One extra cell of width covers the inlet and outlet stubs, half a cell on each side of the board.
fit_cell_size
The cell size that fits game into available space, which is the same formula PipesWidget uses when no explicit cell_size is set. Lets a caller pre-compute the fit instead of duplicating it.