Documentos

Documentos são arquivos Markdown de propriedade do projeto para informações mais extensas sobre o projeto. O arquivo .md é sempre a fonte principal e continua compatível com editores de texto externos.

Propriedade e armazenamento

Todos os Documentos ficam em <Project>/ProjectDocuments/. Não há escopos Compartilhado ou Privado para Documentos. Pastas do Content Browser em /Game/... correspondem a caminhos sob ProjectDocuments/Content/...; uma pasta Developers continua sendo contexto do projeto, não propriedade privada.

Um Documento não é um UAsset, pacote, redirector, objeto de runtime ou proprietário de dados cozidos. O Locus nunca envolve o Markdown em outro formato autoritativo.

Raízes Documentos do Locus e Content Browser

A árvore de Documentos tem duas raízes de apresentação sobre o mesmo repositório físico:

• Documentos do Locus contém Documentos comuns de propriedade do projeto armazenados fora da subárvore reservada Content/. Esses Documentos existem apenas no Locus e não são projetados no Content Browser do Unreal.
• Navegador de Conteúdo contém apenas Documentos cujo caminho relativo autoritativo começa com Content/. O Locus oculta esse prefixo interno na árvore, então ProjectDocuments/Content/Blueprints/AI/Behavior.md aparece como Content Browser > Blueprints > AI > Behavior e é projetado no contexto /Game/Blueprints/AI correspondente.

A raiz Content Browser é esparsa e orientada por Documentos. Ela mostra apenas pastas que contêm diretamente um Documento Locus projetado, além dos ancestrais necessários para chegar a essas pastas. Não espelha pastas /Game não relacionadas, e remover uma pasta de apresentação derivada não exclui nem altera a pasta Unreal correspondente.

A projeção segue o caminho relativo autoritativo, não a UI usada para criar o arquivo. Um Documento descoberto na inicialização, criado no Locus, criado por Add > Locus > Locus Documento, importado ou criado pelo MCP tem a mesma identidade indexada e o mesmo comportamento de projeção.

Criar e encontrar Documentos

Crie sob Documentos do Locus para um Documento somente do Locus. Crie sob Navegador de Conteúdo para um Documento mapeado que seja projetado no contexto /Game correspondente. Add > Locus > Locus Documento em uma pasta compatível do Content Browser cria a mesma identidade mapeada. O Locus cria um arquivo .md externo real, oculta a extensão na UI normal e abre uma aba de editor dedicada. Importações Markdown e Documentos criados pelo MCP seguem a mesma política de criação local Não rastreado.

Organize um novo Documento antes de adicioná-lo ao controle de código-fonte:

Criar → renomear, mover e editar → Marcar para Adição quando o caminho estiver final.

O espaço de trabalho navega por pastas físicas e oferece pesquisa por título/caminho, filtros de status, atualização, abertura, renomeação, movimentação, exclusão, checkout, marcação para adição, importação e exportação. Várias abas de Documento podem permanecer abertas; abrir um caminho já aberto foca a aba existente.

Para importar, use a ação Locus do Content Browser e escolha um arquivo .md UTF-8 válido. O Locus preserva seus bytes de origem e finais de linha e usa um nome numerado seguro quando o destino já existe.

A barra de ferramentas Documento permanece em uma linha. As ações de menor prioridade passam progressivamente para Mais ações; Exportar e Atualizar permanecem lá. As ações de controle de origem estão ausentes quando nenhum provedor está configurado.

Editar e salvar

Documentos novos ou vazios abrem no Modo de Edição; Documentos preenchidos abrem no Modo de Leitura. Pressione Ctrl+E para Modo de Edição, Ctrl+R para Modo de Leitura e Ctrl+S para salvar. Documentos usam salvamento explícito, em vez do salvamento automático das Notas.

O editor de origem oferece comandos para cabeçalhos, ênfase, código inline e cercado, listas ordenadas e não ordenadas, listas de tarefas, citações, links, tabelas, linhas horizontais, referências de assets e referências de Pins. A Visualização dividida apresenta o buffer não salvo atual ao lado da origem após um breve atraso; abrir ou atualizar a Visualização não salva o arquivo.

Em Editar, a barra de ferramentas compacta fornece Título, Negrito, Itálico, Código em linha, Lista não ordenada, Lista ordenada, Link externo, Referência de Asset e Referência de Pin; outros comandos permanecem em Formatar. Dividir Visualização renderiza o buffer atual ao lado da fonte após um breve debounce sem salvar; seu divisor, estado aberto e proporção são preferências pessoais.

Modo de Leitura e suporte a Markdown

O Modo de Leitura usa UI nativa do Unreal. Ele oferece suporte às construções Markdown necessárias para a barra de ferramentas do editor, incluindo cabeçalhos, parágrafos, ênfase, texto em negrito, listas, itens de tarefa somente para exibição, citações, código, links, tabelas com alinhamento, linhas horizontais e texto tachado.

Preservação da origem

A apresentação legível e a Visualização nunca regeneram o Markdown. Alternar entre modos preserva exatamente a origem escrita.

O Locus não promete renderização equivalente à de um navegador ou Markdown completo. HTML bruto permanece como texto de origem inerte, JavaScript nunca é executado, esquemas de URL inseguros não são ativados e conteúdo remoto não é buscado automaticamente. Links HTTP e HTTPS só abrem após uma ação explícita do usuário no navegador do sistema operacional.

Documentos mantêm Markdown como origem enquanto o Modo de Leitura apresenta a estrutura compatível na UI nativa do Editor.

