theseus 2.0.0

  • Readme
  • Changelog
  • Installing
  • 53

Theseus #

Theseus port https://github.com/jamis/theseus version 1.0.2

Theseus is a library for generating and solving mazes. It also includes routines for rendering mazes (and their solutions) to both ASCII art, and to PNG image files.

There is also an included utility for generating mazes from the command-line.

Overview #

Theseus supports the following types of mazes:

  • Orthogonal. This is the traditional maze layout of rectangular passages.
  • Delta. This maze type tesselates the field into triangles.
  • Sigma. The field is tesselated into hexagons.
  • Upsilon. The maze field consists of tiled octogons and squares.

Mazes may be generated using any of the following features:

  • Symmetry. The maze may be reflected in x, y, x and y, or radially. (Not all maze types support symmetry yet.)
  • Randomness. A maze with low randomness will result in many long, straight corridors. Higher randomness gives a maze with more twists and turns.
  • Weave. Mazes with high weave will frequently pass over or under existing passages. Low weave mazes will prefer to remain on the same plane.
  • Braid. Mazes with high braid will trade dead-ends for circular loops in the maze. Thus, braided mazes will tend to have multiple possible solutions.
  • Wrap. Mazes may wrap in x, y, or x and y together. A maze that wraps in any of its dimensions will allow the passages to go from one side of the maze to the other, by moving beyond the far edge of the maze. Another way to think of it is that a maze that wraps in one dimension may be mapped onto a cylinder, and a maze that wraps in both dimensions may be mapped onto a torus.
  • Masks. Mazes may be constrained with masks, which are basically boolean grids that define where a passage is allowed to exist. With masks, you can create mazes that fit pre-defined geometry, or wrap around text.

Theseus supports the following output types:

  • ASCII. Using the ASCII output, you can simply print a maze to the console to see what it looks like. Not all features can be displayed well in ASCII mode, but it works well enough to see what the maze will be like.
  • PNG or Canvas. Mazes that are rendered to PNG may be highly customized, and even allow you to specify custom paths to be rendered.

Theseus supports the following solution algorithms:

  • Recursive Backtracking. This is a fast, efficient algorithm for solving mazes that have no circular loops (e.g. unbraided mazes).
  • A star Search. The A* search algorithm really shines with mazes that are highly braided, and is guaranteed to provide you with the shortest path through the maze.

Orthogonal mazes may be converted to their unicursal equivalent. A unicursal maze is one which has only a single path that covers every cell in the field exactly once. This style is maze is often called a "labyrinth". See Theseus::OrthogonalMaze#to_unicursal for more information.

Theseus is also designed to allow you to step through both the generation of the maze, as well as the computation of the solution. This lets you (for instance) animate the construction (and solution) of the maze by drawing individual PNG frames for each step! And since Theseus includes an implementation of A* Search, this gives you an interesting way to visualize (among other things) how that algorithm works.

Lastly, Theseus can be used to manually build mazes (or any other grid-based structure) by hand. See Theseus::Maze for more information.

Usage #

Theseus is designed to be super simple to use. See 'example' folder.

License #

Theseus is created by Jamis Buck. It is made available in the public domain, completely unencumbered by rules, restrictions, or any other nonsense.

Please prefer good over evil.

Changelog #

1.0.3+2 #

  • Fix AStar solver

1.0.3+1 #

  • Fix all PNG formatters

1.0.3 #

  • Migrate to test package

0.0.1 #

  • Initial version, created by Stagehand

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  theseus: ^2.0.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:theseus/theseus.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
12
Health:
Code health derived from static analysis. [more]
91
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
96
Overall:
Weighted score of the above. [more]
53
Learn more about scoring.

We analyzed this package on Nov 9, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.6.0
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:theseus/theseus.dart.

Health issues and suggestions

Document public APIs. (-0.18 points)

172 out of 177 API elements have no dartdoc comment.Providing good documentation for libraries, classes, functions, and other API elements improves code readability and helps developers find and use your API.

