ATTENTION: FlyingFathead/c64-3d-toolkit is the one and only official, original source for
c64-3d-toolkit. Steer clear of other sources or repositories claiming to be the official project.
New HORS-V4 builds default to EasyFlash.
GMod3 remains available through --cart-type gmod3, --renderer hors-v4-gmod3,
or an explicit config preference. GMod4 remains on the roadmap.
The existing V5 is now V5-c1 (--renderer hors-v5-c1); hors-v5 still selects
c1. Opt-in V5-c2 adds per-animation colour-transport selection to V5 clearing.
Candidate details and comparisons ·
V5-c1 and private comparison workflow ·
HORS-V1 through V5 comparisons.
The full renderer history benchmark includes
the original step, bytechunk, yunroll, streamed and authored-scene variants.
The optimizer-profiler measures fixed-picture full-history
build choices and reports colour mapping separately from cell conflicts.
Release notes and validation · All fresh family measurements.
The public corpus runner includes the established twelve examples, Stanford Dragon and separate SAKU logo-only versions.
Authored scenes now clip geometry at the camera near plane and viewport.
Objects can pass behind the camera and reappear; fully invisible frames stay
in the timeline. Hidden-line occlusion and source colours follow the clipped
geometry. One summary reports clipping; --ignore-warnings suppresses it.
--blender-color-space linear|srgb selects how material numbers are interpreted.
The default remains linear. For imported numbers already stored as sRGB:
python c643d.py build --blend scene.blend --blender-color-space srgb
python c643d.py --configure-blender-color-space srgbOmit the configuration value for an interactive chooser. Explicit C64 material indices and the shared palette mapper are preserved.
Stale root monitor.log files are automatically copied, verified and archived
under logs/ with unique timestamps. VICE launchers select log destinations
before enabling logging. Log maintenance and tracked-log cleanup.
Camera-crossing example · Colour-space details · Recovery verification · Numbered checkpoint workflow
Download Demo Cart v3.1: GMod3 All-in-One. Includes all demos from the previous examples through v0.7.9: 58 selectable entries and 6,474 pictures. The full SAKU interactive baseline is now visible in two-page help, including Shift+I / Shift+F / Shift+U HUD controls. SPACE or Enter starts the selected demo; Shift+H works from the main menu too. RUN/STOP (Esc in VICE) or F1 returns to the menu from playback, help, exhibition and slow playback, including while a speed key is held. Stars start disabled, including after reset.
Matched PAL VICE A/B across all 58 entries measures a median 0.24% reduction in average FPS, with a maximum 0.39% reduction; the largest absolute loss is 0.146 FPS. Three entries tie. All highs, averages, lows and method. The automatic v3.0 benchmark cartridge remains byte-identical and its menus were checked separately.
Root Windows/Linux installers now install the full Python build requirement
set. Missing libraries produce a short explanation and repair commands.
python c643d.py --help lists all build options; --help-all covers every command.
Normal builds use automatic, non-interactive HORS-V4/EasyFlash playback;
--interactive-cart enables controls for supported object/SVG spins.
Install or repair · Release and verification · CLI guide · Blender colour calibration
Demo Cart v3.0: GMod3 All-in-One fits 58 selectable demo entries and 6,474 pictures in one 16 MiB cartridge, with 2,936 KiB free. Includes SAKU, all six Dragon variants, Sande's models, the original demos, Demo Cart 2.0 and the complete 640-picture Marbles sequence. Includes all demos from the previous examples through v0.7.9. Stars start off; help, HUD, speed, colour, starfield and exhibition controls remain available. An automatic benchmark companion is included. RUN/STOP (Esc in VICE) returns to the collection menu; Shift+H opens help.
HORS-V4 (hors-v4, also hors-renderer-v4) is the default renderer. New builds
default to EasyFlash; independent GMod3 processing and runtime modules remain
available with --cart-type gmod3 or --renderer hors-v4-gmod3.
The V3 picture core and all existing EasyFlash backend/cartridge bytes are preserved.
Use --renderer hors-v4-ef to select EasyFlash explicitly. GMod3 VICE 3.10
playback is verified; physical devices must support the GMod3 mapper and the
16 MiB image. Compatibility and EasyFlash fallback.
Across 69 matched PAL VICE workloads: 65 higher average frame rates, four ties, zero lower averages. Gains reach +0.397 FPS, with no increase in mean active rendering cycles. The four SAKU crawl variants tie; solid crawl reaches the PAL display limit. These measurements support a modest speed improvement and much larger collections, not a universal +1 FPS claim or a physical-hardware guarantee.
Performance tables and raw evidence · Release, install and reproduce · GMod3 specification and limits · Set your cartridge default
 |
 |
