diff --git a/docs/guide/cameras.md b/docs/guide/cameras.md index e8350336..3219e831 100644 --- a/docs/guide/cameras.md +++ b/docs/guide/cameras.md @@ -1 +1,46 @@ # Cameras + +Cameras are used to render a scene from a specific point of view. They are attached to a scene and are used to render the scene to the screen. + +However, they're technically very different in 2D and 3D scenes, so we'll cover them separately. + +## 3D Cameras + +In 3D scenes, cameras technically exist the same way you would think of a camera in real life. They have a position, a rotation, and a field of view. + +Every camera in `@fibbojs/3d` extends the [PerspectiveCamera](https://threejs.org/docs/?q=Persp#api/en/cameras/PerspectiveCamera) class from Three.js. + +To learn more about cameras in Three.js, you can check the [Three.js documentation](https://threejs.org/manual/#en/cameras). + +## 2D Cameras + +In 2D scenes, cameras are a bit different as 2D environments don't have a concept of perspective. Instead, they have a position and a zoom level. + +But as the concept of camera is still useful to think about how the scene is rendered, we still have camera classes in `@fibbojs/2d`. + +Under the hood, they're just cleverly managing the scene's viewport based on [pixi-viewport](https://github.com/davidfig/pixi-viewport?tab=readme-ov-file). + +## Changing the camera of a scene + +You can change the camera used to render the scene by setting the `camera` property of the scene. + +```typescript +// Attach a camera to the character +scene.camera = new FGameCamera({ + target: character, +}) +``` + +## Available cameras + +Here are the available cameras in Fibbo : + +| Camera | Available in 2D | Available in 3D | Description | +| ------------------ | --------------- | --------------- | ------------------------------------------------------------------------------------------------------ | +| FGameCamera | ❌ | ✅ | A camera that follows a target and can be rotated. Enables a third-person view and locking the cursor. | +| FOrbitCamera | ❌ | ✅ | More raw version of the game camera. | +| FAttachedCamera | ✅ | ✅ | A camera attached to a given target. | +| FFixedCamera | ✅ | ✅ | A fixed camera that doesn't move. | +| FPointerLockCamera | ❌ | ✅ | Similar to the game camera but behaves like a first-person shooter. | +| FFreeCamera | ✅ | ❌ | A camera that can be moved freely in the scene. | +| FCamera | ✅ | ✅ | The base class for all cameras. | diff --git a/docs/guide/lights.md b/docs/guide/lights.md index 04f0b52e..d41ff7ad 100644 --- a/docs/guide/lights.md +++ b/docs/guide/lights.md @@ -1 +1,9 @@ # Lights + +As lights are still not supported natively in Fibbo, you should still use the underlying libraries to create and manage lights in your scene. + +By default, the 2D starter does not include any kind of light, and the 3D starter includes a basic [AmbientLight](https://threejs.org/docs/#api/en/lights/AmbientLight). + +To learn more about how to manage lights in Three.js, you can check the [Three.js documentation](https://threejs.org/manual/#en/lights). + +We are planning to add a light system in Fibbo in the future, but for now, you should use the underlying libraries directly. diff --git a/docs/guide/scene.md b/docs/guide/scene.md index e697f3f4..121aeae4 100644 --- a/docs/guide/scene.md +++ b/docs/guide/scene.md @@ -1 +1,66 @@ # Scene + +The `Scene` class represents the 2D or 3D scene that will be responsible for storing and rendering all the components. + +## What is a scene ? + +A scene is a class that extends the [`FScene`](/api/core/classes/FScene) core class. It represents a 2D or 3D environment where you can add components, cameras, lights, and more. + +Its main purpose is to initialize the technical environment for your game, aswell as managing the lifecycle of the components and render them on the screen. + +## Creating a scene + +Creating a scene involves several steps : + +- Import the `FScene` class from the `@fibbojs/3d` library. +- Create a new instance of the `FScene` class. +- Calling the `init` method to initialize the scene. +- (optional) Calling the `initPhysics` method to initialize the physics engine. + +So every Fibbo application should start with something like this : + +```typescript +import { FScene } from '@fibbojs/3d' + +// As the `init` and `initPhysics` methods are asynchronous, we need to use an async function. +// Not required if your environment supports top-level await. +(async () => { + const scene = new FScene() + await scene.init() + await scene.initPhysics() +})() +``` + +## Adding components to the scene + +Once the scene is created, you can add components to it using the `addComponent` method. + +```typescript +const cube = new FCube() +scene.addComponent(cube) +``` + +As soon as you add a component to the scene, it will be rendered on the screen each frame. + +## Hooks + +The `Scene` class exposes several hooks that you can use to interact with the scene and its components. This feature took inspiration from the [Vue Lifecycle Hooks](https://vuejs.org/guide/essentials/lifecycle.html) system, but it is still very experimental. + +Here is a list of the available hooks : +- `onFrame` : Called every frame by the scene to update the components. +- `onComponentAdded` : Called when a component is added to the scene. + +```typescript +scene.onFrame(() => { + // Do something on the scene every frame +}) +scene.onComponentAdded((component: FComponent) => { + // Do something on a component added to the scene +}) +``` + +::: warning +The `onFrame` method on a scene is used to add a callback that will be called every frame by the scene itself. You can add as many callbacks as you want, and they will be called in the order they were added. + +The `onFrame` method on a component is a method that will be called every frame by the scene, to update its components. You should not call this method directly : if you want to change the behavior of a component, you should extend it and override the `onFrame` method. +:::