Skip to content

Project layout

How the japes repository is organised, which module does what, and which ones you actually depend on.

Top-level tree

japes/
├── ecs-core/                  # The library. This is what you depend on.
├── benchmark/
│   ├── ecs-benchmark/         # japes JMH benchmarks — all the numbers in the Benchmarks section.
│   ├── ecs-benchmark-valhalla/# Same benchmarks with @LooselyConsistentValue value records.
│   ├── ecs-benchmark-zayes/   # Cross-library: Zay-ES reference implementations.
│   ├── ecs-benchmark-dominion/# Cross-library: Dominion.
│   ├── ecs-benchmark-artemis/ # Cross-library: Artemis-odb.
│   └── bevy-benchmark/        # Cross-library: Bevy 0.15 Rust reference.
├── site/                      # This website (MkDocs Material).
├── README.md                  # Short quick-start + links.
├── DEEP_DIVE.md               # Full benchmark analysis.
├── TIER_FALLBACKS.md          # Per-generator skipReason catalog.
└── build.gradle.kts           # Root Gradle config (JDK 26 + --enable-preview).

ecs-core — the library

The only module you depend on as a consumer. One Gradle subproject, ~90 Java source files, zero runtime dependencies outside the JDK. Published as io.github.zzuegg.japes:ecs-core — see Installation.

Package structure

zzuegg.ecs
├── archetype      — Archetype graph, archetype id, per-archetype chunk lists
├── change         — ChangeTracker with dirty bitmap + per-slot addedTick/changedTick
├── command        — Commands buffer + deferred structural edit processing
├── component      — ComponentId/Info/Registry, Mut<T>, ComponentReader<T>
├── entity         — Entity record (packed index + generation)
├── event          — EventReader/EventWriter + per-tick double buffer
├── executor       — SingleThreaded and MultiThreaded executors
├── query          — ComponentAccess, AccessType, field filters
├── relation       — RelationStore + TargetSlice/SourceSlice + change/removal tracking
├── resource       — Res / ResMut / ResourceStore
├── scheduler      — Stage definitions, ScheduleGraph, topological sort
├── storage        — Chunk + DefaultComponentStorage (reference + flat variants)
├── system         — @System + @Exclusive + @ForEachPair, tier-1 generators, SystemParser
├── util           — LongArrayList (primitive-long growable list)
└── world          — World + WorldBuilder, snapshot, entity location table

You only need to import things from zzuegg.ecs.* — nothing under zzuegg.ecs.system.Generated* is user-facing. Package-private classes stay package-private.

benchmark/* — the benchmark modules

Not published. Clone the repo if you want to run them. Each JMH module targets one ECS implementation so cross-library comparisons are self-contained.

Module Runs against What you get
benchmark/ecs-benchmark Stock japes on JDK 26 All the headline numbers in the benchmarks section
benchmark/ecs-benchmark-valhalla japes with value record components on the Valhalla EA JVM The Valhalla investigation
benchmark/ecs-benchmark-zayes Zay-ES Cross-library reference
benchmark/ecs-benchmark-dominion Dominion Cross-library reference
benchmark/ecs-benchmark-artemis Artemis-odb Cross-library reference
benchmark/bevy-benchmark Bevy 0.15 (Rust) cargo bench

Running them:

./gradlew :benchmark:ecs-benchmark:jmhJar
java --enable-preview -jar benchmark/ecs-benchmark/build/libs/ecs-benchmark-jmh.jar

See the Benchmarks methodology page for the full reproduction commands.

site/ — this website

MkDocs Material sources under site/docs/, built into site/build/ (git-ignored). Published to GitHub Pages automatically via .github/workflows/docs.yml on every push to main.

To preview locally:

pip install mkdocs-material pymdown-extensions
mkdocs serve

Then open http://localhost:8000.

Root docs

Three markdown files live at the repo root alongside this site:

  • README.md — the GitHub landing page; a shorter version of everything here.
  • DEEP_DIVE.md — the canonical benchmark result tables. The benchmarks section of this site is split from that file; the two should stay in sync.
  • TIER_FALLBACKS.md — the per-generator skipReason catalog. Served at Reference / Tier fallbacks on this site.

These are primary sources. If the site and README.md / DEEP_DIVE.md ever disagree, the root .md is authoritative until the site is refreshed from it.

What's next