| The Golden Dragon | SAKU 2026 — interactive |
SAKU: official home page · Saku magazine
The 0.7.9 release introduced HORS-V3 as the normal conversion path. Choose
nearest-palette material/image colours, every native hue family, or your own
metallic gradient with --surface-ramp brown,orange,yellow,white.
SVG builds preserve mapped fills and strokes and fit proportionally; --fill-style gradient adds Dragon-style colour ramps. Explicit outline, diagnostic and single-colour switches are available. The SAKU interactive cart starts with gradients and stars, with speed controls and a complete key map.
New interactive builds retain the original intro and wait for SPACE, with press SHIFT+H for help on the row above. They have RUN/STOP (Esc in VICE) or Shift+H help, plus + / - / 0 speed controls. Stars start disabled unless --starfield-default enabled is set; --no-starfield excludes their code and data entirely. SAKU explicitly enables the light field (--starfield-profile light); the full field remains available with 4. --hide-hud starts with all HUD text hidden; Shift+I / Shift+F / Shift+U toggle the name/counts, FPS/speed feedback, or all HUD text including INTERACTIVE. Star density uses 1 = reset, 2 = more, 3 = less; 4 switches original light / full stars, preserving each density and the on/off state. Latest correction notes and interactive options and implementation cover startup visibility and --no-hud-toggle.
Interactive help now has two pages, navigated with left/right. 5 toggles exhibition, 6 selects ordered/random styles, and 7/8 adjusts the five-second interval. Exhibition starts with HUD/stars off and preserves manual star choices across scene changes. Exhibition controls and CLI defaults.
V3 can compact fragmented clear/colour metadata without discarding geometry, pixels or animation samples. Blender cache diagnostics now explain missing files and unsupported Alembic builds.
SVG paint and gradients · Starfield and speed controls · Release notes and installation · Colours, gradients and Blender cache guide
Five HORS-V3 demo carts bring Stanford's 5,205-vertex / 11,102-triangle Dragon to the C64: wireframe, metallic (grey), red, green and blue. The showcase above presents one complete rotation of each, in that order, with the measured PAL playback timing.
At v0.7.9, HORS-V3 became the conversion default for objects and authored wireframe scenes. Surface shading supports every native colour family plus custom gradients with --surface-ramp brown,orange,yellow,white. Materials and texture pixels map to the nearest C64 palette colour. Checkpoint guide, colour mapping and cache troubleshooting.
Download the five Dragon carts, watch individual GIFs and see performance · v0.7.8 release notes and installation
Sande's Pretzel introduced HORS-V3's metallic shading, MTL surface colours and image textures, with an optional compact colour dictionary. The GIF shows the metallic (grey) version with direct colour encoding. Separate interactive carts add rotation and background controls.
Play the metallic Pretzel · Try the interactive version · All HORS-V3 examples and controls · v0.7.7 release notes
Older releases and announcements · Full changelog
The footage uses verified completed display buffers captured in PAL VICE 3.10. For the showreel, every authored animation sample is presented on a fixed 25 fps clock instead of inheriting renderer-dependent capture delays; HUD FPS values remain the cartridge's benchmark counters. The reel includes Horse & Sunflower, the HiFi horse head and 243-vertex sunflower, Sande's TAC-2, the complete 1,552-vertex Pretzel wireframe, the HORS-V3 metallic Pretzel, Blender Falling Cubes and every Demo Cart 2.0 scene. The video is silent; the featured cartridges do not share a soundtrack.
HORS-V4 / EasyFlash is the default conversion renderer; use --surface-fill material, textured or metallic to select filled surfaces. The prebuilt cartridges below are ready to run. See cartridge loading and output colours for setup and controls.
Performance tables: Original twelve animations · Demo Cart 2.0: all seven scenes · Sande test kit
| Prebuilt | What is inside |
|---|---|
| Demo Cart v3.1: GMod3 All-in-One | Includes all demos from the previous examples through v0.7.9. 58 interactive entries, stars off, 16 MiB GMod3. Controls and benchmark edition |
| Stanford Dragon: all six looks | HORS-V3 wireframe, metallic (grey), golden, red, green and blue; carts, timed GIFs and performance |
| SAKU 2026 — interactive | SVG source/gradient colours, starfield, spin/crawl, speed controls and keyboard map |
| Metallic Pretzel — interactive | HORS-V3 shaded surfaces, rotation and background controls |
| Sande's Pretzel | Sande's 1,552-vertex knot; left/right rotation and F-key colours |
| Sande's TAC-2 | Sande's joystick model; the same interactive controls |
| Color Combo Test | Four colour pairs, ten seconds each, automatic looping, F3/F4 cycling |
| Twelve-demo cart — FPS | The original twelve animations, menu styles, PLAY ALL, HiFi mode and colour controls |
| Twelve-demo cart — RAM | Same material and colour controls, smaller drawing kernels |
| Demo Cart 2.0 | Colour cube, colour torus, twist tunnel, ribbon dance, orbital cubes, wave lattice and Ripples Lite |
| HiFi reel | Horse & Sunflower followed by two HiFi spinners |
| Marbles | All 640 authored samples, original 16 FPS target, native intro and ending |
| Horse & Sunflower | Authored scene, with a separate RAM build in the same folder |
python c643d.py run-cart examples/gmod3_cart_demos/demo-cart-v3.1-gmod3-all-in-one.crt
python c643d.py run-cart examples/cart_demos/c643d-demo-v0.7.9-hors-render-v2-all.crt
python c643d.py run-cart examples/cart_demos_v2/demo-cart-2-preview-hors-v2.crtUse --vice-clean-settings to try temporary VICE defaults when diagnosing a
loading failure. See cartridge loading for the
standalone VICE command, write-back protection and the loader changes.
For the interactive GMod3 collection, use CURSOR to select and SPACE or Enter to start; RUN/STOP (Esc in VICE) or F1 returns to the menu. Shift+H opens help from the menu or playback. Use the separate automatic edition for benchmarks. The older EasyFlash menus use cursor keys and RETURN; F1 changes styles or returns from playback. Their normal PLAY ALL is the benchmark path; F5 exhibition is excluded from FPS comparisons.
A host-assisted 3D compiler and native C64 renderer: import OBJ, SVG or baked Blender scenes; compute projection and visibility on the host; pack drawing data into a GMod3 or EasyFlash cartridge; let the 6510 update VIC-II bitmaps and colours at runtime. It is not a general live-geometry engine. No cartridge coprocessor is required.
V2 groups literal bitmap spans into bounded cartridge-mapping batches, reducing repeated mapping setup. Every frame is an independent picture. It reuses the vector-dispatch page only after requiring all frames to use direct spans. No extra RAM allocation is introduced by the drawing helper. ROM usage can grow when a measured gap-bridging choice buys higher display throughput.
The stable host encoder also avoids constructing an unused vector stream just to obtain metadata. A large intermediate vector representation therefore does not reject a valid literal picture. Final metadata, frame-bank and cartridge capacity limits still apply; inputs are never silently simplified to fit.
Windows: run setup-windows.cmd; it configures tools and offers to install
all Python build dependencies. To install/repair Python packages only:
py -3 .\setup-python.py
py -3 .\c643d.py dependenciesLinux: use the root installer, then activate its environment:
bash setup-linux.sh
source .venv/bin/activate
python c643d.py dependenciesOn Debian/Ubuntu, bash setup-linux.sh --system-deps also installs the external
C64 tools and native Cairo. --repair reinstalls Python packages in the chosen
environment. Use that same Python for builds. Full installation, native Cairo,
Windows/Linux repair and dependency inventory.
Python 3, 64tass and VICE/cartconv are required for cartridge builds and tests.
Blender is optional for .blend export; shipped example rebuilds use frozen
pictures and do not require Blender or a physics rebake.
python c643d.py doctor
python c643d.py build --shape cube --frames 192
python c643d.py build --object horse_head
python c643d.py build --scene examples/autotune/colour-cube.c643dscene --frame-ticks 1
python c643d.py cart-demos --prefer fps
python c643d.py cart-demos --prefer ram
python c643d.py color-combo-test
python c643d.py build --shape torus --foreground-color black --background-color white --border-color whitebuild and cart-stream default to hors-v4 / EasyFlash, with non-interactive automatic playback.
Object/SVG spins opt into controls with --interactive-cart; authored Blender/scene animation remains automatic.
Stars default to disabled; --starfield-default enabled opts in for interactive builds.
Use python c643d.py --help for all build flags or --help-all for every command.
hors-renderer-v4 and hors-render-v4 remain aliases. Explicit HORS-V3 and older renderers retain
EasyFlash defaults. Set --cart-type or a universal config preference to choose
hardware. cart-demos retains the preserved V2 EasyFlash comparison/menu path.
Use --renderer yunroll explicitly for resident PRG output.
python c643d.py build --shape torus --surface-fill metallic --interactive-cart
python c643d.py build --renderer hors-renderer-v3 --shape torus --surface-fill metallic
python c643d.py run-cart examples/gmod3_cart_demos/demo-cart-v3.1-gmod3-all-in-one.crtGMod3 architecture, image specification, bank timings and limits.
python tools/autotune_scene.py examples/cart_demos_v2/scenes/ripples_lite.c643dscene \
--out ../ripples-v2-search --mono --width 320 --jobs 3 \
--renderers hors-render-v1-scene hors-render-v2 \
--ticks 1 2 3 4 --plans optimized raw --gaps 3 6 10 --batches 1024 2048 \
--tass 64tass --cartconv cartconv --vice ./VICE-BATCH.sh \
--vice-data /usr/local/share/viceGeometry is frozen once. Each candidate is built and checked against the same pictures, then measured in VICE. CLI, Markdown, JSON and CSV reports retain wins, losses, failed candidates, display pacing, stage costs and RAM/ROM allocation components. The search covers its requested candidates; it does not claim a universal maximum. A pacing change is reported separately from a renderer throughput improvement.
cd path/to/c64-3d-toolkit
JOBS=3 VICE_DATA=/usr/local/share/vice bash COMPILE-RELEASE.sh \
--workspace ../c64-080-release-buildThis historical full rebuild workflow makes an isolated source copy, builds the older example set, validates
pictures, endings and menus, runs the original renderer matrix, updates the
chart and produces a ZIP. For the GMod3 release, use the
0.8.0 rebuild and verification commands. Results and logs stay beside the checkout.
Add --install to install only after all checks pass. Add --baseline-zip PATH
to also generate a patch ZIP. The pipeline never commits, tags or pushes. Root VERSION supplies the build
identity; an alternate-version VICE test guards startup, menu and thanks labels.
To apply the supplied 0.8.1 hotfix to the complete 0.8.0 release, save the ZIP one level above your checkout and extract it from that parent directory:
unzip -o c64-3d-toolkit-v0.8.1-incremental.zip
cd c64-3d-toolkit
python tools/report_gmod3_performance.py --check
python tools/verify_gmod3_release.pyThe ZIP contains its own c64-3d-toolkit/ directory. Current cartridges are
already rebuilt. Previous versioned menu/HiFi carts remain as historical
references; older EasyFlash cartridges remain byte-for-byte preserved. See the
release guide for checks and rebuilds.
| Selection | Preserved implementation |
|---|---|
step, bytechunk, yunroll |
Resident PRG renderers |
yunroll-cart |
Original resident cartridge scaffold |
yunroll-cart-v2 through yunroll-cart-v9 |
Earlier streamed generations |
hors-v1, hors-v1-scene |
Original v1 / internal V10 implementations |
hors-v2, hors-v2-scene |
Previous object/scene implementation; comparison/menu default |
hors-v3 (also hors-renderer-v3) |
Previous surface/material/texture pipeline; EasyFlash default |
hors-v4 (also hors-renderer-v4) |
Current default; hors-v4-gmod3 or hors-v4-ef selects hardware explicitly |
A new pipeline is added incrementally. Old assembly, encoders and comparisons
stay intact. The resident yunroll method still narrowly wins the canonical
CUBE workload; the chart retains that result. See pipeline versioning.
Release history · Changelog · Documentation index
c64-3d-toolkit by FlyingFathead
Thanks to: ChaosWhisperer
Additional 3D models supplied by: Sande
Inspired by Saku magazine demo competition.
Saku's home page: https://sakulehti.fi
A big thank you to everyone who has contributed, collaborated and given ideas for the project.
Stanford Dragon: model data from the Stanford University Computer Graphics Laboratory's 3D Scanning Repository. The Dragon example includes the original source credit, provenance and usage terms.
EasyFlash / EasyAPI: thanks to Thomas "skoe" Giesel for the EasyFlash project and developer documentation and the original EasyAPI AM/M29F040 V1.4 flash driver embedded in standard toolkit cartridges. Bundled source, original notice and attribution. CRT files are generated with VICE's cartconv; these demos do not call EasyAPI to write flash.