# wha-spell-simulator stops at a second ring instead of guessing an element

> A browser prototype that turns a freehand ring into GlyphAST and SpellIR output, and refuses to soften the rules: one enclosing ring, one primary sigil, and no fallback element when a diagram closes but fails to validate. Interesting as a parser to read, unreliable as a spell maker.

**ytnrvdf/wha-spell-simulator** — A fan-made browser-based Witch Hat Atelier spell simulator.

- Repository: https://github.com/ytnrvdf/wha-spell-simulator
- Website: https://ytnrvdf.github.io/wha-spell-simulator/
- Stars: 891 · Forks: 103
- Language: JavaScript
- License: MIT
- Published: 2026-09-18 · Updated: 2026-09-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/ytnrvdf-wha-spell-simulator

## One ring, one primary sigil, and no consolation element

Recognition runs in strict layers. The app looks for one enclosing ring and uses it to tell a prepared spell from an active one. Inside that ring it looks for a primary sigil backed by the dictionary, which is where fire, water, wind, earth and light come from. Around the sigil, signs adjust direction, levitation, convergence, force, spread, focus, range, duration and stability. Nine signs, five elements, one ring, and that is the whole parseable surface.

The failure policy is the part worth studying. A second ring is detected as unsupported. A second primary sigil is detected as unsupported. Neither case degrades into the nearest match. A diagram that closes its ring but fails validation can still surface diagnostics, and the compiler does not reach for a different element as a consolation prize. Plenty of drawing tools guess quietly because guessing feels friendlier. This one tells you the shape was wrong.

## npm start is a two hop alias to a loopback Vite server

The scripts block in package.json holds four lines, and the entry point the project documents is the second one. `npm start` starts nothing itself, it runs `npm run dev`, which runs `vite --host 127.0.0.1 --port 5173`. The loopback bind is why the local address is 127.0.0.1 rather than a hostname, and why nothing off the machine can reach the dev server while it is up.

Install first:

```sh
npm install
```

Then start it:

```sh
npm start
```

Then open:

```txt
http://127.0.0.1:5173/
```

The `build` script runs `vite build`, and no documented step walks through it, so the production path stays inferred. One script is documented and worth knowing, because it shows how little machinery is installed: the suite runs on Node's own test runner over the tests directory, and the sole devDependency is Vite at `^6.4.0`.

```sh
npm test
```

No test framework appears in devDependencies, so `node --test tests` is used directly.

## Stroke templates decide what a letter is, and a photo cannot supply them

Recognition runs on local stroke templates, which means the recognizer cares about how the pen moved rather than what the finished drawing resembles. That one choice explains most of the limits listed together later: clean deliberate strokes score best, some valid looking drawings fail to match outright, and rough ones want redrawing before anything parses.

A raster image can sit on the canvas as a visual reference and it will not help the parser at all, because stroke order cannot be recovered from a flat bitmap. The order in which a sigil is drawn is part of its identity here, and a scan of a page has already discarded that. So a photographed diagram is a target to copy by hand, never an input the compiler can read.

The project ships the tooling for working on the templates rather than guessing at them, and these are the four pages the README points at:

```txt
/tools/strokeTemplateMaker.html
/tools/strokeTemplateViewer.html
/tools/sigilSignDetectorLab.html
/tools/spellEffectLab.html
```

Making a template, viewing it, and testing it against strokes are three separate pages. That spread says something about what each new sign costs.

## GlyphAST and SpellIR are two contracts, not one debug dump

Every parse emits three things: diagnostics, a `GlyphAST`, and a `SpellIR`. The project treats the two structured outputs as interfaces worth pinning down, and gives each one a documentation file of its own. `docs/glyph-ast.md` holds the parsed glyph output contract, `docs/spell-ir.md` the compiled spell output contract, and `docs/play-rules.md` the parser and spell semantics rules.

The split is the useful part for anyone planning to build on the parser. The AST records what the recognizer believes it saw, before any spell semantics are applied. The IR is the compiler output, with the element resolved and the signs attached as modifiers of direction, levitation, convergence, force, spread, focus, range, duration and stability. Two stages, two contracts, two files.

The docs directory holds five pages in all, the other three being dictionary authoring and visual effect renderer notes. Rendering sits downstream of both contracts, and its notes live in `docs/effect-rendering.md`, which is a reminder that the canvas animation is a consumer of the IR rather than part of the parse.

## Five elements and nine signs, and a stated ceiling on both

Counting the vocabulary sizes the project faster than any feature list does. Five primary sigils: fire, water, wind, earth, light. Nine signs: direction, levitation, convergence, force, spread, focus, range, duration, stability. One ring. That is the entire surface a drawing can address.

