NonoSharp

A Nonogram API built with C# featuring support for randomly generated puzzles and saving/loading pre-made puzzle solutions.

Status: Published on NuGet as an initial development release (v0.*.*).

Example of a project built on top of NonoSharp, NonoSharp-Maui.

What is NonoSharp?

NonoSharp is an API for C#, together with an example UI consumer, allowing for easy creation and playing of Nonogram (also known as Picross) puzzles. Nonograms are Japanese puzzles where you fill in a picture based on hints given to you. The hints, either on the left-side or top-side of the grid, show how many groups there are in a given row/column and show how many cells each group consists of. By filling the grid one cell at a time, eventually you reach the solution.

Features

• A fully functional Nonogram game, complete with hint checking
• An API allowing for game logic to be reused in other projects
• Randomly generated puzzles guaranteed to be uniquely solvable as verified by the built-in solver
• Cross-platform UI built with MAUI
• Saving and loading solutions to/from custom file format

Using the API

Since the core logic is separate from the UI, it can be reused in other projects. To add the API to your project, you can install it from NuGet, for example by running the following command. This will install the latest version and add it to your project.

dotnet add package NonoSharp

Currently supported functions include:

• Abstracted grid, making it easy to implement in your projects
• Built-in undo/redo functionality
• Checking whether the puzzle is solved
• A hint system, together with whether a hint is completed by the user.
• Events for cells changing states and the puzzle being solved correctly
• Generating random uniquely solvable puzzles
• Loading and saving puzzles to a custom file type

Documentation

Documentation for the API is found on this repo's GitHub pages, here.

Example usage

using NonoSharp;
using NonoSharp.Events;
 
// Creates a new random 10x10 puzzle. Generation is guaranteed to produce a solvable puzzle.
// This method is also available asynchronously via NonogramAPI.CreateRandomPuzzleAsync
var game = NonogramAPI.CreateRandomPuzzle(10, 10); // (width x height)
 
// Fill in or cross a cell (coordinates are zero-indexed, (0, 0) is top-left)
game.FillCell(2, 3);
game.CrossCell(0, 0);
 
// Moves can be undone/redone
if (game.CanUndo)
{
    game.Undo();
}
 
// Check individual cell state
bool isFilled = game.IsCellFilled(2, 3);
 
// Check overall progress
if (game.IsPuzzleSolved())
{
    Console.WriteLine("Solved!");
} 
else 
{
    Console.WriteLine("Not solved :(");
}

 
// The hints shown alongside the grid (e.g. "3 1" for a row) are available for building your own UI
Hints[] columnHints = game.ColumnHints;
Hints[] rowHints = game.RowHints;

// There are also some events provided
game.CellStateChanged += (s, e) => {
    Console.WriteLine("A cell has changed states");

    // Include using NonoSharp.Events to gain access to the event args
};

Getting Started

Playing

To play a Nonogram game built on top of NonoSharp, install the beta release for Windows in the Releases tab of the NonoSharp-Maui GitHub Repo, or create your own!

Contributing

To contribute, clone the project and open it in your prefered IDE, such as Visual Studio. The project makes use of .NET 10.0.

Building the project

After setting everything up, you can follow the regular workflow for building .NET projects:

dotnet build

This will build the API project and the unit tests.

If you wish to build just the API, run

dotnet build src/NonoSharp/NonoSharp.csproj

Of course, you are also welcome to use your IDE's debugger to build the project.

Unit tests

The API project is paired with a test suite found in tests/NonoSharp.Tests. To run the tests, either use your IDE's unit testing features or run the following:

dotnet test tests/NonoSharp.Tests/NonoSharp.Tests.csproj

When contributing, please ensure that the unit tests all pass. These will also be checked when opening a pull request.

Roadmap

Features that are currently planned to be added (in no particular order):

• Random puzzle generation that have a guaranteed solution
• Automatically cross the remaining blank cells upon line completion
• Support for pre-made puzzles
• Player-created puzzles and puzzle creator
• Settings for consumers, such as toggling auto crosses or enabling automatic correction when a cell was filled incorrectly
• Optimise Solver used for random puzzle generation and make it available publicly
• Convert pictures to Nonograms
• Getting hints when stuck solving a puzzle

Contribution guidelines

This project started as a solo learning project, but contributions are welcome. Please open a PR or an issue if you wish to contribute.

When submitting a pull request, please make note of the following:

• Keep PRs focussed
• If you make any changes to the logic, ensure that the tests verify
• Make sure the project builds and functions as intended
• Keep code documented
• Try to keep AI generated code at a minimum

License

This project is licensed under the MIT License. See the LICENSE file.