Solução de problemas

Comece pelo sintoma abaixo. Preserve os arquivos do projeto antes de fazer qualquer alteração manual de armazenamento.

O Locus está ausente ou não carrega

1. Confirme que o plugin está em <Project>/Plugins/Locus/ e habilitado em Edit > Plugins.
2. Confirme que o pacote corresponde à versão minor exata do Unreal Engine do projeto.
3. Reinicie o Unreal Editor depois de habilitar ou substituir o plugin.
4. Tente Window > Locus ou Ctrl+Shift+L.
5. Revise o Unreal Output Log em busca da categoria LogLocus e do erro de carregamento do plugin.

Se um pacote binário for destinado a outra versão minor da Engine, substitua-o pelo pacote correto; não copie binários individuais entre pacotes.

O conteúdo é somente leitura

Abra Controle de Código-Fonte e verifique se o arquivo é controlado, está em checkout por outro usuário ou cliente, está desatualizado ou indisponível porque o provedor está desconectado. Um arquivo controlado limpo também permanece somente leitura até que você faça checkout explicitamente.

Check Out pode estar indisponível quando outro cliente possui o arquivo, seu espaço de trabalho está atrás do depot ou o provedor não consegue informar um estado seguro. Resolva a propriedade ou o estado da revisão usando o fluxo normal de controle do projeto. Depois de reconectar um provedor, atualize o Controle de Código-Fonte do Unreal ou o Locus; conteúdo controlado continua somente leitura até o checkout ter sucesso. Não contorne a proteção alterando permissões do sistema de arquivos.

Notas e Pins Privados não devem depender de um provedor. Se estiverem indisponíveis, verifique se o armazenamento Saved/Locus do projeto existe e pode ser gravado.

Sem nenhum provedor configurado, a ausência de status de controle de origem, dica de ferramenta, orientação, interface de usuário Check Out ou Marcar para Adição é o modo local normal. Um provedor configurado, mas indisponível, é diferente e mantém protegido o conteúdo controlado conhecido.

Check Out ou Marcar para Adição falhou

Confirme se o provedor do Unreal está configurado, conectado e pode relatar o arquivo. Uma solicitação Marcar para Adição pós-criação com falha deixa um novo Nota compartilhado no disco. Novos Pins e Documentos compartilhados permanecem Untracked até serem adicionados explicitamente; Os instantâneos Pin compartilhados têm um estado de controle de origem separado.

Um Documento não pode ser renomeado ou movido

Use o espaço de trabalho Documentos do Locus para renomear e mover; o item do Content Browser é uma projeção, não a superfície autoritativa. Um Documento Não rastreado elegível pode ser renomeado com Renomear ou F2 e movido com Mover ou arrastado para uma pasta existente válida. O Locus bloqueia intencionalmente Renomear e Mover para Documentos Marcados para Adição e controlados porque não consegue executar com segurança uma movimentação de controle de código-fonte neutra em relação ao provedor. Não contorne isso desabilitando o controle de código-fonte ou alterando permissões; organize o Documento antes de Marcar para Adição.

Notas, Pins ou Documentos não são atualizados

Use a ação de reconstrução ou atualização do espaço de trabalho ativo. Para Documentos alterados em um editor externo, salve um arquivo .md UTF-8 válido em ProjectDocuments. Para Pins, confirme que o mundo atual está salvo e que o Pin está associado ao mapa resolvido.

Há uma recuperação disponível

Revise o item principal no disco e a cópia de recuperação antes de agir. Restaurar substitui o item principal pelo trabalho recuperado, Restaurar como Novo preserva ambos e Descartar remove a cópia. Quando estiver em dúvida, prefira restaurar como novo.

Não limpe Saved como atalho de solução

A árvore Saved do projeto pode conter Notas Privadas, Pins Privados e snapshots de recuperação. Excluí-la pode destruir permanentemente conteúdo do usuário.

Conflito externo

Um conflito externo significa que o arquivo no disco mudou enquanto o Locus mantinha edições não salvas. Não force uma substituição. Use as ações oferecidas para recarregar do disco, salvar o trabalho local como um novo item, copiar o texto local ou comparar versões quando disponível.

