Início rápido para Unity - .NET SDK
Nesta página
Esta página contém informações sobre como instalar e integrar o Realm ao seu projeto Unity.
Pré-requisitos
Unity 2020.3.12f1 (LTS)
Observação
O Realm .NET SDK pode ser compatível com outras versões do Unity, mas 2020.3.12f1 (LTS)
é a versão que a equipe do Realm usa para fazer testes e desenvolvimento. Recomendamos usar esta versão para garantir que seu projeto funcione com o Realm e que as etapas de instalação correspondam às etapas abaixo, já que a UI do Unity normalmente muda entre as versões.
Instalar
O Realm oferece várias maneiras de instalar o Realm .NET SDK para uso com o Unity. Desenvolvedores experientes do Unity podem achar que instalar o Realm manualmente com um tarball é intuitivo. No entanto, recomendamos a instalação do Realm .NET SDK via npm, pois ele fornece notificações de atualizações de versão por meio do gerenciador de pacote do Unity.
Adicionar NPM como um registro com escopo
Antes de baixar e usar Realm o em seu Unity projeto , você deve adicionar npm como um registro com escopo. Adicionar o npm como um registro com escopo configura o Unity para se comunicar com npm, permitindo a instalação de pacotes, como o Realm.
Abra o Unity Gerenciador de pacote clicando na Window guia na parte superior do Unity menu . Clique Package Manager no Window dropdown. Em seguida, clique no ícone de engrenagem no canto direito. Selecione a opção Advanced Project Settings no menu suspenso.
Preencha o formulário de registro com os detalhes abaixo e clique no botão Salvar.
name = NPM URL = https://registry.npmjs.org Scope(s) = io.realm.unity
Adicionar Realm ao manifesto do projeto
Agora que o Unity pode instalar o Realm .NET SDK a partir do npm, você precisa adicionar Realm como uma dependência no arquivode manifesto do seu projeto . Abra o arquivo "Pacotes/manifest.json" no Visual Studio ou outro editor de texto. Na parte inferior do objeto da dependência, adicione o campo "io.realm.unity" e seu valor, o número da versão do Realm .NET que você deseja usar entre aspas.
"io.realm.unity": "<version-number>"
Lembre-se de substituir o <version-number>
acima pelo número da versão real. Você pode encontrar a versão de lançamento mais recente no repositório realm-dotnet do GitHub. Seu arquivo de manifesto completo deve ter a seguinte aparência:
{ "dependencies": { ... "io.realm.unity": "10.21.0" }, "scopedRegistries": [ { "name": "NPM", "url": "https://registry.npmjs.org/", "scopes": [ "io.realm.unity" ] } ] }
Ao salvar este arquivo, o Unity baixa a versão especificada do pacote Realm .NET SDK do registro NPM.
Verifique a dependência do domínio e verifique se há atualizações
Para verificar se o pacote Realm foi baixado do NPM, abra seu gerenciador de pacotes Unity clicando na guia Window na parte superior do menu Unity. Clique em Package Manager no menu suspenso Window. Você deve ver Realm na guia "Packages: In Project".
Se você ver um ícone de verificação verde ao lado do número da versão do pacote Realm, isso significa que seu pacote está atualizado. No entanto, se o ícone de seta para cima for mostrado, uma nova versão do pacote estará disponível. Clicar nele oferece a opção de atualizar para a versão mais recente.
Baixe a versão mais recente do Realm .NET SDK
Antes de começar a usar o Realm em seu projeto Unity, você deve baixar o Realm .NET SDK.
Navegue até as versões do repositório realm-dotnet página e role para baixo até a versão que você deseja usar em seu projeto. Se não tiver certeza de qual versão usar, use a versão rotulada "última versão" na linha esquerda.
Role para baixo até o menu suspenso "Ativos" da versão e clique no link rotulado "io.realm.unity-<version-number>.tgz" para baixar o SDK.
Adicione o Tarball ao seu gerenciador de pacotes de projetos
Mova o tarball do .NET SDK do Realm baixado para dentro do seu projeto. Você pode fazer isso arrastando e soltando o arquivo na pasta do seu projeto. Copiar o tarball para a pasta do projeto e confirmá-lo no controle de versão garante que outros desenvolvedores trabalhando no projeto possam simplesmente clonar o repositório e construir sem baixar manualmente a dependência do Realm .
Em seguida, você deve carregar o tarball em seu projeto usando o gerenciador de pacote Unity.
Para abrir o gerenciador de pacote , clique na aba Window na parte superior do menu Unity. Clique em Package Manager no Window dropdown. Quando o modelo do gerenciador de pacote abrir, clique no ícone + no canto superior esquerdo do modelo. Selecione a opção Add package from tarball... .
Selecione seu "io. Realm.unity-bundled-<version-number>.tgz" para começar a importar seu projeto.
Importar Realm
Crie um roteiro C# ou use um roteiro C# que você já criou. Abra o roteiro no Visual Studio ou em outro editor de texto e inclua a seguinte linha para importar seu pacote do Realm:
using Realms;
Usando o Realm em seu projeto Unity
Ao desenvolver com o Realm .NET SDK, os métodos da API são os mesmos, independentemente de você usar o Unity ou outra plataforma. No entanto, como o Unity tem algumas restrições de script, tenha em mente as seguintes considerações adicionais ao desenvolver seu projeto:
Remoção gerenciada de código
Unity executa remoção de código gerenciado, descartando qualquer código não utilizado de uma compilação para reduzir o tamanho do binário. Isso pode levar a problemas ao desserializar BSON nas classes C#. Para plataformas que usam IL2C++, como o iOS, a remoção gerenciada de código está ativada por padrão. Ao trabalhar com BSON, use o atributo [Preserve] para evitar a remoção gerenciada de código em propriedades de tipos que são apenas populadas pelo serializador. Como essas propriedades usam reflexão, o Unity não pode inferir estaticamente que o definidor de propriedade é usado. Isso significa que, a menos que você aplique o [Preserve] attribute
, o Unity removerá essas propriedades. Para obter exemplos de quando você pode executar a desserialização BSON, consulte a documentação Consultar MongoDB e Chamar uma função .
Usando o Realm enquanto o aplicativo está encerrando
O .NET SDK do Realm não pode ser acessado dentro do evento AppDomain.DomainUnload ou o Application.quitting evento. Isso significa que você não pode gravar dados em um Realm enquanto o aplicativo do player estiver encerrando. Se você precisar armazenar alguns dados pouco antes do encerramento do aplicativo, considere usar o arquivo Application.wansToquit evento.
Observação
Problema conhecido ao desenvolver com Unity no Windows
No Windows, se você estiver usando o Device Sync, seu projeto poderá travar ao executar várias instâncias do projeto, pois vários processos estão tentando acessar o mesmo domínio sincronizado. Se você estiver utilizando um domínio local, poderá executar múltiplas instâncias do seu projeto sem falhas.
Exemplos adicionais
A comunidade Realm criou diversos projetos que demonstram o uso do Realm .NET SDK. Veja os exemplos abaixo que demonstram o uso do Realm .NET SDK com o Unity!
Observação
A equipe de documentação do MongoDB não mantém estes exemplos diretamente.