Criação de Componentes

Para criar novos componentes, precisamos fazer algumas coisas antes de começar a codificá-los no renderer. Há um guia passo a passo que você precisa seguir. Vou listar todos os passos e, em seguida, você pode seguir cada passo com uma explicação mais longa.

1. Crie a definição proto em @dcl/protocol

2. Gere o novo código proto TypeScript no js-sdk-toolchain

3. Crie um teste para js-sdk-toolchain

4. Gere o novo código proto C# no projeto

5. Codifique o novo componente

6. Garanta que o componente siga a convenção

Crie a definição proto em @dcl/protocol

Para criar uma definição, você deve ir para este repositório: https://github.com/decentraland/protocol

1. Crie a definição proto nesta pasta: https://github.com/decentraland/protocol/tree/main/ecs/components

2. Crie um PR com as novas alterações

NOTA: Após criar o PR, um Bot do GitHub comentará com o link do pacote para testar o PR. Você pode usar esse link para testar nas etapas seguintes

Coisas a ter em conta

• Estamos usando proto 3, então toda a definição do proto deve compilar com sua syntax

• Temos alguns tipos comuns que não podem ser recriados

• O proto deve ter a definição básica

• Você deve adicionar o seguinte código para enumerar o componente

import "common/id.proto";
option (ecs_component_id) = 1100;

Exemplo de .proto

syntax = "proto3";

import "common/id.proto";
option (ecs_component_id) = 1020;

message PBAudioSource {
  optional bool playing = 1;
  optional float volume = 2; // default=1.0f
  optional bool loop = 3;
  optional float pitch = 4; // default=1.0f
  string audio_clip_url = 5;
}

Gere o novo código proto TypeScript no js-sdk-toolchain

Baixe o seguinte repositório: https://github.com/decentraland/js-sdk-toolchain

