Skip to content
docxologyPublic

About

Quadray-based Python/JavaScript games and an experimental C++/OpenGL voxel project. Shared coordinate contracts and browser/native checks in the Synergetics suite.

Topics

Resources

Contributing

Security policy

Stars

9 stars

Watchers

4 watching

Forks

Repository files navigation

QuadCraft

browser-tests.yml workflow status on main License: Apache-2.0

Tetrahedral voxel and geometry experiments plus thirty browser games using quadray ideas.

Status & Verification (agents: start here)

This development checkout contains three distinct runtime families:

Runtime What is implemented Start here
Native C++17 GLFW/OpenGL tetrahedral world prototype, generated chunks, colored faces, drone camera and sampled block interaction Native setup
Historical browser/server experiments Canvas geometry, brushes, CCP ball columns, quaternion camera and experimental Var-tree/JSP synchronization JavaScript runtime map
Browser-game portfolio Thirty game-specific boards/controllers/renderers sharing JavaScript helpers Games and contracts, catalog

These are not one production engine. Native ECS/rigid-body physics, plugin/mod loading, imported asset packs and authenticated authoritative multiplayer are not shipped systems. Historical design prose is not a usable SDK. Architecture identifies actual ownership and boundaries.

Verification commands are documented in the testing guide; current runs are listed in the workflow index. No frozen test/assertion total is a current status receipt. TODO.md retains dated maintenance history; CHANGELOG.md describes v0.6.0 source changes, not a passing CI or publication receipt. Immutable older release assets remain unchanged.

Synergetics suite

QuadCraft is the interactive application member alongside QuadMath (specification, exact mathematics and lattice algorithms) and symergetics (rational geometry, transformations and research workflows). The suite guide documents the Y/Z exchange and scale difference between their Cartesian embeddings, observed interoperability outcomes and source-versus-package evidence. The coordinated source versions are QuadMath 0.7.0, symergetics 1.4.0 and QuadCraft v0.6.0; version metadata is not proof of publication or binary deployment. The projects share mathematical contracts, not a production cross-language game runtime.

Overview

Physical quadrays use four coefficients for a three-dimensional point modulo a common additive offset. Raw four-index game slots may intentionally remain independent even when their projections coincide. A game's “4D” name does not imply four independent physical Euclidean axes.

The native prototype explores tetrahedral block geometry and multioctave procedural material selection. Its terrain noise is a deterministic sum of sine waves, not a seeded Perlin/simplex implementation. Its mesher emits tetrahedral faces, not a marching-tetrahedra isosurface.

Selected gameplay: geometry, strategy, simulation and arcade

Four actual Chromium gameplay captures: browser block editing, Hex moves after rotation, a reseeded Life board and Tetris after a hard drop. Sparse views use labeled center-detail crops.

These are exercised browser Canvas states, not native OpenGL screenshots or four independent physical dimensions. The gallery guide links each game, source, original uncropped capture and recorded state. Capture and composition commands reuse the real Chromium gate's scenarios; the four-view capture is not the full thirty-game gate. Provenance records browser/time/random controls, crop bounds and PNG hashes.

The historical quadray-grid image belongs to the HTML geometry experiments, a separate runtime.

Building and Running

Native graphical build

Requirements: C++17 compiler, CMake 3.16+, OpenGL, GLEW and GLFW3. Running needs a graphical session and an OpenGL 3.3 core context. From the repository root:

cmake -S . -B build -DQUADCRAFT_BUILD_GAME=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build
./build/bin/QuadCraft

Multi-configuration generators require the matching configuration option/path. ./build.sh wraps the default build and launches; ./build.sh --no-run --test runs all configured CTests, including real-GL tests when the game is ON. Linux without a display needs xvfb-run -a ./build.sh --no-run --test. The wrapper preserves cached CMake options. See platform/dependency and CPU-only wrapper details.

For a bounded real-frame capture:

./build/bin/QuadCraft --frames 24 --capture /tmp/quadcraft-application.ppm

N must be positive and capture requires --frames. A bounded run completes the requested frames or exits nonzero; early window closure and capture-write failures are errors. Slow synchronous loading may exceed one second but cannot silently shorten a bounded run. The top-down P6 PPM contains the final actual back buffer, not a synthetic scene. Real-GL checks and artifacts still require execution; no native graphical pass is asserted here.

