A subpackage of `@galacean/engine`. A subpackage of `@galacean/engine`. # Galacean Engine

![npm-size](https://img.shields.io/bundlephobia/minzip/@galacean/engine) ![npm-download](https://img.shields.io/npm/dm/@galacean/engine) [![codecov](https://codecov.io/gh/galacean/engine/branch/main/graph/badge.svg?token=KR2UBKE3OX)](https://codecov.io/gh/galacean/engine) Galacean is a **web-first** and **mobile-first** high-performance real-time interactive engine. Use **component system design** and pursue ease of use and light weight. Developers can independently use and write Typescript scripts to develop projects using pure code. ## Features - 🖥 **Platform** - Suppport HTML5 and wechat minigame - 🔮 **Graphics** - Advanced 2D + 3D graphics engine - 🏃 **Animation** - Powerful animation system - 🧱 **Physics** - Powerful and easy-to-use physical features - 👆 **Input** - Easy-to-use interactive capabilities - 📑 **Scripts** - Use TypeScript to write logic efficiently ## Installation To install, use: ```sh npm install @galacean/engine ``` This will allow you to import engine entirely using: ```javascript import * as GALACEAN from "@galacean/engine"; ``` or individual classes using: ```javascript import { Engine, Scene, Entity } from "@galacean/engine"; ``` ## Usage ```typescript // Create engine by passing in the HTMLCanvasElement id and adjust canvas size const engine = await WebGLEngine.create({ canvas: "canvas-id" }); engine.canvas.resizeByClientSize(); // Get scene and create root entity const scene = engine.sceneManager.activeScene; const rootEntity = scene.createRootEntity("Root"); // Create light const lightEntity = rootEntity.createChild("Light"); const directLight = lightEntity.addComponent(DirectLight); lightEntity.transform.setRotation(-45, -45, 0); directLight.intensity = 0.4; // Create camera const cameraEntity = rootEntity.createChild("Camera"); cameraEntity.addComponent(Camera); cameraEntity.transform.setPosition(0, 0, 12); // Create sphere const meshEntity = rootEntity.createChild("Sphere"); const meshRenderer = meshEntity.addComponent(MeshRenderer); const material = new BlinnPhongMaterial(engine); meshRenderer.setMaterial(material); meshRenderer.mesh = PrimitiveMesh.createSphere(engine, 1); // Run engine engine.run(); ``` ## Links - [Official Site](https://oasisengine.cn) - [Examples](https://oasisengine.cn/#/examples/latest) - [Documentation](https://oasisengine.cn/#/docs/latest/cn/install) - [API References](https://oasisengine.cn/#/api/latest/core) ## License The engine is released under the [MIT](https://opensource.org/licenses/MIT) license. See LICENSE file. A subpackage of `@galacean/engine`. A subpackage of `@galacean/engine`. ## Installation To install, use: ```sh npm install @galacean/engine-physics-lite ``` This will allow you to import engine entirely using: ```javascript import * as PHYSICS_LITE from "@galacean/engine-physics-lite"; ``` or individual classes using: ```javascript import { LitePhysics } from "@galacean/engine-physics-lite"; ``` ## Usage ```typescript // Create engine by passing in the HTMLCanvasElement id and adjust canvas size const engine = await WebGLEngine.create({ canvas: "canvas-id" }); // Initialize physics manager with LitePhysics. engine.physicsManager.initialize(LitePhysics); ...... // Run engine. engine.run(); ``` ## Installation To install, use: ```sh npm install @galacean/engine-physics-physx ``` This will allow you to import engine entirely using: ```javascript import * as PHYSICS_PHYSX from "@galacean/engine-physics-physx"; ``` or individual classes using: ```javascript import { PhysXPhysics } from "@galacean/engine-physics-physx"; ``` ## Usage ```typescript // Create engine by passing in the HTMLCanvasElement id and adjust canvas size const engine = await WebGLEngine.create({ canvas: "canvas-id" }); // Initialize physics manager with PhysXPhysics. engine.physicsManager.initialize(PhysXPhysics); ...... // Run engine. engine.run(); ``` A subpackage of `@galacean/engine`. ## Installation ```sh npm install @galacean/engine-shaderlab ``` ## Usage ```typescript import { ShaderLab } from "@galacean/engine-shaderlab"; // Create ShaderLab const shaderLab = new ShaderLab(); // Create engine with shaderLab const engine = await WebGLEngine.create({ canvas: "canvas", shaderLab }); ...... // Create shader by galacean shader code directly const shader = Shader.create(galaceanShaderCode); ....... // Run engine engine.run() ``` There are two versions of ShaderLab: `Release` and `Verbose`. The `Verbose` version offers more user-friendly diagnostic information for debug ShaderLab compilation errors, while the Release version provides superior performance. you can use `Verbose` version by import: ```ts import { ShaderLab } from "@galacean/engine-shaderlab/verbose"; ``` ## CFG Grammar conflict detection The Galacean ShaderLab syntax is defined using Context-Free Grammar (CFG) and is documented within the `\*.y` file. When modifications to the ShaderLab syntax are required, it is recommended to make changes to the existing CFG syntax file, and employ [Bison](https://www.gnu.org/software/bison/manual/bison.html) to detect any potential grammar conflicts. ```sh bison ./Parser.y -r all ``` A subpackage of `@galacean/engine`. # @galacean/engine-ui `@galacean/engine-ui` is a UI library designed for the `@galacean/engine`, this library enables developers to create and manage user interfaces efficiently within their **Galacean-based** applications. It is important to note that it is currently in an **experimental version**. ## Features - **Rendering components**: Includes `Image` and `Text`. - **Interactive Components**: Include `Button`, as well as other planned basic rendering components to be added in the future. - **Event Handling**: Supports the dispatch and bubbling of events such as `onPointerEnter`, `onPointerExit`,`onPointerDown`, `onPointerUp`, `onPointerClick`, `onPointerDrag` and `onPointerDrop`. - **Optimized Performance**: Designed to run smoothly with the Galacean engine. ## Installation To use `@galacean/engine-ui` in your project, install it via npm: ```bash npm install @galacean/engine-ui ``` ## Getting Started Here is a simple example to help you get started: ```typescript import { AssetType, Camera, Sprite, Texture2D, Vector3, WebGLEngine } from "@galacean/engine"; import { CanvasRenderMode, Image, ResolutionAdaptationMode, UICanvas } from "@galacean/engine-ui"; // Initialize engine and scene const engine = await WebGLEngine.create({ canvas: "canvas" }); const scene = engine.sceneManager.activeScene; const rootEntity = scene.createRootEntity(); // Create camera const cameraEntity = rootEntity.createChild("Camera"); cameraEntity.transform.position = new Vector3(0, 0, 10); const camera = cameraEntity.addComponent(Camera); camera.farClipPlane = 200; camera.nearClipPlane = 0.3; // Create canvas const canvasEntity = rootEntity.createChild("canvas"); const canvas = canvasEntity.addComponent(UICanvas); canvas.renderMode = CanvasRenderMode.ScreenSpaceCamera; canvas.resolutionAdaptationMode = ResolutionAdaptationMode.HeightAdaptation; canvas.distance = 100; canvas.renderCamera = camera; // Create Image const imageEntity = canvasEntity.createChild("image"); const image = imageEntity.addComponent(Image); engine.resourceManager .load({ url: "https://xxx.png", type: AssetType.Texture2D }) .then((texture) => { image.sprite = new Sprite(engine, texture); }); // Run the engine engine.run(); ``` Easier operations in the [Editor](https://galacean.antgroup.com/editor/). ## Documentation For detailed documentation, visit [the official documentation site](https://galacean.antgroup.com/engine). ## Installation `@galacean/engine-xr-webxr` is one of the implementation backends of xr. If your XR application interface is WebXR standard, please introduce this package. To install, use: ```sh npm install @galacean/engine-xr-webxr ``` This will allow you to import engine entirely using: ```javascript import { WebXRDevice } from "@galacean/engine-xr-webxr"; import { XRHitTest, XRSessionMode } from "@galacean/engine-xr"; ``` ## Usage ```typescript import { WebXRDevice } from "@galacean/engine-xr-webxr"; import { XRHitTest, XRSessionMode } from "@galacean/engine-xr"; // Create engine by passing in the HTMLCanvasElement WebGLEngine.create({ canvas: "canvas", xrDevice: new WebXRDevice(), }).then((engine) => { // Users need to actively click the button to enter XR XRButton.onClick = function () { this.engine.xrManager.enterXR(XRSessionMode.AR).then( () => { console.log("Enter AR"); }, (error) => { console.log("Not supported AR", error); } ); }; }); ...... ``` ## Installation `@galacean/engine-xr` is the implementation layer of XRManager and is a necessary package for developing XR applications. To install, use: ```sh npm install @galacean/engine-xr ``` This will allow you to import engine entirely using: ```javascript import { WebXRDevice } from "@galacean/engine-xr-webxr"; import { XRHitTest, XRSessionMode } from "@galacean/engine-xr"; ``` ## Usage ```typescript import { WebXRDevice } from "@galacean/engine-xr-webxr"; import { XRHitTest, XRSessionMode } from "@galacean/engine-xr"; // Create engine by passing in the HTMLCanvasElement WebGLEngine.create({ canvas: "canvas", xrDevice: new WebXRDevice(), }).then((engine) => { // Users need to actively click the button to enter XR XRButton.onClick = function () { this.engine.xrManager.enterXR(XRSessionMode.AR).then( () => { console.log("Enter AR"); }, (error) => { console.log("Not supported AR", error); } ); }; }); ...... ``` # Anti-Over-Engineering Only change what was asked. Simplest solution first. When unsure, ask. Do not modify unrequested code, add abstractions without a concrete need, import unnecessary dependencies, rewrite entire files for small changes, or add error handling for impossible scenarios. Before delivery: verify you only changed requested code, check for simpler approaches, confirm no unrequested files were touched.

core Documentation

Explore Related Technologies & Topics