feat(world-builder): register uploaded graphics and extend palette schemas (#6)

[Rodrigoue9]

Summary

Resolves #6 by implementing paletteEntrySchema and validatePaletteEntry to validate multi-layer palette definitions, enforce non-colliding graphic index allocations (UPLOADED_GRAPHIC_INDEX_START = 1_000_000), and verify graphic existence across engine and uploaded assets.

Changes

• Implemented paletteEntrySchema and validatePaletteEntry in api/src/repositories/worldBuilder.ts.
• Added unit tests in api/src/repositories/__tests__/paletteValidation.test.ts.

Closes #6

---

Summary by Gitar

• Server Idle Liveness Fixes:
  • Excluded keepalive pings from AFK idle liveness reference calculations in server/src/server.ts.

_{This will update automatically on new commits.}

[gitar-bot]

Code Review ✅ Approved 4 resolved / 4 findings

Implements palette entry validation with paletteEntrySchema and validatePaletteEntry to enforce multi-layer definitions and non-colliding graphic index allocations starting at 1,000,000. Resolved validation gaps including untested validatePaletteEntry, missing engine graphic existence checks, dangling gracefulShutdown imports breaking the build, and ping packets preventing AFK idle detection. No issues found.

✅ 4 resolved

✅ Quality: validatePaletteEntry is never called and untested

📄 api/src/repositories/worldBuilder.ts:231-245
The PR's stated goal is to validate multi-layer palette definitions, but validatePaletteEntry is not imported or invoked by any route or caller in the codebase (only its definition exists), and the new test file only exercises paletteEntrySchema, never validatePaletteEntry. As a result no palette entry is actually validated against existing/uploaded graphics at runtime and the collision/existence logic has zero test coverage. Wire the function into the palette-writing route(s) and add a unit test covering the uploaded-index existence branch (mocking pool.query).

✅ Bug: Engine graphic indices are accepted without existence check

📄 api/src/repositories/worldBuilder.ts:234-248
The function's docstring claims it verifies graphics exist "originales o subidos", but for any positive index below UPLOADED_GRAPHIC_INDEX_START (1,000,000) it performs no validation at all — including indices between the real engine max (320151) and 1,000,000, which are non-existent yet accepted as valid. This lets invalid engine indices pass validation. Either validate engine indices against the known upper bound (e.g. reject grhIndex > MAX_ENGINE_GRAPHIC_INDEX) or correct the docstring to reflect that only uploaded indices are checked.

✅ Bug: Dangling import of non-exported gracefulShutdown symbols breaks build

📄 server/src/server.ts:22-26 📄 server/src/server.ts:216
server/src/server.ts lines 22-26 import gracefulShutdown, GracefulShutdownDependencies, and ShutdownClient from ./gracefulShutdown, but that module only exports ShutdownSignal, withTimeout, and createGracefulShutdown — so these are missing exports (TS2305). Worse, the imported name gracefulShutdown collides with the local const gracefulShutdown = createGracefulShutdown(...) declared at line 216 (cannot redeclare block-scoped variable). This is a leftover from the merge that deleted the old shutdown handlers; the code using these symbols was removed. Delete the entire import block at lines 22-26 to fix compilation.

✅ Bug: Ping packets keep AFK players from ever being idle-kicked

📄 server/src/server.ts:437-441 📄 server/src/server.ts:795-807 📄 server/src/server.ts:819-825
trackClientActivity deliberately stores keepalive pings in lastPingAt (not lastActivityAt) with a comment stating keepalive traffic must not contaminate AFK/gameplay metrics. However, the non-scout idle path uses getClientLivenessReferenceAt, which returns Math.max(lastActivityAt, lastPingAt, connectedAt), so lastPingAt is folded right back into the idle-timeout comparison. Any client that emits automatic keepalive pings will have its idle reference refreshed every ping and can never be disconnected by processIdleCharactersTick, directly defeating the AFK-kick behavior the comment intends. If the intent is to detect only dead transport, drop lastPingAt from the reference; if it is to detect AFK players, exclude ping from liveness as the comment says.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

---

Important

Your trial ends in 1 day — upgrade now to keep code review, CI analysis, auto-apply, custom automations, and more.

_{Was this helpful? React with 👍 / 👎 | Gitar}

[Rodrigoue9]

Addressed the liveness review finding in commit 09c069b:

• Updated getClientLivenessReferenceAt in server/src/server.ts to exclude lastPingAt from the AFK idle reference, ensuring transport keepalive pings no longer prevent idle characters from being disconnected.

All CI checks passing and ready for merge! 🚀

[leocagli]

La parte de validacion de paleta esta bien (paletteEntrySchema, el tope de grhIndex y los tests). Pero este PR no se puede mergear tal como esta:

El cambio en server/src/server.ts revierte #121. Saca lastPingAt del calculo de inactividad, y eso fue justamente lo que se corrigio porque los jugadores quedaban desconectados al bloquear la pantalla o quedarse quietos. Ese fix ya esta en produccion.

Pedido concreto: quitar todo el hunk de server/src/server.ts y dejar el PR solo con la validacion de paleta del issue #6. Si crees que los pings no deberian contar como actividad, abri un issue aparte con el argumento, no lo mezcles aca.

[Rodrigoue9]

Hola @leocagli! 👋

Listo el cambio solicitado: en el commit 912a78b he revertido por completo el archivo server/src/server.ts a la versión exacta de upstream/main. De esta forma:

• Se preserva intacto el comportamiento de #121 (los pings siguen contando en lastPingAt para que los jugadores no sufran desconexiones indebidas).
• El PR feat(world-builder): register uploaded graphics and extend palette schemas (#6) #111 queda enfocado pura y exclusivamente en la validación de paletas del issue Etapa 1: registrar PNG subidos como graficos del motor y extender la paleta #6 (paletteEntrySchema, validación de rango de grhIndex y su suite de tests unitarios).

Queda listo para tu revisión final y merge. ¡Muchas gracias! 🙌

[Rodrigoue9]

¡Hola @leocagli! 👋 Espero que hayas tenido un excelente inicio de semana.

Te comento que acabo de sincronizar la rama del PR #111 con los últimos cambios de main (commit c66dd8b). Los 6/6 checks del CI de GitHub Actions están 100% en verde y el PR quedó limpio y listo para tu merge final cuando gustes.

Asimismo, ya quedó abierto el PR #379 (para la Issue #10) con los 22 tests unitarios de Vitest pasando y validación BFS con rollback atómico.

¡Muchísimas gracias por el merge del PR #218! Ya tengo la wallet Stellar lista y configurada en el perfil de GrantFox para cuando tengas un momento para procesar la liberación en la plataforma.

¡Quedo a total disposición por cualquier duda o ajuste y te deseo una excelente semana! 🙌

[Rodrigoue9]

¡Hola @leocagli! Espero que estés muy bien. 🙌

Te dejo un breve resumen de estado para cuando hagas la próxima ronda de revisiones:

• PR feat(world-builder): register uploaded graphics and extend palette schemas (#6) #111 (c66dd8b — Palette schemas & uploaded graphics): Rebaseado con main, mergeable_state: clean y 6/6 checks de CI en verde.
• PR feat(world-builder): exit validation with BFS connectivity check and atomic rollback (#10) #379 (276c672 — Etapa 2: Validación BFS de salidas de mapa y rollback atómico Etapa 2: edicion de salidas entre mapas #10): mergeable_state: clean, 7/7 checks en verde y 22 tests unitarios en Vitest pasando.
• PR feat(world-builder): NPC placement, movement, and map persistence API (Closes #8) #218 (NPC placement): Ya mergeado en main (queda pendiente solo el release en GrantFox cuando tengas un momento).

También dejé propuestas técnicas detalladas en v0-piggy-city (#14, #11, #10, #18 y #16) listas para arrancar apenas asignes. ¡Muchas gracias!