Headless core build

Coordinate/world/camera tests do not require OpenGL libraries or a display:

cmake -S . -B build-core -DQUADCRAFT_BUILD_GAME=OFF -DBUILD_TESTING=ON
cmake --build build-core
ctest --test-dir build-core --output-on-failure --no-tests=error

QUADCRAFT_BUILD_GAME defaults ON; BUILD_TESTING is independently controlled. A graphics-free pass does not establish native render/input correctness.

Browser portfolio

No bundling is needed for ordinary play. Use Python 3.13 explicitly for these launcher/QA examples (the launcher syntax minimum is Python 3.10):

python3.13 games/run_games.py --list
python3.13 games/run_games.py --game chess doom life
python3.13 games/run_games.py --all --no-browser
python3.13 games/run_games.py --test
python3.13 games/run_games.py --validate

The launcher serves static HTTP on base port 8100 plus each catalog offset. Preserve the sibling games/4d_generic/ directory; copying a game folder alone loses shared dependencies. HTTP is the portable recipe, especially for Doom's ES modules. These servers do not provide multiplayer. The shell convenience wrapper ./games/run.sh chess chooses its own available interpreter.

Real Chromium gate

The separate browser gate exercises actual game input/state/rendering and records screenshots/logs and real pointer-capture availability. Run from games/tests/browser/:

npm ci --ignore-scripts --no-audit --no-fund
npx --no-install playwright install --with-deps chromium
PYTHON=python3.13 npm test

Ordinary run_games.py --test runs Node/Python logic suites, not this Chromium package. Structural validation, logic tests and real-browser checks have different coverage.

Controls

The following refer to native Input.h, not the historical browser experiment or every portfolio game:

  • Arrow keys: drone-like forward/back/left/right; Page Up/Down: vertical motion, with or without mouse capture.
  • WASD and Space: captured-mouse movement/up. Shift/Control modify movement speed; do not assume Shift is a working down binding (Page Down is).
  • Mouse look requires capture; wheel adjusts camera zoom.
  • Left click captures the cursor when free; when captured, left/right block actions remove/place stone if the sampled ray finds a stored block.
  • Tab toggles capture. Escape releases capture when captured and requests exit when free.
  • F1 toggles wireframe; F2 toggles the coordinate overlay; F4 toggles diagnostic distance reporting.

Block picking uses sampled world-key queries rather than exact face intersection; visible-face selection is not guaranteed. Native movement has no terrain collision/gravity solver. For browser controls, use the selected game's own page and portfolio documentation.

Architecture

src/core/       native coordinates, world/chunks/materials, camera
src/game/       native lifecycle, GLFW input and embedded shader sources
src/render/     native face meshing, GL meshes and shader utilities
src/browser/   geometry experiments, including newer Var-tree page
src/js/        historical HTML and modular JavaScript experiments
src/server/    experimental Tomcat/JSP state merge
games/         thirty browser games, shared JS and Python launcher/QA
docs/          implementation guides, mathematics and explicit design context

The native world uses Cartesian integer chunk keys, local quadray element keys and world-space mesh vertices. Chunk lifecycle explains creation/generation, dirty flags and numeric limits. The browser portfolio has its own board identity and time ownership.

Implementation Details

Use the actual C++ API reference instead of copying historical class diagrams. Portfolio contracts cover raw versus physical cells, twelve-contact versus raw eight-neighbor graphs, fixed update seconds, seeded streams and conservative transport. Conservative graph mixing is not symmetric-normalized heat.

The documentation hub and development index route to focused topics. Source customization describes real extension points without inventing an installed mod SDK. JSP synchronization describes its limited experiment, not a production service.

License

Apache 2.0; see LICENSE.

Acknowledgments

Inspired by Minecraft, tetrahedral-mesh game research, and quadray/Synergetics work associated with R. Buckminster Fuller and Kirby Urner. Mathematical inspiration does not imply validation of every experimental geometry or gameplay claim.

About

Quadray-based Python/JavaScript games and an experimental C++/OpenGL voxel project. Shared coordinate contracts and browser/native checks in the Synergetics suite.

Topics

Resources

Contributing

Security policy

Stars

9 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages