|
1 | | -# Decentraland SDK 7 |
| 1 | +# Decentraland SDK Toolchain |
2 | 2 |
|
3 | | -[](https://codecov.io/gh/decentraland/js-sdk-toolchain) |
| 3 | +This monorepo contains the core packages for Decentraland's SDK and development tools. |
4 | 4 |
|
5 | | -Use the Decentraland Software Development Kit v7 to create experiences for the Decentraland ecosystem. |
| 5 | +## Packages |
6 | 6 |
|
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 |
| 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 |
8 | 14 |
|
9 | | -1. Run `npx @dcl/sdk-commands init` on an empty folder. |
10 | | -2. Preview it with `npm run start`! |
| 15 | +## Quick Start |
11 | 16 |
|
12 | | -## Repository guide |
| 17 | +1. Clone the repository: |
13 | 18 |
|
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 | +``` |
15 | 23 |
|
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: |
21 | 25 |
|
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 | +``` |
23 | 30 |
|
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 |
26 | 32 |
|
27 | | -### Versioning notes |
| 33 | +### Building |
28 | 34 |
|
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: |
30 | 36 |
|
31 | | -### ECS 6 dev support |
| 37 | +```bash |
| 38 | +# Build everything (including protobuf) |
| 39 | +make build |
32 | 40 |
|
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 |
35 | 43 |
|
36 | | -### Updating golden files (.crdt) |
| 44 | +# Clean everything (including node_modules) and rebuild |
| 45 | +make deep-clean && make install && make build |
| 46 | +``` |
37 | 47 |
|
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 |
39 | 49 |
|
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 |
41 | 53 |
|
42 | | -### Release a new SDK Version |
| 54 | +# Run ECS tests |
| 55 | +make test-ecs |
43 | 56 |
|
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 |
45 | 59 |
|
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 |
47 | 62 |
|
48 | | -## Copyright info |
| 63 | +# Update test snapshots |
| 64 | +make update-snapshots |
| 65 | +``` |
49 | 66 |
|
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 |
0 commit comments