Dentro dele, navegue para packages/dcl/ecs (https://github.com/decentraland/js-sdk-toolchain/tree/main/packages/%40dcl/ecs)

E lá, você pode executar

npm install @dcl/protocol@next

Ou o comando gerado pelo Bot do GitHub no seu PR do @dcl/protocol (isso deve ser temporário para testar os PRs).

Então execute os seguintes comandos na raiz do js-sdk-toolchain project:

make install
make build

E envie (push) o código gerado.

Gere o novo código proto C# no projeto

Para gerar o código C#, precisamos ir para o protocol-gen caminho na raiz do @decentraland/unity-renderer repositório. E executar os seguintes comandos:

npm install
npm run build-components

Para atualizar para a versão mais recente do @dcl/protocol (main branch), devemos atualizar usando

npm install @dcl/protocol@next
npm run build-components

Para testar um PR, podemos usar uma URL gerada pelo Bot do GitHub no @dcl/protocol PR: Exemplo:

npm install "https://sdk-team-cdn.decentraland.org/@dcl/protocol/branch//dcl-protocol-1.0.0-3143233696.commit-45f1290.tgz"
npm run build-components

Após mesclar o PR do @dcl/protocol, devemos usar o @dcl/protocol@next e gerar o código.

Codifique o novo componente

Agora é hora de implementar a funcionalidade do novo componente.

Os componentes têm cinco partes essenciais.

• ComponentID O ID que o componente usará. Deve ser único e gerado a partir da definição proto

• Model Este é o modelo do componente. Esses são os dados que usaremos para manipular o componente. Ele foi gerado automaticamente com a geração do proto e tem o mesmo nome do arquivo proto com um PB na frente. Por exemplo, se você tiver um BoxShape.proto definition a classe gerada do modelo será PBBoxShape

• Component Handler O component handler gerenciará toda a funcionalidade do componente. Nesta classe você deve implementar o IECSComponentHandler<ModelClass> (ModelClass é o modelo. É uma classe gerada a partir do proto, o nome será PB + nome do arquivo .proto). Esta interface tem 3 métodos que são importantes implementar para criar um componente

        void OnComponentCreated(IParcelScene scene, IDCLEntity entity);
        void OnComponentRemoved(IParcelScene scene, IDCLEntity entity);
        void OnComponentModelUpdated(IParcelScene scene, IDCLEntity entity, ModelType model);

• Serializer Cada componente é responsável por implementar sua serialização e desserialização do componente. Este serializer deve ser capaz de serializar/desserializar para um array de bytes

• Register Isto registrará o componente no sistema, conectando-o ao sistema. Este registro irá registrar o componente na factory e no component writer

O design dos componentes evita herança, então incentivamos o uso de funções puras tanto quanto possível

Para criá-los, devemos seguir os próximos passos

1. Crie a pasta do componente e a assembly. Temos todos os componentes sob a seguinte pasta DCLPlugins/ECS7/ECSComponents. Você precisa criar uma pasta e uma nova assembly que conterá o componente

2. Na nova assembly, você deve referenciar a seguinte DCL.ECSComponents.Data. Isso referenciará o novo modelo do componente que você acabou de atualizar

3. Você deve criar o component handler com toda a lógica (Dê uma olhada em ECSBoxShapeComponentHandler.cs como exemplo)

4. Você deve criar a classe serializer (provavelmente você pode copiá-la de outra classe e adaptar ao seu)

5. Você deve criar a classe register

   public static class AudioSourceSerializer
    {
        public static byte[] Serialize(PBAudioSource model)
        {
            int size = model.CalculateSize();
            byte[] buffer = new byte[size];
            CodedOutputStream output = new CodedOutputStream(buffer);
            model.WriteTo(output);
            return buffer;
        }

        public static PBAudioSource Deserialize(object data)
        {
            return PBAudioSource.Parser.ParseFrom((byte[])data);
        }
    }

1. Adicione o novo register ao ECS7ComponentsComposer class com seu ID correspondente

   public class ECS7ComponentsComposer : IDisposable
    {
        private readonly TransformRegister transformRegister;
        private readonly SphereShapeRegister sphereShapeRegister;
        private readonly BoxShapeRegister boxShapeRegister;
        private readonly PlaneShapeRegister planeShapeRegister;
        private readonly CylinderShapeRegister cylinderShapeRegister;
        private readonly AudioStreamRegister audioStreamRegister;
        private readonly AudioSourceRegister audioSourceRegister;

        public ECS7ComponentsComposer(ECSComponentsFactory componentsFactory, IECSComponentWriter componentsWriter)
        {
            transformRegister = new TransformRegister(ComponentID.TRANSFORM, componentsFactory, componentsWriter);
            sphereShapeRegister = new SphereShapeRegister(ComponentID.SPHERE_SHAPE, componentsFactory, componentsWriter);
            boxShapeRegister = new BoxShapeRegister(ComponentID.BOX_SHAPE, componentsFactory, componentsWriter);
            planeShapeRegister = new PlaneShapeRegister(ComponentID.PLANE_SHAPE, componentsFactory, componentsWriter);
            cylinderShapeRegister = new CylinderShapeRegister(ComponentID.CYLINDER_SHAPE, componentsFactory, componentsWriter);
            audioStreamRegister = new AudioStreamRegister(ComponentID.AUDIO_STREAM, componentsFactory, componentsWriter);
            audioSourceRegister = new AudioSourceRegister(ComponentID.AUDIO_SOURCE, componentsFactory, componentsWriter);
        }

        public void Dispose()
        {
            transformRegister.Dispose();
            sphereShapeRegister.Dispose();
            boxShapeRegister.Dispose();
            planeShapeRegister.Dispose();
            cylinderShapeRegister.Dispose();
            audioStreamRegister.Dispose();
            audioSourceRegister.Dispose();
        }
    }

E agora você tem seu componente adicionado e funcionando!

Garanta que o componente siga a convenção

Há uma lista de verificação que precisamos ter em conta ao desenvolver novos componentes; esta parte tenta resumi-las.

• Unit test Todos os componentes devem incluir unit tests que cubram sua funcionalidade, dispose e a serialização/desserialização pelo menos para garantir que o componente funcionará

• Leve em conta o que acontece quando o componente não está dentro da cena (Verifique SceneBoundariesChecker classe para mais informações)

• Se o componente renderiza algo no world, ele deve adicionar a informação renderizável ao data store, dessa forma adicionamos a informação do renderer à cena para que conte para o limite

• Se o componente renderiza algo no world, ele deve adicionar o MeshesInfo à entidade

• Deve ser o mais performático possível. Este código será executado muitas vezes, então precisamos garantir que tudo funcione o mais suavemente possível

• Deve funcionar com Hot reload no modo preview. Se você codificou o OnComponentRemoved corretamente, isso funcionará automaticamente, mas o hot reload é uma forma de testar que tudo funciona bem com o dispose do componente

• Se o componente usa um recurso, você deve implementar o gerenciamento de recursos com um AssetPromiseKeeper. O componente deve notificar o AssetPromiseKeeper quando o recurso é usado e quando não é mais usado