Dados malformados ou incompatíveis

Mantenha o arquivo original e examine a mensagem LogLocus. Não edite manualmente identificadores ou campos de propriedade sem um backup verificado e compreensão do formato. Um arquivo Markdown UTF-8 inválido é rejeitado na importação. Markdown incompatível deve permanecer intacto como origem, mesmo que o Modo de Leitura não consiga apresentá-lo por completo.

Uma referência está faltando ou obsoleta

Atualize o espaço de trabalho relevante e verifique se o Ativo, Pin, Nota, Documento ou Actor ainda existe. Um alvo movido ou excluído pode permanecer legível, mas não resolvido, para que você possa repará-lo deliberadamente.

Crie uma referência Actor apenas arrastando exatamente um Actor elegível carregado do World Outliner para um Nota ou Documento editável. Está ausente em Inserir Referência e @; Instâncias de nível e mundos transitórios ou de visualização não suportados não são suportados.

Pins estão indisponíveis

Pins persistentes exigem um mundo do Editor de nível superior salvo. Salve o mapa, retorne a Mapa Atual e tente colocar novamente. Os arquivos de Pin não carregam nem alteram mapas apenas para a navegação em Todos os Mapas.

A captura e atualização de instantâneo também exigem uma janela de visualização Level Editor de perspectiva disponível e não estão disponíveis durante PIE.

Documentos estão ausentes

Confirme que o arquivo .md está sob <Project>/ProjectDocuments/ e usa UTF-8 válido. Um caminho fora da subárvore reservada Content/ aparece em Documentos do Locus e não é projetado no Content Browser do Unreal. Um caminho sob ProjectDocuments/Content/ aparece na raiz esparsa Navegador de Conteúdo e é projetado no contexto /Game correspondente. Atualize Documentos após alterações externas. Pastas /Game não relacionadas ficam ausentes intencionalmente porque a árvore é derivada dos Documentos indexados, não das pastas do Asset Registry. Lembre-se de que Documentos são itens externos projetados, não UAssets.

Markdown não é renderizado como esperado

Consulte Documentos para construções compatíveis. HTML bruto e URLs inseguras permanecem inertes, conteúdo remoto não é buscado e não há promessa de renderização Markdown equivalente à do navegador. Mude para o Modo de Edição para confirmar que a origem autoritativa está intacta.

O cliente MCP não conecta ou é negado

Mantenha o Unreal Editor aberto e use Editor Preferences > Plugins > Locus > MCP Integration para confirmar que Ativar MCP está ativado e o status está em execução. Se o endpoint local ou a configuração do cliente não estiver disponível, copie uma configuração nova depois de alterar a porta local ou regenerar a credencial.

Escolha o Formato do Cliente correto antes de copiar. Execute comandos de registro do Claude Code e Gemini CLI em um terminal normal, não dentro dos prompts interativos. O Gemini usa escopo de usuário, então uma entrada global antiga locus pode ainda apontar para o endpoint de outro projeto; substitua-a por uma configuração nova do projeto aberto. Nunca cole o comando ou a credencial copiados em uma solicitação de suporte.

Apenas um cliente pode possuir a sessão ativa do Locus. Feche ou desconecte o cliente anterior, aguarde brevemente e tente novamente; use Redefinir Cliente Ativo somente quando o cliente não estiver mais em uso. Uma mutação exige Permitir Alterações, e Notas ou Pins Privados exigem Permitir Notas e Pins Privados separadamente. O trabalho de Pins via MCP é limitado à base compatível de um mundo /Game/... salvo e de propriedade do projeto.

Consulte Integração MCP para obter orientações completas de conexão, permissões, ferramentas compatíveis e contexto de Pins.

A documentação ou o feedback não abre

Links externos usam o navegador padrão do sistema operacional. Verifique se há um navegador HTTP/HTTPS padrão configurado e se o sistema operacional permite iniciar URLs. A falha não altera dados do projeto. A Integração MCP inclui um botão Documentação, e o Locus também oferece Enviar Feedback.