Fix lib/src/maze.dart. (-2.96 points)

Analysis of lib/src/maze.dart reported 6 hints, including:

line 46 col 3: Prefer using /// for doc comments.

line 123 col 104: Use = to separate a named parameter from its default value.

line 537 col 7: This function has a return type of 'bool', but doesn't end with a return statement.

line 538 col 39: This function has a return type of 'bool', but doesn't end with a return statement.

line 933 col 46: This function has a return type of 'bool', but doesn't end with a return statement.

Fix lib/src/formatters/ascii/orthogonal.dart. (-1.99 points)

Analysis of lib/src/formatters/ascii/orthogonal.dart reported 4 hints:

line 6 col 3: Prefer using /// for doc comments.

line 12 col 3: Prefer using /// for doc comments.

line 18 col 3: Prefer using /// for doc comments.

line 159 col 75: This function has a return type of 'bool', but doesn't end with a return statement.

Fix lib/src/formatters/png.dart. (-1 points)

Analysis of lib/src/formatters/png.dart reported 2 hints:

line 54 col 18: Don't explicitly initialize variables to null.

line 122 col 36: Don't explicitly initialize variables to null.

Fix additional 23 files with analysis or formatting issues. (-3 points)

Additional issues in the following files:

  • lib/src/orthogonal_maze.dart (2 hints)
  • lib/ruby_port.dart (1 hint)
  • lib/src/path.dart (1 hint)
  • lib/src/solvers/astar.dart (1 hint)
  • lib/src/solvers/solvers.dart (1 hint)
  • lib/src/algorithms/algorithms.dart (Run dartfmt to format lib/src/algorithms/algorithms.dart.)
  • lib/src/algorithms/base.dart (Run dartfmt to format lib/src/algorithms/base.dart.)
  • lib/src/algorithms/recursive_backtracker.dart (Run dartfmt to format lib/src/algorithms/recursive_backtracker.dart.)
  • lib/src/delta_maze.dart (Run dartfmt to format lib/src/delta_maze.dart.)
  • lib/src/formatters/ascii.dart (Run dartfmt to format lib/src/formatters/ascii.dart.)
  • lib/src/formatters/ascii/delta.dart (Run dartfmt to format lib/src/formatters/ascii/delta.dart.)
  • lib/src/formatters/ascii/sigma.dart (Run dartfmt to format lib/src/formatters/ascii/sigma.dart.)
  • lib/src/formatters/ascii/upsilon.dart (Run dartfmt to format lib/src/formatters/ascii/upsilon.dart.)
  • lib/src/formatters/formatters.dart (Run dartfmt to format lib/src/formatters/formatters.dart.)
  • lib/src/formatters/png/delta.dart (Run dartfmt to format lib/src/formatters/png/delta.dart.)
  • lib/src/formatters/png/orthogonal.dart (Run dartfmt to format lib/src/formatters/png/orthogonal.dart.)
  • lib/src/formatters/png/sigma.dart (Run dartfmt to format lib/src/formatters/png/sigma.dart.)
  • lib/src/formatters/png/upsilon.dart (Run dartfmt to format lib/src/formatters/png/upsilon.dart.)
  • lib/src/mask.dart (Run dartfmt to format lib/src/mask.dart.)
  • lib/src/sigma_maze.dart (Run dartfmt to format lib/src/sigma_maze.dart.)
  • lib/src/solvers/backtracker.dart (Run dartfmt to format lib/src/solvers/backtracker.dart.)
  • lib/src/solvers/base.dart (Run dartfmt to format lib/src/solvers/base.dart.)
  • lib/src/upsilon_maze.dart (Run dartfmt to format lib/src/upsilon_maze.dart.)

Maintenance suggestions

Package is getting outdated. (-3.56 points)

The package was last published 54 weeks ago.

Maintain an example.

None of the files in the package's example/ directory matches known example patterns.

Common filename patterns include main.dart, example.dart, and theseus.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
Dev dependencies
image ^2.0.0
test ^1.3.0