README

Ichiloto 2D Game Engine

Ichiloto 2D Game Engine is a PHP-based engine for creating JRPG-style games, inspired by classics such as Final Fantasy 1-6 and Dragon Quest. Terminal presentation remains the default. An optional GPUI renderer is under development; PHP continues to own gameplay, input bindings, animation state and saves.

Features

Terminal worlds: Styled text, retained-cell rendering, camera scrolling, notifications and HUD overlays.
Battle systems: Traditional turn-based and active-time combat, with configurable battle-entry rules.
Game systems: Maps, events, quests, dialogue, NPCs, inventory, equipment and character progression.
Persistence and audio: Save/load support, music and sound effects; see their runtime requirements below.
Optional graphical presentation: Sprite sheets, field tiles and a locally playtested graphical battle foundation. Native player distribution is not yet available.

Installation

The PHP package requires PHP 8.4.1 or later and Composer:

composer require ichiloto/engine

Project scaffolding and launch commands belong to Ichiloto Console; the editor is a separate package. Installing the PHP package does not install a native GPUI executable. See audio for sound playback requirements and local checks for contributor setup.

GPUI Availability

A clean Engine checkout is not a complete native-player installation. resources/renderers/ contains its installation README. Native executables and the generated installation manifest are ignored by Git. There is currently no published renderer package or Console command to install one. Selecting GPUI cannot provision a missing executable automatically.

Cargo instructions are for developers building the separate ichiloto/gpui-renderer repository, which contains Cargo.toml. Do not run them from this Engine repository or its renderer resources folder. Players should receive compatible, verified platform packages without installing Rust or build tools; that delivery work is unfinished.

The graphical battle foundation has been playtested on macOS/Apple Silicon. A subsequent, local and unpublished correction removes the Renderer window's blanket non-macOS rejection using shared GPUI maximize/restore handling. It has macOS validation only and is not delivered by pulling Engine. Linux/WSLg remains untested; WSLg uses Linux PHP and a Linux renderer. Native Windows additionally needs a correct process transport. Neither a portable API nor a matching platform identifier establishes complete platform support.

The integration roadmap separates accepted work from remaining animation, effects, graphical UI and platform delivery.

Project Vocabulary

Runtime menus and battle results read developer-owned display terms from vocab in the project configuration. currency.name and currency.symbol apply to balances, purchases, rewards and learning costs in both Terminal and graphical presentation. An explicitly empty currency symbol is supported. The game, shop and command groups rename controls; stats and battle provide optional stat and battle headings. Omitted terms retain existing defaults.

Locale-specific entries at vocab.<locale> override base terms. Maps such as command.summon_by_role merge translated entries with the base map. Full authored sentences remain in the separate message catalog; vocabulary does not rewrite story text, stored data keys or gameplay identity.

Battle menus carry BattleCommand descriptors with a stable type and a display name, replacing the former executable-attack placeholders. BattleCommandCatalog::buildOptions() accepts a BattleCommandType; legacy name/id strings are still accepted at that API boundary. Renaming a command does not change its targeting, availability, action category or icon role.

Documentation

Contributing and Git workflow

Read GIT_WORKFLOW.md and install the Git guards with sh scripts/install-git-guards.sh before contributing. All changes integrate into develop; main is updated only by a PR from this repository's develop.

ichiloto / engine

Package info

Security

Statistics