Asciicker Y9 Fork

Asciicker is a C++ ASCII/CP437-styled 3D game/editor engine with native, terminal, and web targets, plus a Python-based asset pipeline for .xp sprites and Blender integration.

This README is intentionally concise and command-accurate. Deep architecture and subsystem details live in docs/INDEX.md.

Lineage

This repository is derived from msokalski/asciicker.

If you want to track upstream locally:

git remote add upstream https://github.com/msokalski/asciicker.git

Quick Start

Build everything:

./build.sh

Run main binaries:

./.run/game
./.run/asciiid
./.run/server
./.run/game_term

Build individual targets:

make -f makefile_asciiid      # editor
make -f makefile_game         # game
make -f makefile_server       # server
make -f makefile_game_term    # terminal game

Web build:

./build-web.sh

Clean intermediates:

./clean.sh

Python Tooling Quickstart

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Asset pipeline entrypoint:

python3 -m scripts.asset_gen --help

Interactive asset wizard:

python3 -m scripts.asset_gen --wizard

XP editor (GUI/Tkinter):

python3 -m scripts.asset_gen.xp_tool sprites/player-nude.xp

REXPaint MCP server:

python3 scripts/rex_mcp/server.py

Wizard MCP bridge:

python3 scripts/wizard_mcp_server.py

Minimap CLI

Render a terminal minimap from any .a3d file without starting the editor:

# From project root or agent-harness/:
python3 agent-harness/minimap_render.py                        # default map, center (0,0)
python3 agent-harness/minimap_render.py --cx 100 --cy -50     # center on position
python3 agent-harness/minimap_render.py --map a3d/other.a3d   # specify map file
python3 agent-harness/minimap_render.py --scale 16 --width 60 # zoom/size

# Marker editing
python3 agent-harness/minimap_render.py add-marker SAC 0 -50
python3 agent-harness/minimap_render.py add-marker Town 10 30 --type region --glyph T
python3 agent-harness/minimap_render.py remove-marker SAC
python3 agent-harness/minimap_render.py list-markers

python3 agent-harness/minimap_render.py --help

Markers are stored in .minimap_markers.json at the project root. The render_minimap_from_a3d() function is also importable from agent-harness/cli_anything/asciiid/core/minimap.py and exposed as the render_minimap tool in the asciicker-dev MCP server.

ASCIIID MCP Mode

Run editor in MCP mode:

./.run/asciiid --mcp

Example:

printf 'ECHO hi\nSET_TERRAIN_HEIGHT 4096\nRENDER\nQUIT\n' | ./.run/asciiid --mcp

Implemented commands in asciiid.cpp:

• ECHO <text>
• QUIT
• RENDER
• DUMP_MATRIX
• PLACE_MESH <path> <x> <y> <z> <scale>
• LOAD_SPRITE <path>
• SET_ACTIVE_SPRITE <name|path>
• PLACE_SPRITE <path> <x> <y> <z> <yaw> [anim] [frame]
• PLACE_SPRITE_ACTIVE <x> <y> <z> <yaw> [anim] [frame]
• PLACE_SPRITE_ACTIVE_REL <dx> <dy> <dz> <yaw> [anim] [frame]
• SET_TERRAIN_HEIGHT <h>
• PROBE_TERRAIN <x> <y> (currently approximate patch-level height probe)
• GET_CAMERA
• SET_CAMERA <x> <y> <z> <yaw> <pitch> (currently applies position + yaw; pitch argument is reserved)
• FOCUS_ORIGIN
• DEBUG_AXIS
• LIST_INSTANCES
• SET_GRID <alpha>
• LOAD_MAP [path] (loads .a3d map; defaults to a3d/game_map_y8.a3d)

Testing and Verification

General verification:

python3 scripts/verify.py

Blender-focused tests:

python3 scripts/test_blender.py

End-to-end export + game driver verification:

python3 scripts/verify_e2e.py

Repository Layout

• Core engine/editor/server C/C++ sources: repo root (*.cpp, *.h)
• Build outputs: .run/
• Build intermediates: .o_*, .d_*
• Assets: sprites/, meshes/, fonts/, palettes/, a3d/, images/, icons/, samples/
• Blender addons/tools: io_asciicker/, io_mesh_akm/, io_scene_a3d/, io_scene_a3d_tools/
• Python tooling and automation: scripts/
• Technical documentation index: docs/INDEX.md

Documentation

Start with:

• docs/INDEX.md
• docs/ARCHITECTURE.md
• docs/AGENT_PROTOCOL.md
• docs/DEV_QUICKSTART_NOOBS.md
• docs/TESTING_GUIDE.md
• docs/MCP_SETUP.md
• docs/ASSET_PIPELINE.md
• docs/ASCIID_CODE_GUIDE.md
• docs/RENDER_PIPELINE_DETAILED.md

Contributing

Use Conventional Commits with scope:

feat(editor): add multi-tile brush
fix(game): clamp camera pitch
docs(render): clarify resolve stage

Keep changes focused, include test evidence where possible, and separate code changes from large asset drops when practical. Follow vibe coding etiquette and best practices (git ignore agent files, human code audit, proper code slop management ) See northstar backlog roadmap in the docs for ongoing task list before making any PR's.

License

See LICENSE and upstream licensing context.