API Three.js

`TransformComponent`

Classe de composant standard pour la transformation d'un objet Three.js.

position: Vector3
rotation: Euler
scale: Vector3

`Object3DComponent`

Encapsule un Object3D Three.js pour qu'il puisse vivre sur une entité.

`LightComponent`

Décrit une lumière à créer côté ECS.

type: LightType
color: string
intensity: number

Types disponibles:

LightType.Ambient
LightType.Directional

`createThreeWorld(scene)`

Crée un World préconfiguré avec:

SceneAttachmentSystem
TransformSyncSystem

Utilise-le quand tu n'as besoin que d'une seule scène.

`AbstractGame`

Classe de base pour les jeux Three.js qui veulent éviter de recoder le même cycle de vie.

Elle fournit:

création du ThreeCanvasManager;
création et conservation d'un ThreeSceneManager;
boucle requestAnimationFrame;
resize automatique du canvas et des scènes;
rendu de la scène active;
changement de scène avec les touches numériques;
dispose() idempotent;
debug optionnel avec ?debug=true ou options.debug.
panneau FPS via stats.js;
panneau de contrôles live via Tweakpane.
verrouillage optionnel du ratio de rendu avec options.enforceAspectRatio.

Une scène consommée par AbstractGame doit exposer:

name: string
uiScene?: AbstractGameScene
resize(aspect: number): void
update(deltaTime: number): void
render(canvas: ThreeCanvasManager): void

Exemple

import { AbstractGame, AbstractGameAspectRatio, ThreeSceneManager } from "envy";

class Game extends AbstractGame<MyScene> {
  protected createScenes(sceneManager: ThreeSceneManager): MyScene[] {
    return [
      new MainMenuScene(sceneManager),
      new MatchScene(sceneManager)
    ];
  }
}

new Game().run(document.querySelector("#game"));

Avec un ratio verrouillé:

new Game().run(document.querySelector("#game"), {
  enforceAspectRatio: AbstractGameAspectRatio.SixteenNine
});

`run(container, options?)`

Démarre le jeu dans le conteneur donné.

Options:

canvas: options passées à ThreeCanvasManager, sauf container;
debug: force l'activation ou non des outils de debug;
debugClassName: classe CSS ajoutée au panneau stats.js;
debugPaneTitle: titre du panneau Tweakpane;
enforceAspectRatio: AbstractGameAspectRatio.Free, SixteenNine, SixteenTen ou OneOne;
initialSceneName: nom de scène à activer après la création des scènes;
keyboardSceneSwitching: active ou non le changement de scène avec les touches numériques.

`dispose()`

Arrête la boucle, retire les listeners, vide les scènes, détruit le canvas et retire les outils de debug.

`configureDebugPane(pane)`

Hook appelé uniquement quand le debug est actif. Il permet d'ajouter des inputs, sliders ou moniteurs Tweakpane sans créer d'UI HTML spécifique au jeu.

`TransformSyncSystem`

Copie les valeurs de TransformComponent vers les objets Three.js en utilisant une requête de composants.

`SceneAttachmentSystem`

Garde les instances de Object3D attachées à la scène active tant que l'entité existe.

`LightSystem`

Crée l'objet Three.js correspondant aux entités qui ont un LightComponent.

Le système ajoute un Object3DComponent à l'entité, puis SceneAttachmentSystem l'attache à la scène.

const entity = world.createEntity();
entity.addComponent(new LightComponent(LightType.Directional, "#ffffff", 3));
entity.addComponent(new TransformComponent()).position.set(3, 4, 5);

UI ECS Three.js

Envy expose une base d'UI responsive qui reste dans le rendu Three.js. Les éléments d'interface sont des entités ECS; les systèmes créent et positionnent des Mesh ou Sprite dans le plan de la caméra.

Composants:

