working game, needs some touch up
This commit is contained in:
168
README.md
Normal file
168
README.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Shikaku — Native NixOS Puzzle Game
|
||||
|
||||
A fully offline, ad-free [Shikaku](https://en.wikipedia.org/wiki/Shikaku) rectangle
|
||||
puzzle game. Built with Python + GTK4. Packaged to nixpkgs standards.
|
||||
|
||||
## What is Shikaku?
|
||||
|
||||
Divide the grid into rectangles. Each rectangle must:
|
||||
- Contain **exactly one** number clue
|
||||
- Have an **area (in cells) equal to that number**
|
||||
|
||||
All puzzles are procedurally generated and guaranteed solvable — the generator
|
||||
works backwards, partitioning the grid into valid rectangles first and then
|
||||
placing clue numbers, so every puzzle has a solution by construction.
|
||||
|
||||
## Controls
|
||||
|
||||
| Action | Input |
|
||||
|---------------------|----------------------------------|
|
||||
| Draw a rectangle | Click and drag across cells |
|
||||
| Erase a rectangle | Right-click any cell inside it |
|
||||
| Check your solution | Click **Check** |
|
||||
| New puzzle | Click **New Puzzle** |
|
||||
| Clear all | Click **Clear** |
|
||||
|
||||
## Puzzle sizes
|
||||
|
||||
| Size | Status |
|
||||
|-------|--------|
|
||||
| 5×5 | ✅ |
|
||||
| 7×7 | ✅ |
|
||||
| 10×10 | 🔜 |
|
||||
| 15×15 | 🔜 |
|
||||
| 20×20 | 🔜 |
|
||||
| 25×25 | 🔜 |
|
||||
|
||||
---
|
||||
|
||||
## Using the package locally (before it lands in nixpkgs)
|
||||
|
||||
### Quick test with nix-build
|
||||
|
||||
Copy the `pkgs/by-name/sh/shikaku/` directory into your local nixpkgs checkout,
|
||||
then from the nixpkgs root:
|
||||
|
||||
```bash
|
||||
nix-build -A shikaku
|
||||
./result/bin/shikaku
|
||||
```
|
||||
|
||||
### Install into your profile
|
||||
|
||||
```bash
|
||||
nix-env -f '<nixpkgs>' -iA shikaku
|
||||
```
|
||||
|
||||
### In your NixOS `configuration.nix` (via an overlay)
|
||||
|
||||
```nix
|
||||
nixpkgs.overlays = [
|
||||
(final: prev: {
|
||||
shikaku = final.callPackage /path/to/pkgs/by-name/sh/shikaku/package.nix { };
|
||||
})
|
||||
];
|
||||
|
||||
environment.systemPackages = [ pkgs.shikaku ];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Submitting to nixpkgs
|
||||
|
||||
### File layout (already correct for the PR)
|
||||
|
||||
```
|
||||
pkgs/by-name/sh/shikaku/
|
||||
├── package.nix ← the derivation
|
||||
└── shikaku.py ← the game source (single file)
|
||||
```
|
||||
|
||||
The `pkgs/by-name` directory is automatically wired into nixpkgs — no edits to
|
||||
`all-packages.nix` are needed. The package attribute `pkgs.shikaku` is created
|
||||
automatically from the directory name.
|
||||
|
||||
### Steps before opening the PR
|
||||
|
||||
1. **Host the source.** Push this repo to GitHub (or another forge). The
|
||||
`src.rev` and `src.hash` in `package.nix` must point to a real tagged commit.
|
||||
Get the hash with:
|
||||
```bash
|
||||
nix-prefetch-url --unpack https://github.com/YOU/shikaku/archive/v0.1.0.tar.gz
|
||||
# or with the newer tooling:
|
||||
nix store prefetch-file --hash-type sha256 --unpack \
|
||||
https://github.com/YOU/shikaku/archive/refs/tags/v0.1.0.tar.gz
|
||||
```
|
||||
|
||||
2. **Add yourself as a maintainer.** Edit `maintainers/maintainer-list.nix` in
|
||||
nixpkgs to add your handle, then reference it in `package.nix`:
|
||||
```nix
|
||||
maintainers = with lib.maintainers; [ your-handle ];
|
||||
```
|
||||
|
||||
3. **Build and run locally** from the nixpkgs root:
|
||||
```bash
|
||||
nix-build -A shikaku
|
||||
./result/bin/shikaku
|
||||
```
|
||||
|
||||
4. **Check nixpkgs-vet passes** (CI runs this automatically, but you can run it
|
||||
locally too):
|
||||
```bash
|
||||
nix-build pkgs/top-level/release.nix -A tarball.nixpkgs-basic-release-checks \
|
||||
--arg supportedSystems '["x86_64-linux"]'
|
||||
```
|
||||
|
||||
5. **Open the PR** with the commit message format nixpkgs expects:
|
||||
```
|
||||
shikaku: init at 0.1.0
|
||||
```
|
||||
Include in the PR description:
|
||||
- A screenshot of the game running
|
||||
- Link to the upstream source
|
||||
- Confirmation it builds on x86_64-linux (and aarch64-linux if you can)
|
||||
|
||||
### nixpkgs reviewer checklist (pre-answered)
|
||||
|
||||
| Requirement | Status |
|
||||
|---|---|
|
||||
| `pkgs/by-name/sh/shikaku/package.nix` | ✅ |
|
||||
| `pname` lowercase, no spaces | ✅ `"shikaku"` |
|
||||
| `version` present | ✅ |
|
||||
| Source from `fetchFromGitHub` with pinned `rev` and `hash` | ✅ (fill in hash) |
|
||||
| `meta.description` — short, no trailing period | ✅ |
|
||||
| `meta.license` | ✅ `lib.licenses.mit` |
|
||||
| `meta.maintainers` | ⚠️ add yourself |
|
||||
| `meta.homepage` | ⚠️ add your repo URL |
|
||||
| `meta.platforms` | ✅ `lib.platforms.linux` (GTK4, Linux only) |
|
||||
| `meta.mainProgram` | ✅ `"shikaku"` |
|
||||
| `wrapGAppsHook4` for GTK4 app | ✅ |
|
||||
| `gobject-introspection` in `nativeBuildInputs` | ✅ |
|
||||
| No `flake.nix` in the package dir | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## How puzzle generation works
|
||||
|
||||
Puzzles are generated in reverse, guaranteeing solvability:
|
||||
|
||||
1. The full grid is **partitioned into random non-overlapping rectangles**
|
||||
(every cell belongs to exactly one rectangle, no gaps).
|
||||
2. Each rectangle gets **one randomly chosen clue cell**, with the rectangle's
|
||||
area written as the number.
|
||||
3. The player sees only the clue numbers and must reconstruct the rectangles.
|
||||
|
||||
Because the rectangles are generated first and clues derived from them, every
|
||||
puzzle is solvable by construction. There is no backtracking solver needed.
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Why |
|
||||
|---|---|
|
||||
| `python3` | Runtime |
|
||||
| `pygobject3` | GTK4 Python bindings |
|
||||
| `gtk4` | GUI toolkit |
|
||||
| `gobject-introspection` | Required at build time for PyGObject |
|
||||
| `wrapGAppsHook4` | Wraps binary with correct GDK/GI env vars at runtime |
|
||||
|
||||
All managed by Nix — nothing to install manually.
|
||||
Reference in New Issue
Block a user