Cross-Platform

devicesGuideline

If a project targets multiple platforms — parity is enforced from commit #1.

Rule

If a project declares more than one platform target (e.g. desktop + Android), every commit must build and pass on all declared targets. Platform parity is enforced from the first commit, not retrofitted later.

Why

Retrofitting mobile support onto a desktop-first codebase is exponentially more expensive than building for both from the start. Desktop-only assumptions (filesystem paths, unlimited RAM, persistent GL context, mouse input, synchronous I/O on main thread) silently embed themselves throughout the codebase. By the time someone says "now let's port", the cost is no longer a port — it's a rewrite.

How

When a project's platform-targets.md declares multiple platforms, the AI enforces platform parity at every lifecycle step. The AI blocks any change that introduces a platform-specific dependency without a PAL (Platform Abstraction Layer) boundary.

Platform-Specific Assumptions to Catch

Category	Examples
Filesystem / Storage	Direct paths, hardcoded separators — Android uses Scoped Storage and AAssetManager
Memory / Resources	Assuming >4 GB RAM (mobile gets 512 MB–1 GB), no LOD/streaming
Graphics / Rendering	Wide subgroup ops, persistent GL context, BC7 without ASTC fallback
Input	Mouse coords without touch abstraction, no rotation/soft-keyboard handling
Threading / Lifecycle	Sync I/O on main thread (ANR on Android), no `onPause`/`onResume`
Build / Distribution	No size budget, x86_64 only (missing arm64-v8a), no Gradle/NDK alongside CMake

Platform Abstraction Layer (PAL)

core/         ← platform-agnostic, references only PAL interfaces
pal/          ← interface definitions
pal/desktop/  ← desktop implementations
pal/android/  ← Android implementations

• core/ must never import platform headers directly
• Every platform-specific operation goes through a PAL interface
• PAL implementations are compile-time selected
• A new PAL interface requires an ADR

Asset Dual-Target Rule

Asset Type	Desktop	Android
Textures	BC7 / DXT	ASTC / ETC2
Shaders	SPIR-V (desktop Vulkan)	SPIR-V (mobile) or GLSL ES
Models	Full LOD chain	Reduced LOD + streaming
Bundles	No size limit	Budget per asset pack

An asset pipeline that only outputs one format is a gate violation.

menu_book guidelines/cross-platform.mdopen_in_new