Refactor/upstream raylib first

.gitattributes

@@ -0,0 +1,2 @@
+# Vendored upstream sources and license texts must stay byte-identical.
+third_party/** -whitespace

.github/workflows/release-checks.yml

@@ -15,8 +15,8 @@ jobs:
       - name: Assemble and pack an isolated component
         uses: espressif/esp-idf-ci-action@v1
         with:
-          # ESP-IDF 6.2 has no release image tag yet. Device evidence is recorded
-          # separately in docs/releasing.md; this job uses the current latest image.
+          # Packaging uses the latest image; consumer builds also cover v6.1.
+          # Device evidence is recorded separately in docs/releasing.md.
           esp_idf_version: latest
           target: esp32s3
           path: '.'
@@ -63,15 +63,27 @@ jobs:
           - example: last_zone_extraction
             chip: esp32s31
             board: esp-mosaico
-          - example: tomb_raycast
-            chip: esp32s31
-            board: esp-mosaico
           - example: neon_rift_rally
             chip: esp32s31
             board: esp-mosaico
+          - example: sky_hop
+            chip: esp32s3
+            board: esp32-s3-box-3
+          - example: tower_defense
+            chip: esp32s3
+            board: esp32-s3-box-3
           - example: raylib_shooter
             chip: esp32s3
             board: esp32-s3-box-3
+          - example: living_worlds
+            chip: esp32s3
+            board: esp32-s3-box-3
+          - example: last_zone_extraction
+            chip: esp32s3
+            board: esp32-s3-box-3
+          - example: neon_rift_rally
+            chip: esp32s3
+            board: esp32-s3-box-3
     steps:
       - uses: actions/checkout@v4
       - uses: actions/download-artifact@v4

.gitignore

@@ -11,7 +11,9 @@ examples/*/components/gen_bmgr_codes/
 examples/sky_hop/assets_src/*.wav
 examples/sky_hop/assets_src/sky_hop_atlas.png
 examples/raylib_shooter/assets_src/shooter_atlas.png
+examples/raylib_shooter/assets_src/*.wav
 examples/last_zone_extraction/assets_src/*.wav
+examples/neon_rift_rally/assets_src/*.wav
 examples/last_zone_extraction/assets_src/enemy_run.png
 examples/last_zone_extraction/assets_src/weapon.png
 examples/last_zone_extraction/assets_src/controls.png
@@ -30,6 +32,7 @@ artifacts/
 /examples/vector_pet_dev/
 /examples/vector_puppet_dev/
 /examples/sewer_labyrinth_dev/
+/examples/koala_seasons_dev/
 
 # Local integration backups and generated release output
 /*.patch

AGENTS.md

@@ -11,4 +11,4 @@ Choose checks from the files changed. Report which checks ran and which device p
 | Audio cue or haptic mapping | Run the related model/audio tests; check repeated event consumption and cleanup; listen or feel on the target device when hardware is available |
 | Board adapter or display path | Build the affected target; capture device startup, input, present, and shutdown results when hardware is available |
 
-Keep game models and shared views independent of ESP-IDF/BSP headers. Concrete native-example boards live under `examples/boards/<board>/`; game sources depend only on the selected example-board contract/component and must not include a concrete board API. Device-only benchmark adapters are explicit exceptions in the boundary test. Use separate build directories for Host, direct native, and lobby ELF outputs. Flashing, installing, or publishing require their own authorization; a build instruction does not authorize them.
+Keep game models and shared views independent of ESP-IDF/BSP headers. Concrete native-example boards live under `examples/boards/<board>/`; game sources depend only on the selected example-board contract/component and must not include a concrete board API. Device-only benchmark adapters are explicit exceptions in the boundary test. Use separate build directories for Host and for each native board target. Flashing, installing, or publishing require their own authorization; a build instruction does not authorize them.

API.md

@@ -35,6 +35,9 @@ Keep callbacks bounded.
 
 `get_info` describes a fixed native-endian RGB565 surface. Stride is in pixels
 and must be at least width. The backend performs any transfer byte swapping.
+A backend that only ever displays rows `y % sample_row_step == 0` (power of
+two) may report that step; the Raylib-compatible facade and renderer then leave
+the other rows unwritten, and the backend must not show or snapshot them as-is.
 A successful `acquire` lends one exclusively writable frame; its opaque token
 belongs to the backend. The Engine holds at most one acquired frame.
 
@@ -83,3 +86,19 @@ Boot runs before Board creation, attach borrows the Board video/input interfaces
 and first-present runs after frame submission/flush and input startup. Detach must
 finish before the Board is destroyed; failure retains resources. A selected provider
 is a required link dependency. Ordinary native examples select no provider.
+
+## API audiences
+
+Public visibility does not make every entrypoint a default game API. The reviewed
+[catalog](compat/api/catalog.json) separates game capabilities, application integration
+hooks, low-level tools, compatibility facades and retained modules under review.
+Some legacy `raylib_lite_2d_*` names use neutral types in the renderer header;
+classify them by header/type contract rather than name alone. See the
+[custom API boundaries (Chinese)](docs/custom-api.CN.md) and
+[Scene/UI usage contract (Chinese)](docs/scene-ui.CN.md).
+
+Renderer callers may include the narrow [drawing](include/raylib_lite/raylib_lite_renderer_draw.h),
+[statistics](include/raylib_lite/raylib_lite_renderer_stats.h), or
+[benchmark](include/raylib_lite/raylib_lite_renderer_benchmark.h) contracts. The old renderer
+header re-exports all three. Statistics keep their existing layout and five legacy phase
+slots; benchmark entrypoint availability does not prove it was enabled or run.

CHANGELOG.md

@@ -2,13 +2,75 @@
 
 ## Unreleased
 
+- Released games adapt to the panel size. A new example header,
+  `raylib_lite_design_view.h`, keeps the short side at 480 design units and
+  maps them to the panel with a Camera2D (no camera at 480x480, so those frames
+  are unchanged). Pointer input converts back with `raylib_lite_design_point`
+  or `raylib_lite_design_field_point`; text snaps to 10 px multiples of the
+  default font. A game opts in by defining
+  `raylib_lite_game_adaptive_surface()` to return true; native glue then opens
+  the Board's `raylib_lite_example_board_panel_size()` (BOX-3 320x240, 1:1, no
+  letterbox) instead of the descriptor size. Games that do not opt in keep the
+  480x480 letterbox. Tomb Raycast, Last Zone and Living Worlds project 3D at the
+  panel's own resolution with the vertical field of view kept.
+- `tomb_in_move_capture()` and `tomb_in_jump_zone()` take the view width, and
+  Sky Hop's `platform_game_t` gains `view_width` (`platform_game_set_view_width`).
+- New `raylib_lite_tilemap_draw_layer_scaled()` draws a layer at any scale with
+  seam-free snapped tile edges; scale 1 is `raylib_lite_tilemap_draw_layer()`.
+- Host: `RAYLIB_LITE_HOST_SIZE=WxH`, or `--size WxH` on `tools/game_cli.py sim`
+  and `host/run_game.py`, runs a game on another surface size.
+- Neon Rift Rally: each race rolls rider personalities (skill, cornering,
+  aggression, nitro reserve) from a seed and names one rider the rival. Riders
+  take the inside line, check their mirror before merging, slipstream each
+  other, fire nitro tactically and sometimes slide wide in bends. New
+  `RALLY_EVENT_RIVAL_BOOST`/`RALLY_EVENT_RIVAL_SLIP`, `rally_set_seed()`,
+  `rally_rider_name()` and a `rival.wav` cue; the view adds nitro flames, slip
+  sparks, tail lights, a rival tag and HUD panel, and the rival result.
+  Rider lane changes follow a damped spring with a sideways velocity, so a
+  move eases in and settles instead of jumping to full speed, and the lean
+  pose follows that velocity.
+- Last Zone: hostiles have rifle, flanker and heavy roles, patrol routes with
+  a 120 degree vision cone and suspicion before alert, radio calls that killing
+  the caller cancels, rolled enemy fire with near-miss tracers, staggers and
+  retreats, and search sweeps. New `whizz.wav` and `radio.wav` cues.
+- The asset packer encodes sounds shorter than one second as IMA-ADPCM when
+  the reconstruction keeps at least 20 dB SNR (PCM16 otherwise), and starts
+  every ADPCM clip from a step size matched to its attack instead of the
+  smallest step. A sound entry may force `"encoding": "adpcm"` or `"pcm16"`;
+  the report records `adpcm_snr_db`. Existing decoders read both unchanged.
+- Translucent fills of 64 pixels or more blend through per-channel lookup
+  tables built once per colour; output is bit-identical to the per-pixel blend.
+  On ESP-Mosaico (mmu app-slot build) Last Zone's full-screen alpha-120 start
+  overlay drops from 24.7 to 17.0 ms.
+- The audio mixer resolves playing voices once per `mix` call instead of per
+  frame and skips the voice loop when nothing plays; output is unchanged.
+- Tomb Raycast is an internal preview: it is no longer assembled into the
+  Registry examples or built by release CI. The checkout keeps it as a raster
+  workload for Host tests and benchmarks.
+- `raylib_lite_video_info_t` gains an optional trailing `sample_row_step`. A
+  backend that never displays some rows (for example a 2:1 vertical downscale)
+  reports it, and the renderer and Raylib-compatible facade skip writing those
+  rows; displayed rows are unchanged. New `raylib_lite_renderer_set_row_step()`
+  and `raylib_lite_raylib_port_sample_row_step()`. Backends that fill the info
+  with positional initializers now need designated initializers to stay clean
+  under `-Wextra`.
+- ESP32-S3-BOX-3: the LCD runs at the esp-bsp 40 MHz pixel clock instead of the
+  board-pack 20 MHz, only the viewport is transferred once the letterbox bars are
+  on the panel, 480x480 games report row step 2, and the Board defaults build
+  with `-O2`, 64 KiB/64-byte data cache, 32 KiB instruction cache and code/rodata
+  executed from PSRAM. Existing BOX-3 projects must re-run `idf.py bmgr`.
+- Living Worlds runs on ESP32-S3-BOX-3, decoding its panoramas with the ROM
+  TJpgDec decoder; release CI compiles every released game on both Boards.
+- Raylib Shooter has an authored nebula backdrop and Sky Hop rounded clouds.
+  Tower Defense, Sky Hop and Shooter no longer paint background that opaque
+  layers fully cover.
 - ESP-Mosaico examples start Iris by default and mark the application healthy
   after the first accepted frame, so `mosaico.py install` can finish.
 - ESP-Mosaico and ESP32-S3-BOX-3 examples use per-project Board Manager
   generation; generated board metadata selects the matching application adapter.
 - Neon Rift Rally is included in the assembled Registry examples.
-- Release CI compiles every assembled game on ESP-Mosaico and `raylib_shooter`
-  on ESP32-S3-BOX-3, after generating each Board Manager profile.
+- Release CI compiles every assembled game on ESP-Mosaico and ESP32-S3-BOX-3,
+  after generating each Board Manager profile.
 - Prepared the single Engine component for Registry distribution with explicit
   package filters, a minimal offscreen consumer, API contracts and release CI.
 - Registry game examples are assembled with private copies of their shared

CMakeLists.txt

@@ -48,6 +48,13 @@ endif()
 set(_raylib_sources
     "${RAYLIB_LITE_ENGINE_ROOT}/src/runtime/raylib_lite_raylib_port.c"
     "${RAYLIB_LITE_ENGINE_ROOT}/src/renderer/raylib_lite_raylib_impl.c")
+set(_upstream_raylib_dir "${RAYLIB_LITE_ENGINE_ROOT}/third_party/raylib")
+set(_upstream_raylib_sources
+    "${_upstream_raylib_dir}/src/rshapes.c"
+    "${_upstream_raylib_dir}/src/rtextures.c"
+    "${_upstream_raylib_dir}/src/rtext.c"
+    "${RAYLIB_LITE_ENGINE_ROOT}/src/rcore/raylib_lite_rcore.c")
+list(APPEND _platform_sources "${RAYLIB_LITE_ENGINE_ROOT}/src/idf/raylib_lite_rcore_posix.c")
 set(_feature_sources
     "${RAYLIB_LITE_ENGINE_ROOT}/src/renderer/raylib_lite_tilemap.c"
     "${RAYLIB_LITE_ENGINE_ROOT}/src/scene/raylib_lite_scene.c"
@@ -59,20 +66,31 @@ set(_feature_sources
 idf_component_register(
     SRCS ${_platform_sources} ${_runner_sources} ${_runtime_sources}
          ${_asset_sources} ${_audio_sources} ${_renderer_sources}
-         ${_raylib_sources} ${_feature_sources}
+         ${_raylib_sources} ${_feature_sources} ${_upstream_raylib_sources}
     INCLUDE_DIRS
         "${RAYLIB_LITE_ENGINE_ROOT}/include/raylib_lite"
         "${RAYLIB_LITE_ENGINE_ROOT}/compat/raylib/include"
+        "${_upstream_raylib_dir}/src"
     PRIV_INCLUDE_DIRS
         "${RAYLIB_LITE_ENGINE_ROOT}/src/assets"
         "${RAYLIB_LITE_ENGINE_ROOT}/src/audio"
         "${RAYLIB_LITE_ENGINE_ROOT}/src/renderer"
-    REQUIRES raylib
     PRIV_REQUIRES esp_timer esp_system heap freertos esp_mmap_assets
                   nvs_flash log)
 
 target_compile_definitions(${COMPONENT_LIB} PUBLIC
-    RAYLIB_LITE_DEFAULT_FPS=${CONFIG_RAYLIB_LITE_DEFAULT_FPS})
+    RAYLIB_LITE_DEFAULT_FPS=${CONFIG_RAYLIB_LITE_DEFAULT_FPS}
+    GRAPHICS_API_OPENGL_SOFTWARE
+    PLATFORM_CUSTOM
+    SW_COLOR_BUFFER_BITS=16
+    SW_DEPTH_BUFFER_BITS=16)
+
+set_property(SOURCE ${_upstream_raylib_sources} APPEND PROPERTY COMPILE_OPTIONS
+    "-I${_upstream_raylib_dir}/src/external"
+    -Wno-incompatible-pointer-types -Wno-uninitialized -Wno-nonnull
+    -Wno-return-type -Wno-unused-variable -Wno-unused-function
+    -Wno-unused-label -Wno-stringop-truncation -Wno-unused-parameter
+    -Wno-missing-field-initializers -Wno-sign-compare)
 
 set(_renderer_c_sources
     "${RAYLIB_LITE_ENGINE_ROOT}/src/renderer/raylib_lite_renderer_esp.c"

CONTRIBUTING.CN.md

@@ -7,3 +7,5 @@
 提交改动时说明触发条件、最终行为和受影响目标。修改像素、资产格式或命令协议时，配独立正确性检查。运行 `python3 tools/check_markdown_links.py`、`git diff --check` 和相关测试；[AGENTS.md](AGENTS.md)按改动类型列出检查。Host 耗时与板端测量分开记录。不要提交生成的 `build/`、`managed_components/`、`sdkconfig` 或本地 `docs/debug/` 文件。
 
 新源码写明 SPDX 标识，并遵循所在组件的 C/Python 风格。不要复制其他引擎的实现；算法和数据布局的原创选择应在提交说明中可供审查。
+
+正式使用文档与开发记录分开维护。阶段历程、候选验收、消费者快照和退役审查写入[开发记录](docs/development/README.CN.md)，保留在仓库但不进入组件包。

CONTRIBUTING.EN.md

@@ -7,3 +7,5 @@ Start with the [quickstart](docs/quickstart.EN.md), then choose the affected bui
 For a change, describe the trigger, resulting behavior, and target path. Add an independent correctness check when changing pixels, asset formats, or protocol output. Use `python3 tools/check_markdown_links.py`, `git diff --check`, and the relevant tests; [AGENTS.md](AGENTS.md) maps change types to checks. Record device measurements separately from Host timings. Do not include generated `build/`, `managed_components/`, `sdkconfig`, or local `docs/debug/` files.
 
 New source files should carry an SPDX identifier and follow the existing C/Python formatting in their component. Do not copy another engine's implementation into this repository. Keep original algorithm and data-layout decisions reviewable in the PR or commit description.
+
+Keep usage contracts separate from development history. Store plans, candidate captures and review snapshots in the [development records (Chinese)](docs/development/README.CN.md); keep them in Git but exclude them from component packages.

README.CN.md

@@ -1,6 +1,6 @@
 # Raylib Lite Engine
 
-[English](README.md) · [开发文档](docs/README.CN.md)
+[English](README.md) · [使用文档](docs/README.CN.md)
 
 面向 ESP-IDF 的轻量游戏运行时与 RGB565 软件渲染引擎，提供固定步长更新、输入处理、资源加载、音频混合，以及场景和 UI 工具。游戏可在 PC Host 上开发和回放，再构建为设备原生固件。
 
@@ -19,7 +19,7 @@
 
 ```yaml
 dependencies:
-  idf: ">=6.2"
+  idf: ">=6.1"
   espressif2022/raylib-lite-engine: "^0.1.0"
 ```
 
@@ -36,17 +36,19 @@ python3 tools/game_cli.py sim examples/sky_hop
 
 浏览器打开 `http://127.0.0.1:8460/`。新建游戏及回放测试见[快速入门](docs/quickstart.CN.md)和[游戏开发指南](docs/game-development.CN.md)。
 
-仓库提供七个参考游戏和一个渲染基准工程，见[示例列表（English）](examples/README.md)。ESP-Mosaico 原生游戏使用共享 Board 适配层，自动获取板级依赖；构建和安装步骤见[构建指南](docs/build-matrix.CN.md)。
+仓库提供六个发布的参考游戏、一个内测游戏（Tomb Raycast）和一个渲染基准工程，见[示例列表（English）](examples/README.md)。ESP-Mosaico 原生游戏使用共享 Board 适配层，自动获取板级依赖；构建和安装步骤见[构建指南](docs/build-matrix.CN.md)。
 
 当前 Host 覆盖游戏模块、绘制、输入回放和特效；尚未链接场景、UI、存档和音频模块。
 
 ## 文档
 
-- [开发文档索引](docs/README.CN.md)：资源、输入、音频、绘制和板卡移植。
+- [使用与接口文档索引](docs/README.CN.md)：资源、输入、音频、绘制和板卡移植。
 - [组件发布（English）](docs/releasing.md)：组装可独立使用的例程并发布组件。
 - [更新记录](CHANGELOG.md)。
 - [贡献指南](CONTRIBUTING.CN.md)。
 
 ## 许可
 
 源码采用 [Apache-2.0](LICENSE) 许可；外部依赖见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)，例程素材来源见[素材记录](release/asset_provenance.json)。
+
+Raylib Lite Engine 是独立项目，不是 raylib 官方项目，与 raylib 及其作者 Ramon Santamaria（@raysan5）没有隶属或背书关系；随附的 raylib 源码保持其 zlib/libpng 许可。

README.md

@@ -19,7 +19,7 @@ Once the component is published, add it to your application's `main/idf_componen
 
 ```yaml
 dependencies:
-  idf: ">=6.2"
+  idf: ">=6.1"
   espressif2022/raylib-lite-engine: "^0.1.0"
 ```
 
@@ -36,7 +36,7 @@ python3 tools/game_cli.py sim examples/sky_hop
 
 Open `http://127.0.0.1:8460/` in a browser. See the [quickstart](docs/quickstart.EN.md) and [game development guide](docs/game-development.EN.md) for creating games and replay tests.
 
-The repository includes seven reference games and a render benchmark; see the [example list](examples/README.md). Native ESP-Mosaico games use a shared Board adapter that automatically resolves board dependencies. Build and installation steps are in the [build guide](docs/build-matrix.EN.md).
+The repository includes six released reference games, an internal preview (Tomb Raycast) and a render benchmark; see the [example list](examples/README.md). Native ESP-Mosaico games use a shared Board adapter that automatically resolves board dependencies. Build and installation steps are in the [build guide](docs/build-matrix.EN.md).
 
 Host currently covers game modules, rendering, input replay and effects. Scene, UI, save and audio modules are not linked by the current Host runner.
 
@@ -50,3 +50,5 @@ Host currently covers game modules, rendering, input replay and effects. Scene,
 ## License
 
 Source code is licensed under [Apache-2.0](LICENSE). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for external dependencies and the [asset record](release/asset_provenance.json) for example media origins.
+
+Raylib Lite Engine is an independent project. It is not an official raylib project and is not affiliated with or endorsed by raylib or its author, Ramon Santamaria (@raysan5); the vendored raylib sources keep their zlib/libpng license.