UIElementComponent: ancre, pivot, taille responsive, offset et distance à la caméra.
UIPanelComponent: panneau couleur/opacité, rendu en Mesh, avec textureKey et hoverTextureKey pour les boutons texturés.
UITextComponent: texte rendu en texture Three.js puis affiché en Sprite.
UIAnchor: ancres standards (TopLeft, TopCenter, Center, BottomRight, etc.).

Systèmes:

UIPanelRenderSystem: crée/met à jour les panneaux.
UITextRenderSystem: crée/met à jour les sprites de texte.
UILayoutSystem: place et redimensionne les objets UI selon la caméra et son aspect ratio.

Chaque scène UI choisit explicitement ses systèmes:

this.world.addSystem(new UIPanelRenderSystem());
this.world.addSystem(new UITextRenderSystem());
this.world.addSystem(new UILayoutSystem(this.camera));

Exemple d'entité:

const title = this.world.createEntity();
title.addComponent(
  new UIElementComponent({
    anchor: UIAnchor.TopCenter,
    pivot: new Vector2(0.5, 1),
    size: new Vector2(0.5, 0.07),
    offset: new Vector2(0, -0.1)
  })
);
title.addComponent(new UITextComponent({ text: "Main menu" }));

Les valeurs size et offset sont exprimées en fraction du viewport visible à la distance de l'élément. L'UI suit donc le resize et les ratios verrouillés sans passer par une couche HTML/CSS.

UIPanelComponent.isFocused permet au système de choisir automatiquement la texture de survol quand hoverTextureKey est fourni.

`AssetsLoader`

Singleton de chargement et de cache d'assets Three.js.

Types supportés:

AssetType.Texture: charge une Texture;
AssetType.Image: charge une HTMLImageElement;
AssetType.Glb: charge un asset GLB/GLTF via GLTFLoader;
AssetType.Font: charge une font Three.js JSON via FontLoader;
AssetType.Json: charge du JSON;
AssetType.Audio: charge un AudioBuffer;
AssetType.Text: charge du texte;
AssetType.Binary: charge un ArrayBuffer.

const manifest = [
  { key: "mech", type: AssetType.Glb, url: "/assets/mech.glb" },
  { key: "portrait", type: AssetType.Texture, url: "/assets/portrait.png" },
  { key: "ui-font", type: AssetType.Font, url: "/assets/fonts/ui.typeface.json" }
] satisfies AssetManifest;

await AssetsLoader.getInstance().loadAll(manifest, {
  onProgress: ({ ratio }) => console.log(Math.round(ratio * 100))
});

const mech = AssetsLoader.getInstance().get("mech");

Le loader déduplique les clés du manifest, évite de recharger un asset déjà en cache, et expose unload(key) ou clear() pour libérer les assets jetables.

`ThreeSceneManager`

Gère plusieurs scènes nommées, chacune avec son propre World.

`AbstractThreeScene`

Classe de base minimale pour une scène Three.js pilotée par Envy.

Elle fournit:

création d'une scène managée via ThreeSceneManager;
caméra PerspectiveCamera par défaut;
resize de la caméra;
rendu via ThreeCanvasManager;
accès protégé à scene et world.

Elle ne décide pas des systèmes de gameplay. Chaque scène concrète ajoute ses propres systèmes dans son constructeur:

class MainMenuScene extends AbstractThreeScene {
  constructor(sceneManager: ThreeSceneManager) {
    super(sceneManager, "main-menu");

    this.world.addSystem(new MenuInputSystem());
  }
}

`AbstractThreeUiScene`

Variante de AbstractThreeScene pensée pour l'UI. Elle rend sa scène en overlay sans effacer la scène principale. Une scène de jeu peut exposer une propriété readonly uiScene pour que AbstractGame la mette à jour et la rende juste après la scène active.

class MainMenuScene extends AbstractThreeScene {
  readonly uiScene: MainMenuUiScene;

  constructor(sceneManager: ThreeSceneManager) {
    super(sceneManager, "main-menu");
    this.uiScene = new MainMenuUiScene(sceneManager);
  }
}

