{"id":46469015,"url":"https://github.com/ljramones/dynamislightengine","last_synced_at":"2026-03-06T06:01:36.660Z","repository":{"id":338702677,"uuid":"1158774658","full_name":"ljramones/DynamisLightEngine","owner":"ljramones","description":"Multi-backend Java 25 rendering engine with OpenGL and Vulkan forward PBR pipelines (Cook-Torrance, IBL, CSM shadows, PCSS/VSM/EVSM filtering), TAA/SMAA/SSAO post-processing, glTF 2.0 asset loading, and a strict lifecycle API. Built on LWJGL 3.3.6 with ServiceLoader backend discovery and a compare-harness test framework.","archived":false,"fork":false,"pushed_at":"2026-02-25T04:53:16.000Z","size":3432,"stargazers_count":1,"open_issues_count":14,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T10:17:33.321Z","etag":null,"topics":["java","rendering-engine","vulkan-engine"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ljramones.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-15T22:22:09.000Z","updated_at":"2026-02-25T04:53:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ljramones/DynamisLightEngine","commit_stats":null,"previous_names":["ljramones/dynamislightengine"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ljramones/DynamisLightEngine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljramones%2FDynamisLightEngine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljramones%2FDynamisLightEngine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljramones%2FDynamisLightEngine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljramones%2FDynamisLightEngine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ljramones","download_url":"https://codeload.github.com/ljramones/DynamisLightEngine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljramones%2FDynamisLightEngine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30164532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T04:43:31.446Z","status":"ssl_error","status_checked_at":"2026-03-06T04:40:30.133Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","rendering-engine","vulkan-engine"],"created_at":"2026-03-06T06:00:42.015Z","updated_at":"2026-03-06T06:01:34.665Z","avatar_url":"https://github.com/ljramones.png","language":"Java","readme":"# DynamicLightEngine\n\nCross-platform Java rendering/game engine scaffold using a stable Java-first API boundary and backend SPI.\n\n## Requirements\n\n- JDK 25 (project enforces Java 25 via Maven Enforcer)\n- Maven 3.9+\n\n## JDK 25 setup\n\nIf you use `jenv`:\n\n```bash\njenv local 25.0.1\njava -version\nmvn -version\n```\n\nOr shell-only:\n\n```bash\nexport JAVA_HOME=$(/usr/libexec/java_home -v 25)\nexport PATH=\"$JAVA_HOME/bin:$PATH\"\njava -version\nmvn -version\n```\n\n## Modules\n\n- `engine-api`: immutable DTOs and runtime contracts (`org.dynamislight.api.*`)\n- `engine-spi`: backend discovery SPI (`ServiceLoader`)\n- `engine-impl-common`: shared lifecycle/runtime base for backend implementations\n- `engine-impl-opengl`: OpenGL backend implementation\n- `engine-impl-vulkan`: Vulkan backend implementation\n- `engine-bridge-dynamisfx`: host bridge/mapping layer\n- `engine-host-sample`: minimal console host that runs the lifecycle\n\n## Interface contracts and implementations\n\n### API contract modules\n\n- `org.dynamislight.api.runtime`: lifecycle and execution surface (`EngineRuntime`, callbacks, frame/stats/capabilities)\n- `org.dynamislight.api.config`: runtime config and quality tier\n- `org.dynamislight.api.input`: host input DTOs\n- `org.dynamislight.api.scene`: scene/fog/smoke DTOs\n- `org.dynamislight.api.event`: event/warning DTOs\n- `org.dynamislight.api.error`: engine error model (`EngineException`, `EngineErrorCode`)\n- `org.dynamislight.api.logging`: structured runtime log DTOs\n- `org.dynamislight.api.resource`: resource cache/reload service contracts\n\n### SPI and backend implementations\n\n- SPI contract: `engine-spi` (`EngineBackendProvider`, `BackendRegistry`) discovers backends through `ServiceLoader`.\n- OpenGL implementation: `engine-impl-opengl` (`OpenGlBackendProvider`, `OpenGlEngineRuntime`) is the primary active backend.\n- Vulkan implementation: `engine-impl-vulkan` (`VulkanBackendProvider`, `VulkanEngineRuntime`) provides a real baseline render path (context, swapchain, pipeline, indexed draw).\n- Host integration: `engine-bridge-dynamisfx` provides the DynamisFX bridge/session and mappers to engine DTOs.\n\n## Build and test\n\n```bash\nmvn clean compile\nmvn test\n```\n\nIf `JAVA_HOME` is stale in your shell, use the repo launcher to force `.java-version` (25):\n\n```bash\n./scripts/mvnw25 test\n```\n\nRun backend compare-harness parity tests explicitly:\n\n```bash\nmvn -pl engine-host-sample -am test -Ddle.compare.tests=true -Dtest=BackendParityIntegrationTest -Dsurefire.failIfNoSpecifiedTests=false\n```\n\nWrite compare outputs to a stable folder for inspection/artifacts:\n\n```bash\nmvn -pl engine-host-sample -am test -Ddle.compare.tests=true -Ddle.compare.outputDir=artifacts/compare -Dtest=BackendParityIntegrationTest -Dsurefire.failIfNoSpecifiedTests=false\n```\nThis includes tiered fog/smoke, shadow, and texture-heavy checks plus `shadow-cascade-stress`, `fog-shadow-cascade-stress`, `smoke-shadow-cascade-stress`, and `texture-heavy` compare profiles.\n\nRun real-hardware AA compare rebaseline on macOS (OpenGL/Vulkan, non-mock, first-thread JVM):\n\n```bash\n./scripts/aa_rebaseline_real_mac.sh\n```\n\nOptional overrides:\n\n```bash\nDLE_COMPARE_OUTPUT_DIR=artifacts/compare/aa-real-manual ./scripts/aa_rebaseline_real_mac.sh\n```\n\n```bash\n# Vulkan mode: mock (default), auto, or real\nDLE_COMPARE_VULKAN_MODE=real ./scripts/aa_rebaseline_real_mac.sh\n```\n\n```bash\n# TSR validation depth (extra temporal frames) + optional upscaler hook tuning\nDLE_COMPARE_TEMPORAL_FRAMES=10 \\\nDLE_COMPARE_TEMPORAL_WINDOW=5 \\\nDLE_COMPARE_TSR_FRAME_BOOST=6 \\\nDLE_COMPARE_UPSCALER_MODE=xess \\\nDLE_COMPARE_UPSCALER_QUALITY=quality \\\nDLE_COMPARE_VULKAN_MODE=real \\\n./scripts/aa_rebaseline_real_mac.sh\n```\n\n```bash\n# Run repeated real-Vulkan AA samples and lock thresholds from the aggregate\nDLE_COMPARE_LONGRUN_RUNS=5 \\\n./scripts/aa_longrun_real_sampling_mac.sh\n```\n\n```bash\n# Run repeated motion-focused AA stress suites (animated/pan-heavy) and lock thresholds\nDLE_COMPARE_LONGRUN_MOTION_RUNS=4 \\\n./scripts/aa_rebaseline_real_mac.sh longrun-motion\n```\n\n```bash\n# Run TSR+upscaler vendor matrix (FSR/XeSS/DLSS hook/native-state audit from metadata)\n./scripts/aa_rebaseline_real_mac.sh upscaler-matrix\n```\n\n```bash\n# Build threshold-lock recommendations from repeated real-Vulkan compare metadata\n# Default minimum profile samples: 3 (override with DLE_COMPARE_THRESHOLD_LOCK_MIN_RUNS)\n./scripts/aa_rebaseline_real_mac.sh lock-thresholds artifacts/compare\n```\n\n```bash\n# Promote generated recommendations into repo-owned default threshold files\n./scripts/promote_compare_thresholds.sh artifacts/compare/threshold-lock/recommended-thresholds.properties real\n./scripts/promote_compare_thresholds.sh artifacts/compare/threshold-lock/recommended-thresholds.properties mock\n```\n\n```bash\n# Apply locked thresholds automatically during compare runs\nDLE_COMPARE_THRESHOLDS_FILE=artifacts/compare/threshold-lock/recommended-thresholds.properties \\\nDLE_COMPARE_VULKAN_MODE=real \\\n./scripts/aa_rebaseline_real_mac.sh\n```\n\n```bash\n# Optional: enforce a pinned MoltenVK version during preflight/real runs\nDLE_COMPARE_REQUIRE_MOLTENVK_VERSION=1.4.0 \\\nDLE_COMPARE_VULKAN_MODE=real \\\n./scripts/aa_rebaseline_real_mac.sh preflight\n```\n\nTSR implementation reference: `docs/tsr-temporal-upsampling-notes-2026.md`\n\nExternal native upscaler bridge options (OpenGL and Vulkan):\n- `\u003cbackend\u003e.upscaler.nativeEnabled=true|false`\n- `\u003cbackend\u003e.upscaler.bridgeClass=com.example.MyUpscalerBridge`\n- `\u003cbackend\u003e.upscaler.bridgeLibrary=/abs/path/libvendor_upscaler.dylib` (or comma-separated list)\n\nCompare metadata now includes warning code snapshots per backend:\n- `compare.opengl.warningCodes`\n- `compare.vulkan.warningCodes`\n\nExample (`vulkan` backend):\n\n```bash\nMAVEN_OPTS=\"-Dvulkan.upscaler.nativeEnabled=true \\\n  -Dvulkan.upscaler.bridgeClass=com.acme.upscale.VulkanDlssBridge \\\n  -Dvulkan.upscaler.bridgeLibrary=/opt/acme/lib/libacme_dlss_bridge.dylib\" \\\nDLE_COMPARE_UPSCALER_MODE=dlss \\\nDLE_COMPARE_VULKAN_MODE=real \\\n./scripts/aa_rebaseline_real_mac.sh\n```\n\nGitHub Actions CI runs:\n- matrix build/test (`mvn test`) on `main` and pull requests using JDK 25 across Linux, macOS, and Windows\n- guarded backend parity compare harness tests on Ubuntu (`dle.compare.tests=true`)\n- `.github/workflows/ci.yml`\n\n## Run sample host\n\nInstall snapshots, then run the sample host:\n\n```bash\nmvn -DskipTests install\nmvn -f engine-host-sample/pom.xml exec:java\n```\n\nSelect backend by argument:\n\n```bash\nmvn -f engine-host-sample/pom.xml exec:java -Dexec.args=\"vulkan\"\n```\n\nInspect and hot-reload resources in sample host:\n\n```bash\nmvn -f engine-host-sample/pom.xml exec:java -Dexec.args=\"opengl --resources\"\n```\n\nRun compare harness from sample host (writes images under `artifacts/compare`):\n\n```bash\nmvn -f engine-host-sample/pom.xml exec:java -Dexec.args=\"--compare --compare-tier=HIGH --compare-tag=shadow-high\"\n```\n\nCompare mode backend toggles:\n- `--compare-opengl-mock=true|false`\n- `--compare-vulkan-mock=true|false`\n- `--compare-vulkan-offscreen=true|false`\n\nTune sample host shadow/post parameters from CLI:\n\n```bash\nmvn -f engine-host-sample/pom.xml exec:java -Dexec.args=\"vulkan --tier=HIGH --shadow=on --shadow-cascades=4 --shadow-pcf=5 --shadow-bias=0.001 --shadow-res=2048 --post=on --tonemap=on --exposure=1.1 --gamma=2.2 --bloom=on --bloom-threshold=1.0 --bloom-strength=0.8\"\n```\n\nInteractive tuning + diagnostics overlay:\n\n```bash\nmvn -f engine-host-sample/pom.xml exec:java -Dexec.args=\"vulkan --interactive --overlay --frames=99999\"\n```\n\nInteractive commands:\n- `help`, `show`, `reload`, `quit`\n- `tier LOW|MEDIUM|HIGH|ULTRA`\n- `shadow on|off`, `shadow_cascades \u003c1-4\u003e`, `shadow_pcf \u003c1-9\u003e`, `shadow_bias \u003cfloat\u003e`, `shadow_res \u003c256-4096\u003e`\n- `post on|off`, `tonemap on|off`, `exposure \u003c0.25-4.0\u003e`, `gamma \u003c1.2-3.0\u003e`\n- `bloom on|off`, `bloom_threshold \u003c0.2-2.5\u003e`, `bloom_strength \u003c0.0-1.6\u003e`\n\nOpenGL backend options (via `EngineConfig.backendOptions`):\n- `opengl.mockContext=true|false` (default `false`) skips native context creation for headless/test runs.\n- `opengl.forceInitFailure=true|false` forces `BACKEND_INIT_FAILED` for failure-path testing.\n- `opengl.windowVisible=true|false` (default `false`) controls visible presentation window.\n\nVulkan backend options:\n- `vulkan.mockContext=true|false` (default `true`) toggles real Vulkan instance initialization.\n- `vulkan.forceInitFailure=true|false` forces `BACKEND_INIT_FAILED` for failure-path testing.\n- `vulkan.windowVisible=true|false` (default `false`) controls visible presentation window.\n- `vulkan.forceDeviceLostOnRender=true|false` forces `DEVICE_LOST` for failure-path testing.\n- `vulkan.postOffscreen=true|false` (default `true`) enables dedicated Vulkan post pass (intermediate copy + fullscreen composite) with automatic shader fallback if unavailable.\n\nSample-host default keeps OpenGL in mock mode for portability. To run real OpenGL init/render from sample host:\n\n```bash\nmvn -f engine-host-sample/pom.xml exec:java -Dexec.args=\\\"opengl\\\" -Ddle.opengl.mockContext=false\n```\n\n## Current status\n\nDynamicLightEngine now provides real baseline rendering in both OpenGL and Vulkan backends behind the same API/SPI contracts.\n\nVulkan now includes:\n- attribute-rich mesh ingestion (`POSITION`, `NORMAL`, `TEXCOORD_0`, `TANGENT`) with `.gltf/.glb` parsing\n- descriptor-backed camera/material/lighting data\n- 3-frames-in-flight global uniform + descriptor-set ring path\n- persistently mapped Vulkan staging memory for frame-uniform uploads\n- fog/smoke quality-tier behavior and degradation warnings aligned with OpenGL warning semantics\n- multi-frame-in-flight command/sync model and device-local mesh buffers uploaded via staging transfers\n\nCross-backend parity tests now cover:\n- lifecycle/error parity\n- material/lighting scene behavior parity signals\n- repeated resize stability\n- quality-tier fog/smoke degradation warning parity\n- tonemap-enabled post-process parity profile (`post-process`)\n\nPost-processing status:\n- scene-level `PostProcessDesc` is supported on OpenGL and Vulkan.\n- scene-level `AntiAliasingDesc` (via `PostProcessDesc.antiAliasing`) can override AA mode/debug and temporal controls (`blend`, `clipScale`, `lumaClipEnabled`, `sharpenStrength`, `renderScale`).\n- temporal debug view supports a composite overlay mode: `dle.taa.debugView=5` (quadrants: reactive/disocclusion/historyWeight/velocity).\n- OpenGL now uses a dedicated post pass (offscreen FBO color target + fullscreen post shader) with shader-driven fallback safety.\n- Vulkan now runs a dedicated post pass when available and surfaces explicit `VULKAN_POST_PROCESS_PIPELINE` diagnostics (including fallback mode when needed).\n\nOpenGL includes a fog path driven by `SceneDescriptor.fog` with quality-tier dependent sampling:\n- `LOW`: coarse fog steps\n- `MEDIUM/HIGH`: progressively smoother fog\n- `ULTRA`: unquantized fog factor\n\nOpenGL also consumes `SceneDescriptor.smokeEmitters` with a screen-space smoke blend.\nAt lower tiers (`LOW`, `MEDIUM`) smoke quality is degraded intentionally and reported through `EngineWarning` code `SMOKE_QUALITY_DEGRADED`.\n\nResource baseline is now available through `EngineRuntime.resources()`:\n- in-memory asset cache with ref-count ownership\n- automatic scene asset acquire/release on scene swap and shutdown\n- filesystem-backed `LOADED` / `FAILED` state transitions\n- checksum-aware hot reload via `EngineResourceService.reload(ResourceId)` (changed vs unchanged detection) with `ResourceHotReloadedEvent`\n- per-resource metadata in `ResourceInfo` (`resolvedPath`, `lastChecksum`, `lastLoadedEpochMs`)\n- v1 eviction policy: no TTL; zero-ref resources remain cacheable and are evicted by `resource.cache.maxEntries` pressure\n\nResource runtime options (`EngineConfig.backendOptions`):\n- `resource.watch.enabled=true|false` (default `false`) enables filesystem watcher auto-reload.\n- `resource.watch.debounceMs=\u003cint\u003e` (default `200`) debounce window for watcher-triggered reloads.\n- `resource.cache.maxEntries=\u003cint\u003e` (default `256`) maximum cached resource records.\n- `resource.reload.maxRetries=\u003cint\u003e` (default `2`) retry attempts for failed reload scans.\n\nResource telemetry is available via `EngineRuntime.resources().stats()`:\n- cache hits/misses\n- reload requests/failures\n- evictions\n- watcher event count\n\nOptional integration-test flags:\n- `-Ddle.test.resource.watch=true` enables watcher auto-reload integration test.\n- `-Ddle.test.vulkan.real=true` enables guarded real-Vulkan integration tests (init/reuse/reorder/resize-endurance/device-loss paths). Tests skip automatically if LWJGL native runtime prerequisites are unavailable.\n- `-Ddle.compare.tests=true` enables compare-harness image diff integration tests.\n- `-Ddle.compare.opengl.mockContext=true|false`, `-Ddle.compare.vulkan.mockContext=true|false`, and\n  `-Ddle.compare.vulkan.postOffscreen=true|false` control compare-harness backend modes.\n\n## Planning\n\n- Rendering roadmap (2026): `docs/rendering-roadmap-2026.md`\n- Mechanical sympathy + GPU-driven + Dynamic GI roadmap: `docs/mechanical-sympathy-gpu-driven-roadmap-2026.md`\n- Superset rendering roadmap (2026): `docs/superset-rendering-roadmap-2026.md`\n- Capabilities compendium: `docs/capabilities-compendium.md`\n- Expanded rendering feature comparison (2026): `docs/expanded-rendering-feature-comparison-2026.md`\n- API reference: `docs/api-reference.md`\n- Release workflow: `docs/release-workflow.md`\n- Milestone and issue backlog: `docs/github-milestones.md`\n- Architecture note: `docs/architecture/backend-strategy.md`\n- ADR: `docs/adr/0001-backend-strategy.md`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fljramones%2Fdynamislightengine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fljramones%2Fdynamislightengine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fljramones%2Fdynamislightengine/lists"}