Skip to content

Commit

Permalink
add info regarding creating and destroying objects
Browse files Browse the repository at this point in the history
  • Loading branch information
hybridherbst committed Nov 24, 2024
1 parent d0a6a26 commit 24d5258
Showing 1 changed file with 17 additions and 7 deletions.
24 changes: 17 additions & 7 deletions documentation/networking.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,6 @@ There may be no ownership required, ownership may be allowed to be transferred t

When a user leaves a room, objects owned by that user will either be deleted or have ownership reset, depending on how the object was created.

### Dynamic objects: `syncInstantiate()` and `syncDestroy()`

> 🏗️ Under Construction
## Enable Networking for your project

1. Add a `SyncedRoom` component to your scene. By default, this will use networking infrastructure provided by Needle.
Expand All @@ -58,11 +54,12 @@ Ownership will be transferred to whoever starts dragging the object.
| `Duplicatable` | Handles duplicating objects. Duplicated objects are instantiated for everyone in the room. |
| `Deletable` | Handles deleting objects. Deletions are synchronized across the network. |
| `DeleteBox` | Handles deleting objects that have a "Deletable" component when they are dragged into a box volume. |
| `PlayerSync` | Helper component for synchronizing player-specific data. |
| `PlayerColor` | Each user gets assigned a random color upon joining a room. This component assigns that color to the object's main material. |
| `PlayerSync` | Powerful component that instantiates a specific object for each connected player. |
| `PlayerState` | Add this component to objects that are assigned to `PlayerSync`. |
| `PlayerColor` | Simple component for player-specific colors. Each user gets assigned a random color upon joining a room. This component assigns that color to the object's main material. |
| `WebXR` | Handles synchronizing user avatars (hands and heads). |

## Automatic Networking for Components
## Automatic Networking for custom Components

Fields in your own components can be networked very easily. Changes to the field will automatically be detected and sent to all users in the room. The changes are also persisted as part of the Room State, so users that join the room later will receive the current state of the field as well, ensuring everyone sees the same data.

Expand Down Expand Up @@ -101,6 +98,19 @@ Note that syncField has an optional parameter to specify a method that should be
If you're using a custom project setup, you need to have ``experimentalDecorators: true`` in your ``tsconfig.json`` file for syncField decorators to work. Projects created with Needle Starters have this enabled by default.
:::

## Creating and destroying objects

Often, you want to create and destroy objects at runtime, and of course these changes should be synchronized across the network.

The `PlayerSync` component simplifies this process by automatically instantiating a specific object for each connected player.
When a player leaves the room, the object is destroyed for all users.

Additionally, Needle Engine provides two high-level methods:
- [`syncInstantiate()`](https://engine.needle.tools/docs/api/latest/syncInstantiate) to duplicate objects across the network.
- [`syncDestroy()`](https://engine.needle.tools/docs/api/latest/syncDestroy) to destroy objects across the network.

> 🏗️ Code Samples Under Construction
## Manual Networking

Needle Engine also provides a low-level API for sending and receiving messages. We call this "manual networking". The principles are the same, but you're in full control for sending and receiving messages and how to handle them.
Expand Down

0 comments on commit 24d5258

Please sign in to comment.