Skip to content

Commit

Permalink
docs: finish fundamentals
Browse files Browse the repository at this point in the history
  • Loading branch information
Gugustinette committed Aug 30, 2024
1 parent eda394a commit ff98c97
Show file tree
Hide file tree
Showing 3 changed files with 118 additions and 0 deletions.
45 changes: 45 additions & 0 deletions docs/guide/cameras.md
Original file line number Diff line number Diff line change
@@ -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. |
8 changes: 8 additions & 0 deletions docs/guide/lights.md
Original file line number Diff line number Diff line change
@@ -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.
65 changes: 65 additions & 0 deletions docs/guide/scene.md
Original file line number Diff line number Diff line change
@@ -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.
:::

0 comments on commit ff98c97

Please sign in to comment.