PHPackages                             phpolygon/phpolygon - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. phpolygon/phpolygon

ActiveLibrary[Utility & Helpers](/categories/utility)

phpolygon/phpolygon
===================

PHP-native game engine with AI-first authoring

v0.17.3(1w ago)148[2 issues](https://github.com/phpolygon/phpolygon/issues)MITPHPPHP >=8.3CI passing

Since Mar 24Pushed 5d agoCompare

[ Source](https://github.com/phpolygon/phpolygon)[ Packagist](https://packagist.org/packages/phpolygon/phpolygon)[ RSS](/packages/phpolygon-phpolygon/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (10)Dependencies (9)Versions (63)Used By (0)

 [![PHPolygon](logo.png)](logo.png)

 **PHP-native game engine with AI-first authoring**

 [Features](#features) · [Architecture](#architecture) · [Getting Started](#getting-started) · [Examples](#examples) · [Roadmap](#roadmap)

---

PHPolygon is a standalone game engine written entirely in PHP. It uses [php-vio](https://github.com/hmennen90/php-vio) as its primary unified backend for window management, input, audio, and 2D/3D rendering. When php-vio is not available, it falls back to [php-glfw](https://github.com/mario-deluna/php-glfw)(OpenGL 4.1 / NanoVG) and [php-vulkan](https://github.com/hmennen90/php-vulkan)for 3D graphics. The primary authoring tool is Claude Code — scenes, components, and game logic are generated and iterated on through AI-assisted workflows.

Features
--------

[](#features)

- **Hybrid ECS** — Entities as PHP objects, Components with lifecycle hooks (`onAttach`, `onUpdate`, `onDetach`), Systems for cross-entity logic
- **Attribute-driven serialization** — `#[Property]`, `#[Range]`, `#[Hidden]`, `#[Serializable]` on component fields, zero manual `toJson()`/`fromJson()`
- **Scene system** — PHP-canonical scene definitions, SceneManager with single/additive loading, parent-child entity hierarchy, persistent entities
- **Prefabs** — Reusable entity templates as PHP classes
- **PHP ↔ JSON transpiler** — Bidirectional conversion for the editor pipeline; PHP is always the source of truth, JSON is the intermediate format
- **Physics** — RigidBody2D, BoxCollider2D, AABB collision detection + response, raycasting, trigger/collision events
- **Input mapping** — Action-based system with named bindings (`jump`, `shoot`) instead of raw key codes, axis support for movement
- **Audio** — AudioManager with channel-based mixing (SFX, Music, UI, Ambient, Voice), per-channel volume/mute, pluggable backend interface
- **Localization** — LocaleManager with JSON translation files, dot-notation keys, placeholder replacement (`:param`), fallback locale
- **Save system** — Slot-based SaveManager with metadata, play time tracking, JSON persistence
- **UI system** — Dual-paradigm: immediate-mode (UIContext) for debug overlays, retained-mode (Widget tree) for complex UIs with measure/layout/draw pipeline
- **Editor infrastructure** — Inspector metadata extraction via Reflection, component registry with category grouping, SceneDocument with undo/redo, command bus for editor operations, NativePHP desktop app with Vue 3 SPA
- **Build system** — 7-phase pipeline producing standalone executables: PHAR creation, static PHP binary (micro.sfx), platform packaging (macOS .app, Linux, Windows), plus a native iOS/iPadOS `.app` via embed libphp.a + Xcode
- **Headless mode** — Full engine without GPU: `EngineConfig(headless: true)`swaps in NullWindow, NullRenderer2D, NullTextureManager for CI/testing
- **Visual regression testing** — Playwright-style VRT with GD software renderer, YIQ pixel comparison, automatic snapshot management, diff image generation
- **Math primitives** — Vec2, Vec3, Mat3, Rect as immutable value objects
- **Rendering** — Vio unified backend (primary), NanoVG 2D fallback, Vulkan/Metal/OpenGL 3D, Camera2D, TextureManager, SpriteSheet
- **Splash screen** — Engine-branded "Developed with PHPolygon" splash at startup with fade animation, renderer info display, configurable duration, skippable

Architecture
------------

[](#architecture)

```
PHPolygon\
├── ECS\              Entity, World, Component/System interfaces, Attributes
├── Scene\            Scene, SceneManager, SceneBuilder, Prefabs, Transpiler
├── Component\        Transform2D, SpriteRenderer, RigidBody2D, BoxCollider2D, ...
├── System\           Physics2DSystem, Renderer2DSystem, AudioSystem, InputMapSystem
├── Rendering\        VioRenderer2D, Renderer2D (NanoVG), VioRenderer3D, OpenGLRenderer3D,
│                     VulkanRenderer3D, MetalRenderer3D, NullRenderer2D/3D, Camera2D,
│                     VioTextureManager, TextureManager, Color
├── Runtime\          VioWindow, Window (GLFW), NullWindow, GameLoop, VioInput, Input, Clock
├── Physics\          Collision2D, RaycastHit2D
├── Input\            InputMap, InputAction, InputBinding
├── Audio\            AudioManager, AudioChannel, AudioBackendInterface
├── Locale\           LocaleManager (i18n with JSON files, fallback locale)
├── SaveGame\         SaveManager, SaveSlotInfo (slot-based persistence)
├── UI\               UIContext (immediate), Widget tree (retained), UIStyle
├── Math\             Vec2, Vec3, Mat3, Rect
├── Build\            GameBuilder, PharBuilder, StaticPhpResolver, PlatformPackager
├── Testing\          GdRenderer2D, ScreenshotComparer, VisualTestCase
├── Editor\           Inspector, Registry, Commands, SceneDocument, ProjectManifest
└── Event\            EventDispatcher, scene/collision/trigger events

```

### Design Principles

[](#design-principles)

- **PHP is canonical** — Scenes are PHP classes, version-controlled as code. JSON is a derived artefact for editor tooling.
- **Attribute-driven** — Component metadata (`#[Property]`, `#[Range]`, `#[Category]`) drives both serialization and editor UI generation.
- **No cross-boundary logic** — Components own per-entity behavior, Systems own cross-entity logic. Never mix the two.
- **Layered rendering** — `RenderContextInterface` base, `Renderer2DInterface`(Vio or NanoVG), `Renderer3DInterface` (Vio, Vulkan, Metal, OpenGL) with `RenderCommandList` command buffers. Backend auto-detected at startup.

Getting Started
---------------

[](#getting-started)

### Requirements

[](#requirements)

- PHP 8.3+
- [php-vio](https://github.com/hmennen90/php-vio) extension (primary: unified window, input, audio, 2D/3D rendering)
- **Or** [php-glfw](https://github.com/mario-deluna/php-glfw) extension (fallback: OpenGL 4.1 + NanoVG)
- [php-vulkan](https://github.com/hmennen90/php-vulkan) extension (optional: native Vulkan 3D backend)
- Composer

### Installation

[](#installation)

```
composer require phpolygon/phpolygon
```

### Hello World

[](#hello-world)

```