Swiftpack.co - Package - josephroquedev/hive-engine

Logo

Hive Engine

Build status codecov

Manages the game state of a game of hive and determines valid playable moves.

Additionally, produces new game states from the application of valid moves.

This engine optionally supports games with all 3 official Hive expansions: the Mosquito, the Lady Bug, and the Pill Bug. See details on the GameState below for options.

Usage

You can read about each of the engine's components below, or dive right in with an instance of GameState:

let state = GameState()

Unit

A Unit represents one of the various pieces a game of Hive is played with -- ants, spiders, etc.

Each Unit has a class, which defines the type of bug it is, an owner to let you know who it belongs to, and an identifier to differentiate each instance.

There are a variety of functions for determining if a Unit can move, and where it can move to.

Each class of Unit also provides an extension to the Unit class to calculate its moves. See extension classes such as Unit+Ant and Unit+Beetle for more.

Position

A Position is a space on the "board" where a Unit can be placed or moved to.

Positions rely on a hexagonal grid system, inspired by an excellent article by Red Blog Games. Details on the grid system implementation can be found here.

The Position class also provides functions for determining if a Unit can move freely between two Positions, very important for determining valid moves in the current state.

Movement

A Movement provides details on moving a Unit around the board, or introducing a new Unit to the board.

  • .move(unit:to:) specifies instructions for moving a Unit to a Position
  • .place(unit:at:) specifies instructions for placing a Unit at a Position
  • .yoink(pillBug:unit:to:) specifies instructions for moving a Unit through the use of a Pill Bug to a Position
  • .pass specifies a non-movement, only available when a player has no other moves.

GameState

The GameState is the structure which manages the overall state of a game of Hive.

Get started by creating an instance: let state = GameState()

Options

By default, a GameState will create a basic game with no additional options. You can enable expansion pieces and common unofficial rules through GameState.Options, as well as performance enhancements.

Provide a set of GameState.Options to the GameState(options:) constructor to change which options you have enabled.

API

You can enumerate all the current moves available with availableMoves.

To update the GameState with a given move, call apply(_:) which will mutate the state in place. If you want to explore various Movements, you can undo a move with undoMove()

For better performance, you can disable move validation with GameState.Options.disableMovementValidation.


Installation

Swift Package Manager

This package is built with Swift Package Manager, so you can require it as a dependency in your Package.swift file:

    dependencies: [
        .package(url: "git@github.com:josephroquedev/hive-engine.git", .branch("master"))
    ],

Optionally, you can lock the engine to a specific version with:

    dependencies: [
        .package(url: "git@github.com:josephroquedev/hive-engine.git", from: "2.0.0")
    ],

See the Releases for the most recent release.

Manual

To install manually, simply drag and drop HiveEngine.xcodeproj into your Xcode project.

Requirements

  • Swift 5.0+

Contributing

  1. Write your changes and make sure you test them! This engine boasts nearly 100% code coverage and expects precise conformance to the rules of the game.
    • swift test
  2. Install SwiftLint for styling conformance:
    • brew install swiftlint
    • Run swiftlint from the root of the repository.
    • There should be no errors or violations. If there are, please fix them before opening a PR.
  3. Open a PR with your changes 👍
  4. CI will run your changes and ensure they build and pass all tests on Linux and macOS

Github

link
Stars: 4
Help us keep the lights on

Dependencies

Releases

2.0.0 - May 7, 2019

  • Added a new .pass Movement for players who become shut out and unable to make any other moves
  • lastMovedUnit and lastMovedPlayer added as convenience accessors
  • availableMoves is cached after its first calculation, for improved performance. It is cleared when a move is applied or undone
  • 3 new GameState.Options:
    • restrictedOpening: limits Black's first move to a single position, to reduce branching
    • noFirstMoveQueen: optional rule, prevents either play from playing their Queen as their first piece
    • allowSpecialAbilityAfterYoink: enable using the Pill Bug's ability immediately after the ability has been used on it.
  • Passing perft tests

Breaking changes

  • Removed requireMovementValidation accessor, replaced by GameState.Options.disableMovementValidation
  • Renamed moves(as:in:) to canCopyMoves(of:in) to reduce ambiguity with method bearing a similar name
  • Removed opponentMoves due to the additional complexity required to maintain its functionality
  • A shut out player is no longer skipped. Instead, they have only 1 available move, .pass, and must play it

1.2.0 - Apr 27, 2019

  • Add support for standard Hive notation
  • Limit the pieces playable from hand to be only the unit of each class with the lowest index. For example, with 3 ants with indices 1, 2, and 3, only the ant with index 1 can be placed. After it is placed, only the ant with index 2 can be placed, etc.

1.1.0 - Apr 2, 2019

Human readable encodings for Movements for ease of debugging.

1.0.0 - Mar 31, 2019

With the release and support of Swift 5.0, the engine now appears stable.

The Hive Engine version 1.0 is capable of tracking the state of a game of Hive with the 3 official expansions included.