Skip to content

Commit 586f153

Browse files
cazalacazala
committed
chore: update readmes
1 parent 75bba39 commit 586f153

File tree

7 files changed

+686
-37
lines changed

7 files changed

+686
-37
lines changed

‎README.md

Lines changed: 150 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,171 @@
1-
# Decentraland SDK 7
1+
# Decentraland SDK Toolchain
22

3-
[![codecov](https://codecov.io/gh/decentraland/js-sdk-toolchain/branch/main/graph/badge.svg?token=F7J331CGP6)](https://codecov.io/gh/decentraland/js-sdk-toolchain)
3+
This monorepo contains the core packages for Decentraland's SDK and development tools.
44

5-
Use the Decentraland Software Development Kit v7 to create experiences for the Decentraland ecosystem.
5+
## Packages
66

7-
## Create a scene and preview it locally
7+
- **[@dcl/sdk](packages/@dcl/sdk/README.md)**: Main SDK package for building Decentraland scenes using TypeScript/JavaScript
8+
- **[@dcl/ecs](packages/@dcl/ecs/README.md)**: Core Entity Component System (ECS) implementation with CRDT-based networking support
9+
- **[@dcl/react-ecs](packages/@dcl/react-ecs/README.md)**: React bindings for the ECS, providing a declarative way to build UIs using React's component model and JSX syntax
10+
- **[@dcl/js-runtime](packages/@dcl/js-runtime/README.md)**: TypeScript definitions for the Decentraland scene runtime environment.
11+
- **[@dcl/inspector](packages/@dcl/inspector/README.md)**: Visual editor and development tool for building Decentraland scenes with real-time preview
12+
- **[@dcl/sdk-commands](packages/@dcl/sdk-commands/README.md)**: CLI tools and commands for scene development, testing, and deployment
13+
- **[@dcl/playground-assets](packages/@dcl/playground-assets/README.md)**: Contains the built assets required by the Decentraland Playground
814

9-
1. Run `npx @dcl/sdk-commands init` on an empty folder.
10-
2. Preview it with `npm run start`!
15+
## Quick Start
1116

12-
## Repository guide
17+
1. Clone the repository:
1318

14-
This repository consists of the following components, packaged for the `nodejs`/`npm` ecosystem (find them under the respective subfolder in `packages`):
19+
```bash
20+
git clone https://github.com/decentraland/js-sdk-toolchain.git
21+
cd js-sdk-toolchain
22+
```
1523

16-
* `@dcl/react-ecs`: a framework to create scenes using the [React](https://reactjs.org) framework
17-
* `@dcl/sdk`: contains all the packages that a scene needs to work.
18-
* `@dcl/ecs`: an engine used to render things on screen
19-
* `@dcl/sdk-commands`: contains the command line interface
20-
* `@dcl/inspector`: Editor interface.
24+
2. Install dependencies and build all packages:
2125

22-
And some internal or maybe useful packages if you're digging deeper into how the Decentraland runtime works:
26+
```bash
27+
make install
28+
make build
29+
```
2330

24-
* `@dcl/js-runtime`: the `js-runtime` contains the typings for the environment variables available in the sandboxed execution environment for scenes
25-
* `@dcl/playground-assets`: contains the files needed by the playground. <https://playground.decentraland.org/>
31+
## Development
2632

27-
### Versioning notes
33+
### Building
2834

29-
When `@dcl/sdk` is built, as it depends on new versions of `@dcl/ecs`, these are built first and `@dcl/sdk` includes the new versions.
35+
The project uses a Makefile to handle all build tasks:
3036

31-
### ECS 6 dev support
37+
```bash
38+
# Build everything (including protobuf)
39+
make build
3240

33-
The ECS 6 lives in the `6.x.x` branch, there will no longer be new features but it's available for fixes or patches.
34-
With a PR to `6.x.x`, you can test the build with the S3 publish, but it'll be necessary to create a release for propagating under `decentraland-ecs@latest`.
41+
# Clean build artifacts
42+
make clean
3543

36-
### Updating golden files (.crdt)
44+
# Clean everything (including node_modules) and rebuild
45+
make deep-clean && make install && make build
46+
```
3747

38-
We use golden files to create snapshots for a series of test scenes. Most changes to the codebase impose a change in the amount of opcodes executed in the actual scene. We use a QuickJS virtual machine to benchmark how many opcodes are required. Even though this is not representative of the reallity of optimized JIT virual machines, it is a good approximation of the impact that the change would imposes on scene developers.
48+
### Testing
3949

40-
To re-create these golden files, run `make build update-snapshots`. In some cases, this will generate some discrepancies with the clean environment used by the continuous integration we use (CircleCI). If you run into this issue, please run `make deep-clean-and-snapshot` to invalidate all cached calculations. **Be careful**: it will clean all local changes on your git [working tree](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefworkingtreeaworkingtree).
50+
```bash
51+
# Run all tests
52+
make test
4153

42-
### Release a new SDK Version
54+
# Run ECS tests
55+
make test-ecs
4356

44-
After merging a PR to the main branch, we should wait until the [actions](https://github.com/decentraland/js-sdk-toolchain/actions/workflows/ci.yml) finish the process.
57+
# Run Inspector tests
58+
make test-inspector
4559

46-
Once the actions completed successfuly, we have to create a new [Release](https://github.com/decentraland/js-sdk-toolchain/releases/new) from the main branch following this [version guideline](https://docs.decentraland.org/creator/releases/version-agreement/).
60+
# Run tests with coverage
61+
make test-coverage
4762

48-
## Copyright info
63+
# Update test snapshots
64+
make update-snapshots
65+
```
4966

50-
This repository is protected with a standard Apache 2 license. See the terms and conditions in the LICENSE file.
67+
### Protobuf
68+
69+
The project uses Protocol Buffers for type-safe communication. Protobuf files are automatically compiled during the build process.
70+
71+
To manually rebuild protobuf files:
72+
73+
```bash
74+
make proto
75+
```
76+
77+
## Release Process
78+
79+
1. Merge changes to the main branch
80+
2. Wait for CI workflow completion in GitHub Actions
81+
3. Create a new Release following the [version guidelines](https://docs.decentraland.org/creator/releases/version-agreement/)
82+
83+
## Testing Infrastructure
84+
85+
### Snapshot Testing
86+
87+
We use snapshot testing with golden files to track runtime performance impacts:
88+
89+
- Snapshots measure QuickJS opcode execution for test scenes
90+
- Run `make build update-snapshots` to update golden files
91+
- For clean environment matching CI, use `make deep-clean-and-snapshot`
92+
> Note: This cleans all local changes in your git working tree
93+
94+
### Running Tests
95+
96+
```bash
97+
# All tests
98+
make test
99+
100+
# Specific package
101+
make test-ecs
102+
make test-inspector
103+
```
104+
105+
## SDK Version Support
106+
107+
### SDK7
108+
109+
The main branch contains SDK7, the current version. All new features and improvements target SDK7.
110+
111+
### SDK6 Maintenance
112+
113+
SDK6 is maintained in the `6.x.x` branch for critical fixes:
114+
115+
- No new features are added
116+
- Only bug fixes and security patches
117+
- Create PRs against the `6.x.x` branch
118+
- Releases update the `decentraland-ecs` package
119+
120+
## Troubleshooting
121+
122+
If you encounter build issues:
123+
124+
1. Clean the project and reinstall dependencies:
125+
126+
```bash
127+
make clean && make install
128+
```
129+
130+
2. Rebuild everything and run tests:
131+
132+
```bash
133+
make build && make test
134+
```
135+
136+
Common issues:
137+
138+
- **Build failures**: Try `make clean && make install && make build`
139+
- **Test failures**: Run `make test` to see detailed errors
140+
- **Protobuf errors**: Run `make proto` to rebuild protocol buffers
141+
- **Package conflicts**: Delete `node_modules` and run `make install` again
142+
- **TypeScript errors**: Check package versions match in `package.json` files
143+
144+
## Contributing
145+
146+
1. Fork the repository
147+
2. Create your feature branch
148+
3. Commit your changes
149+
4. Push to the branch
150+
5. Create a Pull Request
151+
152+
## Architecture Decisions
153+
154+
For a deeper understanding of the architecture and design decisions:
155+
156+
- [ADR-117: CRDT Protocol for Scenes](https://adr.decentraland.org/adr/ADR-117) - Details the scene state synchronization
157+
- [ADR-123: Schema and Serialization](https://adr.decentraland.org/adr/ADR-123) - Explains component data handling
158+
- [ADR-124: Implementing Flexbox-based UI](https://adr.decentraland.org/adr/ADR-124) - Describes the UI layout system
159+
- [ADR-125: User Interface Components](https://adr.decentraland.org/adr/ADR-125) - Covers the UI system architecture
160+
- [ADR-133: Scene Runtime Definition](https://adr.decentraland.org/adr/ADR-133) - Details how scenes are executed
161+
- [ADR-153: Transform SDK Component](https://adr.decentraland.org/adr/ADR-153) - Explains the core Transform component
162+
- [ADR-165: Component Declaration](https://adr.decentraland.org/adr/ADR-165) - Describes the ECS component system design
163+
- [ADR-237: SDK 7 Custom UI Components](https://adr.decentraland.org/adr/ADR-237) - Details the UI component system
164+
- [ADR-281: Items in Decentraland tooling](https://adr.decentraland.org/adr/ADR-281) - Explains the Items abstraction used across tools
165+
- [ADR-282: Decentraland Inspector](https://adr.decentraland.org/adr/ADR-282) - Details the Inspector's architecture and integration approaches
166+
167+
For more ADRs, visit our [ADR repository](https://adr.decentraland.org/).
168+
169+
## License
170+
171+
Apache 2.0

‎packages/@dcl/ecs/README.md

Lines changed: 114 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,117 @@
1-
# ECS 7
1+
# @dcl/ecs
22

3-
## Installing dependencies
4-
Run `make install`, this will run the `npm install` and other dependencies
3+
Core Entity Component System (ECS) package for Decentraland scenes. Implements a CRDT-based ECS architecture for networked scene state.
54

6-
## Building
7-
Run `make build`
5+
## Installation
86

9-
## Testing
10-
Run `make test`, you can also debug the test in VS code, selecting the launch `Jest current file` or just `Jest` (this will run all test)
7+
```bash
8+
npm install @dcl/ecs
9+
```
10+
11+
## Usage
12+
13+
```typescript
14+
import { engine } from '@dcl/ecs'
15+
16+
// Create entity
17+
const entity = engine.addEntity()
18+
19+
// Define and add component
20+
const Health = engine.defineComponent(1, {
21+
current: Number,
22+
max: Number,
23+
regeneration: Number
24+
})
25+
26+
Health.create(entity, {
27+
current: 100,
28+
max: 100,
29+
regeneration: 1
30+
})
31+
32+
// Create system
33+
engine.addSystem((dt: number) => {
34+
for (const [entity, health] of engine.mutableGroupOf(Health)) {
35+
if (health.current < health.max) {
36+
health.current = Math.min(health.max, health.current + health.regeneration * dt)
37+
}
38+
}
39+
})
40+
```
41+
42+
## Technical Overview
43+
44+
### Component Definition
45+
46+
Components are defined with a unique ID and a schema. The schema is used to:
47+
48+
- Generate TypeScript types
49+
- Create binary serializers/deserializers
50+
- Set up CRDT operations
51+
52+
### CRDT Implementation
53+
54+
The ECS uses CRDTs (Conflict-free Replicated Data Types) to enable deterministic state updates across multiple engine instances:
55+
56+
- Component updates are CRDT operations with logical timestamps
57+
- Multiple engine instances can be synced by exchanging CRDT operations
58+
- Conflict resolution uses timestamps and entity IDs to ensure consistency
59+
- Binary transport format minimizes network overhead
60+
61+
### Network Entities
62+
63+
For multiplayer scenes, the `NetworkEntity` component marks entities that should be synchronized across peers:
64+
65+
```typescript
66+
import { engine, NetworkEntity } from '@dcl/ecs'
67+
68+
// Create a networked entity
69+
const foe = engine.addEntity()
70+
NetworkEntity.create(foe)
71+
72+
// Components on this entity will be synced across peers
73+
Health.create(foe, { current: 100, max: 100, regeneration: 1 })
74+
```
75+
76+
Each peer maintains its own engine instance. When using NetworkEntity:
77+
78+
- The owner peer can modify the entity's components
79+
- Other peers receive read-only replicas
80+
- Updates are propagated through the network transport layer using CRDT operations
81+
82+
Example transport message:
83+
84+
```typescript
85+
{
86+
entityId: number
87+
componentId: number
88+
timestamp: number
89+
data: Uint8Array // Serialized component data
90+
}
91+
```
92+
93+
### Performance Features
94+
95+
- Zero-allocation component iteration
96+
- Dirty state tracking for efficient updates
97+
- Binary serialization for network transport
98+
- Batched component operations
99+
100+
## Development
101+
102+
```bash
103+
# Build
104+
make build
105+
106+
# Test
107+
make test
108+
109+
# Clean and reinstall
110+
make clean && make install
111+
```
112+
113+
## Documentation
114+
115+
- [ECS Guide](https://docs.decentraland.org/creator/development-guide/sdk7/entities-components/)
116+
- [Component Reference](https://docs.decentraland.org/creator/development-guide/sdk7/components/)
117+
- [ADR-117: CRDT Protocol](https://adr.decentraland.org/adr/ADR-117)

‎packages/@dcl/js-runtime/README.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# @dcl/js-runtime
2+
3+
TypeScript definitions for the Decentraland scene runtime environment.
4+
5+
## Overview
6+
7+
This package provides TypeScript type definitions for the Decentraland scene runtime environment. It includes:
8+
9+
- Type definitions for Web APIs (fetch, WebSocket)
10+
- Auto-generated SDK/API type definitions
11+
- Basic runtime types (console, DEBUG flag)
12+
13+
This package does not contain any JavaScript runtime code - it only provides TypeScript types and interfaces used by the SDK and scene developers.
14+
15+
## Installation
16+
17+
```bash
18+
npm install --save-dev @dcl/js-runtime
19+
```
20+
21+
## Development
22+
23+
The types in this package are auto-generated during the monorepo's build process:
24+
25+
```bash
26+
# From the root of the monorepo
27+
make build
28+
```
29+
30+
The generated types will be available in `apis.d.ts`.
31+
32+
## Documentation
33+
34+
- [Scene Development Guide](https://docs.decentraland.org/creator/development-guide/sdk7/scene-content/)
35+
- [Runtime API Reference](https://docs.decentraland.org/creator/development-guide/sdk7/runtime-api/)

‎packages/@dcl/playground-assets/README.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# @dcl/playground-assets
2+
3+
Assets package for the [Decentraland Playground](https://playground.decentraland.org/).
4+
5+
## Overview
6+
7+
This package contains the built assets required by the Decentraland Playground - an experimental web IDE that allows developers to:
8+
9+
- Write and preview Decentraland scenes in real-time
10+
- Share code snippets with other developers
11+
- Test and iterate on scene code directly in the browser
12+
- View changes instantly in the integrated Decentraland web explorer
13+
14+
Similar to [Babylon.js Playground](https://playground.babylonjs.com/), the Decentraland Playground provides an interactive environment for rapid prototyping and experimentation.
15+
16+
## Development
17+
18+
The assets in this package are automatically built during the monorepo's build process:
19+
20+
```bash
21+
# From the root of the monorepo
22+
make build
23+
```
24+
25+
## Related Documentation
26+
27+
- [Playground](https://playground.decentraland.org)

0 commit comments

Comments
 (0)