Repository: olistic/warriorjs

Stars: 9510

CLAUDE.md Copy Chapter

WarriorJS

A game that teaches JavaScript and TypeScript through interactive coding challenges. Players write code to control a warrior navigating through towers full of enemies.

Commands Copy Chapter

pnpm install        # Install dependencies
pnpm build          # Build all packages (Turborepo handles ordering)
pnpm test           # Run all tests
pnpm lint           # Check linting/formatting (Biome)
pnpm lint:fix       # Auto-fix linting/formatting

Run a single package's tests: npx vitest run apps/cli/

Architecture Copy Chapter

pnpm monorepo with Turborepo. Code is organized into three top-level directories:

- apps/ — End-user applications
- @warriorjs/cli — CLI for offline play
- libs/ — Shared libraries
- @warriorjs/core — Game engine, level runner, player code loader
- @warriorjs/abilities — Warrior abilities (walk, attack, feel, etc.)
- @warriorjs/units — Game units/enemies
- @warriorjs/effects — Status effects system
- @warriorjs/spatial — Spatial/direction utilities (foundational, no deps)
- @warriorjs/scoring — Score calculation and grade letters
- towers/ — Built-in tower definitions
- @warriorjs/tower-the-narrow-path / tower-the-powder-keep — The Narrow Path and The Powder Keep

Dependency flow: spatial → abilities → units → towers, spatial → core → scoring → cli.

Each package compiles with tsc to dist/.

Conventions Copy Chapter

- Biome enforces formatting and linting — don't manually fix style, run pnpm lint:fix
- Lefthook pre-commit hook auto-formats staged files
- All imports use .js extensions (ES modules with NodeNext resolution)
- Tests live next to source: src/Foo.test.ts
- Coverage thresholds: 80% (lines, functions, branches, statements)
- Conventional Commits with scope: feat(cli): add language choice, fix(core): handle edge case

README.md Copy Chapter

<div align="center">
<a href="https://warrior.js.org">
<img alt="WarriorJS Banner" title="WarriorJS" src="logo/warriorjs-banner-dark.png?raw=true">
</a>
</div>

<br />

<div align="center">
<strong>Learn JavaScript and TypeScript by writing code that fights</strong>
</div>

<br />

<div align="center">
<a href="https://github.com/olistic/warriorjs/actions/workflows/ci.yml">
<img alt="CI" src="https://img.shields.io/github/actions/workflow/status/olistic/warriorjs/ci.yml?branch=master&style=flat-square">
</a>
<a href="https://codecov.io/gh/olistic/warriorjs">
<img alt="Codecov" src="https://img.shields.io/codecov/c/github/olistic/warriorjs.svg?style=flat-square">
</a>
</div>

<br />

In WarriorJS, you write JavaScript or TypeScript to guide a warrior through
towers full of enemies. Each floor is a puzzle: battle sludge, dodge archers,
rescue captives, and reach the stairs alive. The code you write _is_ the
strategy — there's no clicking, no dragging, just logic and sharp thinking.

Whether you're writing your first if statement or refactoring for a perfect
score, every floor will test you.

Quick Start Copy Chapter

1. Install Node.js 22 or later.

2. Install the CLI:

npm install --global @warriorjs/cli

3. Launch the game:

warriorjs

The game walks you through creating a warrior and choosing a tower. Open the
generated README.md for your first level's instructions, write your solution
in Player.js, then run warriorjs again to see how your warrior fares.

You can also play from your browser at
warriorjs.com.

Documentation Copy Chapter

The official docs cover everything from first steps
to building your own towers:

- Gameplay
- Towers
- Player API

Contributing Copy Chapter

The best way to contribute is to build a
tower — a set of levels that
other players can install and play.

You can also fix bugs, improve the docs, or add new abilities and units.
See the contribution guide and
Code of Conduct.

Acknowledgments Copy Chapter

This project was born as a port of
ruby-warrior. Credits for the original
idea go to Ryan Bates.

Special thanks to Guillermo Cura for designing
a wonderful logo.

License Copy Chapter

WarriorJS is licensed under a MIT License.