____  ____   _____ _____ _____  _____           _   _ 
 / __ \|  _ \ / ____|_   _|  __ \|_   _|    /\   | \ | |
| |  | | |_) | (___   | | | |  | | | |     /  \  |  \| |
| |  | |  _ < \___ \  | | | |  | | | |    / /\ \ | . ` |
| |__| | |_) |____) |_| |_| |__| |_| |_  / ____ \| |\  |
 \____/|____/|_____/|_____|_____/|_____|/_/    \_\_| \_|

Obsidian

A Vulkan-only Minecraft Java renderer focused on frame pacing, scalable terrain rendering, and GPU-driven visibility.

Releases · Modrinth · Timeline · Roadmap · Current state · Contributing

Warning

Obsidian is experimental renderer software. Preview builds may be incomplete or not production ready. Use a dedicated Minecraft profile, keep backups of important worlds, and read the release/test notes before installing a development build.

Current status

	Status
Product phase	Phase 4 — GPU-driven visibility at real-world scale
Validated production baseline	Phase 3 P3.10 opaque/cutout terrain replacement
Current tester build	0.4.0-phase4-dev3.1 — validated P4.3 Preview; promotion in progress
Minecraft	26.2
Fabric Loader baseline	0.19.3
Java	25
Graphics backend	Vulkan only

P4.2/dev2.2 is promoted and complete. P4.3/dev3.1 has now closed its corrected render-distance-32 runtime and human visual gates, including non-zero conservative safe-extra lineage with zero true fine mismatch/false-cull counters. Promotion is in progress through PR #78. P3.10 still owns production terrain rendering and P4.3 remains shadow-only.

For exact source SHAs, CI authority, test gates, and the current handoff, read ai/CURRENT_STATE.md.

Getting a build

Obsidian uses three publication levels. GitHub remains canonical package authority, and eligible Stable/Preview builds are mirrored to Modrinth:

• Stable checkpoint — the most validated public checkpoint at that time.
• Preview — GitHub Prerelease for active testers; may be incomplete or not production ready. Eligible Preview builds mirror to Modrinth as alpha/beta according to the version marker.
• CI artifact — short-lived Actions output used for engineering evidence.

See docs/RELEASE_CHANNELS.md for the full policy.

Test/install

1. Use Minecraft 26.2, Fabric Loader 0.19.3, and Java 25.
2. Download the build requested by the active test/release notes.
3. Place the Obsidian JAR in the instance mods folder.
4. In Minecraft, select Prefer Vulkan (Experimental) as the graphics API and restart when required.
5. Do not stack Obsidian with another complete terrain renderer/optimization mod unless compatibility is explicitly documented.

What Obsidian is optimizing for

Obsidian prioritizes renderer behavior in this order:

1. strong 1% / 0.1% lows and consistent frame pacing;
2. smooth chunk loading and camera movement;
3. large render distances as a normal workload;
4. high average FPS without hiding visual regressions;
5. bounded RAM/VRAM use and explicit GPU lifetime/synchronization;
6. vendor-neutral Vulkan architecture.

The project is correctness-first: performance experiments do not get promoted by weakening visual, lifecycle, synchronization, or differential-correctness gates after measurement.

Architecture direction

Minecraft / Fabric
       |
immutable render extraction
       |
renderer scene database
       |
+-----------------------------+
| async CPU mesh system       |
| GPU scene + visibility      |
+-----------------------------+
       |
bounded uploads / GPU arenas
       |
GPU culling + draw compaction
       |
indirect terrain rendering
       |
Vulkan render graph
       |
     screen

Minecraft keeps presentation/device ownership. Native Vulkan interop is kept narrow and evidence-driven rather than turning Obsidian into a second device/swapchain owner.

Roadmap

Phase	Focus	Status
0	bootstrap / backend validation	Complete
1	Vulkan frame, memory, indirect and visibility foundations	Complete
2	real-section semantics and correctness reference	Complete
3	asynchronous CPU meshing, greedy output, production terrain replacement	Complete
4	GPU-driven visibility at real-world scale	Active
Later	broader production scaling, advanced visibility/LOD/render-graph work	Planned

The full evidence-driven plan lives in ai/MASTER_ROADMAP.md.

Development and repository organization

Obsidian keeps a persistent engineering memory under ai/. It records current truth, roadmap, decisions, failed experiments, exact package authority, and handoff state so development can resume without relying on hidden chat history.

Repository hygiene is explicit:

• main is the only permanent branch;
• active PR branches are temporary working state;
• merged/closed branches are deleted after their evidence is recorded;
• tags/releases and ai/attempts/ preserve history;
• tester-facing development JARs should be published as GitHub Prereleases.

See ai/REPOSITORY_HYGIENE.md and CONTRIBUTING.md.

Project documents

• TIMELINE.md — detailed visual development timeline with phase status, milestone evidence, current position, and future horizon.
• ai/CURRENT_STATE.md — exact active implementation/runtime truth and next action.
• ai/MASTER_ROADMAP.md — canonical long-range product plan and phase gates.
• ai/OPERATING_MANUAL.md — engineering and validation procedure.
• ai/REPOSITORY_HYGIENE.md — branch, README, release, and public-surface rules.
• ai/DECISIONS.md — durable architecture/product decisions.
• ai/attempts/ — immutable experiment and validation evidence.
• docs/RELEASE_CHANNELS.md — Stable / Preview / CI publication model.

---

Frame pacing first. Scale second. FPS without cheating.