repository·v2·Indexed 23 days ago
https://github.com/eva-engine/eva.jsA high-performance front-end interactive game engine built on an Entity-Component-System (ECS) architecture using PixiJS for rendering. It features a modular plugin system including @eva/plugin-ui for UI components, @eva/plugin-ai for mapping scene elements to a DOM layer for LLM understanding, and a BehaviorScript system for managing gameplay logic via manifests, signals, and events.
Eva.js is a front-end game engine designed for interactive game projects. It is built on an ECS (Entity-Component-System) architecture, allowing for high extensibility through a customizable API.
Key features include:
The @eva/plugin-renderer-render-texture plugin provides a Phaser-style RenderTexture or DynamicTexture capability for Eva.js. It allows a GameObject to host an offscreen PixiJS RenderTexture.
You can manipulate the texture using declarative ops (operations) to perform tasks such as:
drawFrame)drawText)Additionally, you can use the saveAs option to save the resulting texture as a reusable resource key. This allows other components, such as Img or Sprite, to reference the generated texture by its key later in the scene.
@eva/plugin-renderer-dom-element plugin allows you to render standard HTML elements as part of the Eva.js scene. It overlays these DOM elements on top of (or below) the PixiJS canvas. The plugin automatically synchronizes the HTML elements' position and scale with a GameObject's Transform using the CSS transform property, ensuring they move and scale in sync with the game engine's coordinate system.The @eva/plugin-ui package contains 16 components driven by the UISystem.
Important Implementation Rule:
When using @eva/plugin-ui components in an example, you must only attach one UISystem per example. Do not attempt to attach separate systems for individual components.
BehaviorScripts can declare stable references to other parts of the scene or to assets.
Declared in manifest.nodes. Supports paths like self, .., relative child paths (Weapon/Muzzle), absolute scene paths (/arena/Enemy), or bare names (falling back to findByName).
ctx.getNode('name'), ctx.getRequiredNode('name'), or ctx.getNodes('name').BehaviorScript.nodes in the DSL.Declared in manifest.resources. Uses Eva's global resource manager.
ctx.getResourceName('key'), ctx.hasResource('key'), ctx.loadResource('key'), or ctx.loadRequiredResource('key').BehaviorScript.resources in the DSL.In v2 mode, animated source tiles (defined with animation.frames[]) are registered in record.animatedSpritesByAnimKey during the sprite-build phase.
An update() tick manages the animationDrivers, applying texture swaps to live sprites. Note that the animation tick is automatically skipped if the browser tab is hidden or if the WebGL context is lost.
A BehaviorScript instance can implement the following lifecycle methods to control its execution and state:
| Method | Description |
|---|---|
setup(ctx) | Initialization |
enterTree() | When entering the scene tree |
ready() | When ready to run |
process(frame) | Per-frame update |
lateProcess(frame) | Post-frame update |
physicsProcess(fixedFrame) | Fixed-step physics update |
input(event) | Handle input events |
unhandledInput(event) | Handle input not consumed by others |
onSignal(name, payload) | React to signals |
onEvent(name, payload, target) | React to events |
propsChanged(nextProps, previousProps) | React to property updates |
enable() / disable() | Manual activation/deactivation |
enabledChanged(enabled, previousEnabled) | React to enabled state changes |
pause() / resume() | Execution control |
exitTree() | When leaving the scene tree |
destroy() | Cleanup |
serializeState() | For state persistence |
restoreState(state) | For state restoration |
BehaviorScripts use two distinct paths for communication:
Declared in the manifest.signals array with direction: "listen" or "both". These are automatically subscribed via the global SignalBus and routed to the onSignal(name, payload) hook. This path is typed and visible to Editors/AI.
ctx.emitSignal('name', payload) or BehaviorScriptSystem.emitSignal(...).BehaviorScriptSystem.dispatchSignal(name, payload, target?) to bypass manifest requirements.Declared in manifest.events. These are routed to the onEvent(name, payload, target) hook. Supported targets include "self", "component", "gameObject", or a custom string provided during system initialization.
Use ctx.onSignal(name, listener) or ctx.onEvent(target, name, listener) for dynamic, local subscriptions inside setup(). These are automatically cleaned up on detachment. Failures in these listeners are reported as phase: "signal" or phase: "event" diagnostics.
The Tilemap component renders chunks within a single Container under the host GameObject's display container. Its behavior regarding transformations is as follows:
transform.position: Respected. Moving the host entity translates the entire tilemap.transform.rotation: Respected. The chunk container rotates with the host.transform.scale: Respected visually, but chunk geometry is not recomputed. Note that cell collision math (e.g., cullingBoundsHint) does not account for the host scale.transform.size: Ignored. Tilemap chunks are sized based on cellSize, not the host entity's size. Resizing the host entity will not resize the cells.To resize cells at runtime:
Do not mutate transform.size. Instead, update the cellSize prop on the Tilemap component. This emits a CHANGE event that triggers a system rebuild of the layer chunks.
The plugin automatically detects which rendering path to use based on the component props provided:
tileset: string prop is set. This uses a single tileset image and layers[].data[][].tilemapRef: string prop is set. This uses an external .tileset.json resource (via RESOURCE_TYPE.TILESET) and chunked layersV2[].cellData.chunks.Switching modes on a live entity (e.g., clearing tileset and setting tilemapRef) is supported via handleChange, which handles the teardown of previous containers and animation drivers.
Input actions are declared in the manifest.inputs array. The system automatically subscribes to @eva/plugin-input-action signals.
Configuration:
action: The name of the action (e.g., 'jump').phases: (Optional) The input phases to listen for (e.g., ['press']). If omitted, the system listens for press, release, and hold.Behavior:
When an input matches, the system dispatches an input(event) call to scripts. If a script handles the input (e.g., by setting event.handled = true), subsequent handlers are skipped.
The examples directory provides several ways to explore @eva/plugin-ui components:
src/plugin-ui-tour.ts provides a tour of all 16 components (UI, Button, FancyButton, CheckBox, Switcher, RadioGroup, ProgressBar, CircularProgressBar, Slider, DoubleSlider, Input, List, ScrollBox, Select, Dialog, MaskedFrame).src/plugin-ui-pixi-*.ts files provide single-story entries that correspond to the official @pixi/ui Storybook, allowing for pixel-perfect comparison and regression testing.src/plugin-ui-button-and-bar.ts: Demonstrates interaction between Button/Use Graphics and FancyButton with ProgressBar (e.g., updating HP bars via button clicks).src/plugin-ui-hud.ts: Demonstrates a combat HUD scenario using the plugin-ui v2 wrapper combined with Transform and Layout.