class MainMenuUiScene extends AbstractThreeUiScene {
  constructor(sceneManager: ThreeSceneManager) {
    super(sceneManager, "main-menu-ui");
  }
}

`createScene(name, scene?)`

Crée une scène nommée et son monde ECS.

`hasScene(name)`

Vérifie si une scène existe.

`getScene(name)`

Retourne une scène ou undefined.

`getActiveScene()`

Retourne la scène active ou undefined.

`getActiveWorld()`

Retourne le monde de la scène active ou undefined.

`setActiveScene(name)`

Change la scène active.

`update(deltaTime)`

Met à jour uniquement la scène active.

`updateScene(name, deltaTime)`

Met à jour une scène spécifique par son nom.

`removeScene(name)`

Supprime une scène, vide son graphe de scène et vide son monde.

`ThreeCanvasManager`

Gère un canvas de renderer Three.js avec la taille, le ratio d'aspect et le centrage.

`ThreeCanvasOptions`

container?: HTMLElement
width?: number
height?: number
aspectRatio?: number
antialias?: boolean
alpha?: boolean
center?: boolean

`getRenderer()`

Retourne le renderer Three.js sous-jacent.

`getCanvas()`

Retourne l'élément canvas géré.

`getSize()`

Retourne la taille logique actuelle du canvas.

`getAspectRatio()`

Retourne le ratio d'aspect forcé, s'il y en a un.

`setAspectRatio(aspectRatio)`

Met à jour le ratio d'aspect forcé.

`setSize(width, height?)`

Définit la taille du canvas tout en respectant le ratio d'aspect quand il est forcé.

`fitToContainer()`

Adapte le canvas à la taille actuelle du conteneur.

`centerCanvas()`

Réapplique les styles de centrage.

`render(scene, camera)`

Rend une scène Three.js avec la caméra fournie.

Passe { clear: false, clearDepth: true } en troisième argument pour rendre une scène en overlay, comme le fait AbstractThreeUiScene.

`dispose()`

Retire le canvas et détruit le renderer.

TransformComponent​

Object3DComponent​

LightComponent​

createThreeWorld(scene)​

AbstractGame​

Exemple​

run(container, options?)​

dispose()​

configureDebugPane(pane)​

TransformSyncSystem​

SceneAttachmentSystem​

LightSystem​

UI ECS Three.js​

AssetsLoader​

ThreeSceneManager​

AbstractThreeScene​

AbstractThreeUiScene​

createScene(name, scene?)​

hasScene(name)​

getScene(name)​

getActiveScene()​

getActiveWorld()​

setActiveScene(name)​

update(deltaTime)​

updateScene(name, deltaTime)​

removeScene(name)​

ThreeCanvasManager​

ThreeCanvasOptions​

getRenderer()​

getCanvas()​

getSize()​

getAspectRatio()​

setAspectRatio(aspectRatio)​

setSize(width, height?)​

fitToContainer()​

centerCanvas()​

render(scene, camera)​

dispose()​

`TransformComponent`

`Object3DComponent`

`LightComponent`

`createThreeWorld(scene)`

`AbstractGame`

Exemple

`run(container, options?)`

`dispose()`

`configureDebugPane(pane)`

`TransformSyncSystem`

`SceneAttachmentSystem`

`LightSystem`

UI ECS Three.js

`AssetsLoader`

`ThreeSceneManager`

`AbstractThreeScene`

`AbstractThreeUiScene`

`createScene(name, scene?)`

`hasScene(name)`

`getScene(name)`

`getActiveScene()`

`getActiveWorld()`

`setActiveScene(name)`

`update(deltaTime)`

`updateScene(name, deltaTime)`

`removeScene(name)`

`ThreeCanvasManager`

`ThreeCanvasOptions`

`getRenderer()`

`getCanvas()`

`getSize()`

`getAspectRatio()`

`setAspectRatio(aspectRatio)`

`setSize(width, height?)`

`fitToContainer()`

`centerCanvas()`

`render(scene, camera)`

`dispose()`