The Dictionary panel holds sample spell layouts, and they are placed there to be looked at rather than run, which makes the panel a drawing reference rather than a catalogue of everything the parser accepts. Extending the vocabulary is documented work instead of a config edit: dictionary authoring has its own page, and the stroke templates behind a new sigil have to be made and tested in the lab before the compiler will ever see that symbol.

The author is explicit that the dictionaries only cover a small fan made subset of sigils, signs and observed spell ideas. Read a failed match in that light. It is the stated size of a fan project that started from a manga and reverse engineered the magic into something a browser canvas can hold, not a regression waiting for a bug report.

## Version 0.1.0, no releases, and a maintenance promise already declined

The package sits at version 0.1.0 with `private: true`, so it was never meant to reach a registry, and the repository has no GitHub releases at all. The archive flag is off, and the last commit landed on 31 May 2026, roughly four months before this was assembled.

More telling is the Project Status section, where the question is settled before anyone asks it: this is an experimental prototype, issues and pull requests get reviewed when there is time, and there is no commitment to long term maintenance. The same section points faster movers at forking, and warns that community forks can drift away from the original version. Community work is credited to @cosykid, who helped start the community Discord, and a video link sits near the top with no description of what it shows.

An open invitation to fork next to a refusal to promise a roadmap is the actual governance model here. Plan to read the source and run your own copy rather than waiting on upstream.

## MIT covers the pipeline, not the sigils

The license file is MIT. The fan project notice beside it is narrower and more careful: the project is unofficial, is not affiliated with, endorsed by, or sponsored by the creators, publishers, licensors or production partners of Witch Hat Atelier, and the names, artwork, symbols and trademarks belong to their respective rights holders. The sigils, signs, spell terminology and visual effects are described as partial fan references and interactive interpretations, not official assets or canonical rules.

The same restraint carries into the rendering. The animated effects are interpretive canvas animations, and the project states plainly that they are not a faithful reproduction of manga or anime effects. Nothing in the code claims to reproduce the source material.

That split is the cleanest licensing posture a project of this kind can have. The MIT grant covers the recognizer, the compiler and the canvas work. The fiction stays with its rights holders, and the pipeline stays useful to anyone willing to write their own dictionary.

## Conclusion

wha-spell-simulator is worth reading as a stroke template recognizer with a small compiler attached, and it is not a spell maker for anyone who wants their own handwriting understood. Draw slowly and cleanly, stay inside one ring with one primary sigil, and expect a refusal rather than a guess. Before building on the SpellIR, check the dictionary against the spells you care about, since five elements and nine signs is the whole vocabulary. And treat the hosted demo, not the repository, as the only thing with a fixed address.

## FAQ

### What is wha-spell-simulator?

A fan made, browser based spell drawing simulator inspired by Witch Hat Atelier. You draw a freehand diagram on a paper-like canvas, the app parses it into diagnostics, a GlyphAST and a SpellIR, and the compiled behavior drives animated element effects. It is an unofficial project with no affiliation to the creators.

### How do I run wha-spell-simulator on my own machine?

Run `npm install`, then `npm start`, then open http://127.0.0.1:5173/. The start script hands off to the Vite dev server on 127.0.0.1 port 5173, bound to loopback, so no other machine on the network can reach it while it runs.

### Which elements and signs does wha-spell-simulator know?

Dictionary-backed primary sigils exist for fire, water, wind, earth and light. Signs modify direction, levitation, convergence, force, spread, focus, range, duration and stability. The dictionaries cover only a small fan made subset of sigils, signs and observed spell ideas.

### Can wha-spell-simulator read a spell diagram from a photo?

Not as parser input. Raster images can be used as visual references, but true stroke order cannot be recovered from an image, and recognition is based on local stroke templates. A scan helps you redraw the sigil by hand; it does not feed the compiler.

### What happens if I draw two rings or two primary sigils in wha-spell-simulator?

Both are detected as unsupported. The app supports one enclosing spell ring at a time and the compiler expects one primary sigil, and a closed but invalid diagram can show diagnostics without falling back to another element.

### How are the wha-spell-simulator tests run?

With `npm test`, which runs `node --test tests`. No test framework is declared in devDependencies; the only declared dependency is Vite, and the suite uses the Node test runner directly against the tests directory.

## Sources

- [Issues](https://github.com/ytnrvdf/wha-spell-simulator/issues)
- [License: MIT](https://github.com/ytnrvdf/wha-spell-simulator/blob/main/LICENSE)
- [Project website](https://ytnrvdf.github.io/wha-spell-simulator/)
- [README](https://github.com/ytnrvdf/wha-spell-simulator/blob/main/README.md)
- [ytnrvdf/wha-spell-simulator on GitHub](https://github.com/ytnrvdf/wha-spell-simulator)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ytnrvdf-wha-spell-simulator