Referências de assets e Pins usam rótulos legíveis na apresentação. Um Pin do mapa atual pode ser focado; um Pin de outro mapa pode localizar seu nível proprietário sem carregá-lo automaticamente. Referências ausentes continuam inertes e diagnosticáveis.

As referências de Ativo Resolvido, Pin, Nota, Documento e Actor usam rótulos legíveis. As referências Actor são criadas apenas colocando um World Outliner Actor carregado elegível em um Documento no modo de edição; eles não são oferecidos por Inserir Referência ou @. HTML bruto e JavaScript nunca são executados e o conteúdo remoto não é obtido.

Renomear, mover e excluir

Renomear e mover permanecem dentro da raiz Documentos. Para um Documento Não rastreado elegível, use Renomear na barra de ferramentas ou no menu de contexto, pressione F2, use Mover na barra ou arraste-o para uma pasta existente válida. O espaço de trabalho Documentos do Locus é o local autoritativo para renomear ou mover; o item do Content Browser é uma projeção, e a renomeação direta no Content Browser não é compatível.

Depois de Marcar para Adição, Renomear e Mover ficam intencionalmente indisponíveis. Eles também ficam indisponíveis para Documentos controlados, pois o Locus não pode garantir uma movimentação transacional de controle de código-fonte neutra em relação ao provedor. Esse limite de segurança evita que uma alteração no sistema de arquivos dessincronize o Documento e o controle de código-fonte. Documentos abertos com alterações pendentes ou conflitos também bloqueiam renomear, mover e excluir no espaço de trabalho.

A exclusão é permanente, exige confirmação e não pode ser desfeita pelo Unreal. Para arquivos rastreados, o Locus valida o estado e encaminha a exclusão pelo provedor ativo antes da limpeza local.

As alterações de caminho estão disponíveis apenas para Untracked Documentos locais ou. Renomear e mover são desabilitados após Marcar para Adição ou controle do provedor porque Locus não executa movimentações de depósito neutras em relação ao provedor ou transfere estado aberto entre caminhos.

Exportar

Exporte um Documento selecionado, uma pasta, todos os Documentos ou uma cópia do editor. A exportação preserva a origem atual — incluindo um buffer não salvo ao exportar uma cópia — e pode preservar a estrutura de pastas. O destino não pode ficar dentro de ProjectDocuments; em caso de colisão, as opções são substituir, ignorar ou criar uma cópia numerada. Exportar não altera o Documento de origem, sua aba ou seu estado de controle de código-fonte.

Recuperação e edição externa

O Locus armazena a recuperação de Documentos em <Project>/Saved/Locus/Recovery/Documentos/. Um salvamento bem-sucedido remove o snapshot correspondente. Alterações externas limpas são recarregadas; uma alteração externa em conflito com texto local pendente bloqueia o salvamento até que você escolha uma resolução segura.

Como .md é autoritativo, editores externos são compatíveis. Atualize a descoberta após operações externas de arquivo se o espaço de trabalho não for atualizado rapidamente. As abas do Editor não são restauradas automaticamente após reiniciar o Unreal Editor.

Um novo Locus Documento prefere a pilha de guias Locus Documento ativa ou ativa mais recentemente; o mesmo caminho normalizado concentra sua guia existente. As guias permanecem livremente encaixáveis, mas não são restauradas após a reinicialização do Editor.

Visualização do Documento selecionado

Selecionar um Documento mostra uma visualização Markdown somente leitura no painel de detalhes do espaço de trabalho. Ela apresenta o arquivo salvo e autoritativo; use o editor de Documentos dedicado para ler ou editar o conteúdo. Durante uma transição curta e normal de seleção, a visualização permanece neutra até o conteúdo selecionado ficar pronto. Somente uma espera superior a aproximadamente um segundo mostra uma explicação nativa compacta de carregamento em vez de conteúdo antigo.

O nome do arquivo e o caminho do Documento fornecem sua identidade no espaço de trabalho. Um cabeçalho Markdown é conteúdo, portanto renomear o arquivo atualiza o nome exibido sem reescrever um cabeçalho como # My Title.

No menu Documento Editor Exibir, Tamanho da Fonte do Modo de Edição afeta o editor de origem e Tamanho da Fonte de Leitura afeta a visualização completa de leitura e divisão. Ctrl+mouse wheel ajusta a visualização aplicável.

Controle de código-fonte

Documentos são de propriedade do projeto. Um Documento recém-criado permanece Não rastreado até que você escolha explicitamente Marcar para Adição, para que ele possa ser organizado enquanto o caminho ainda muda. Um Documento local ou não rastreado continua legitimamente editável no Modo Local. Se Marcar para Adição falhar, o Markdown válido permanece no lugar e pode ser tentado novamente.

Um Documento controlado pelo depot continua legível, mas não pode entrar no Modo de Edição autoritativo ou ser Salvo até que o checkout explícito seja bem-sucedido. O Locus mantém essas ações indisponíveis quando o Documento está limpo e sem checkout, em checkout por outro usuário ou cliente, desatualizado ou desconectado do provedor. Não oferece um fallback para torná-lo gravável; Modo de Leitura e Exportar Cópia permanecem disponíveis quando aplicável.

Após reconectar o controle de código-fonte, atualizar restaura o estado controlado. O Documento continua somente leitura até o checkout ser bem-sucedido. O Locus não envia, sincroniza, gerencia changelists nem altera typemaps. Consulte Controle de Código-Fonte, Impacto no projeto e dependências e Solução de problemas.

Sem nenhum provedor configurado, Documentos não mostra nenhum status, orientação, dica de ferramenta ou ação específica do controle de origem. Um provedor configurado, mas indisponível, mantém protegidos os arquivos controlados conhecidos.