Documenti

I Documenti sono file Markdown di proprietà del progetto destinati alle informazioni progettuali più estese. Il file .md è sempre la fonte primaria e resta compatibile con editor di testo esterni.

Proprietà e archiviazione

Tutti i Documenti risiedono sotto <Project>/ProjectDocuments/. Non esistono ambiti Documento Condiviso o Privato. Le cartelle Content Browser sotto /Game/... corrispondono ai percorsi sotto ProjectDocuments/Content/...; una cartella Developers resta contesto del progetto, non proprietà privata.

Un Documento non è un UAsset, un pacchetto, un redirector, un oggetto runtime né un contenitore di dati cooked. Locus non racchiude mai Markdown in un altro formato primario.

Radici Documenti Locus e Content Browser

L’albero Documenti ha due radici di presentazione sopra lo stesso repository fisico:

• Documenti Locus contiene Documenti ordinari di proprietà del progetto archiviati fuori dal sottoalbero riservato Content/. Questi Documenti esistono solo in Locus e non vengono proiettati nel Content Browser di Unreal.
• Content Browser contiene solo Documenti il cui percorso relativo canonico inizia con Content/. Locus nasconde questo prefisso interno nell’albero, quindi ProjectDocuments/Content/Blueprints/AI/Behavior.md appare come Content Browser > Blueprints > AI > Behavior e viene proiettato nel contesto /Game/Blueprints/AI corrispondente.

La radice Content Browser è sparsa e guidata dai Documenti. Mostra solo cartelle che contengono direttamente un Documento Locus proiettato, oltre agli antenati necessari a raggiungerle. Non rispecchia cartelle /Game non correlate e rimuovere una cartella di presentazione derivata non elimina né modifica la cartella Unreal corrispondente.

La proiezione segue il percorso relativo canonico, non l’UI usata per creare il file. Un Documento rilevato all’avvio, creato in Locus, creato tramite Add > Locus > Locus Documento, importato o creato tramite MCP ha la stessa identità indicizzata e lo stesso comportamento di proiezione.

Crea e trova Documenti

Crea sotto Documenti Locus per un Documento solo Locus. Crea sotto Content Browser per un Documento mappato che viene proiettato nel contesto /Game corrispondente. Add > Locus > Locus Documento in una cartella Content Browser supportata crea la stessa identità mappata. Locus crea un vero file .md esterno, nasconde l’estensione nell’UI normale e apre una scheda editor dedicata. Import Markdown e Documenti creati tramite MCP seguono la stessa politica di creazione locale Non tracciato.

Organizza un nuovo Documento prima di aggiungerlo al controllo del codice sorgente:

Crea → rinomina, sposta e modifica → Contrassegna per l’aggiunta quando il percorso è definitivo.

L’area di lavoro esplora cartelle fisiche e supporta ricerca per titolo/percorso, filtri di stato, aggiornamento, apertura, rinomina, spostamento, eliminazione, checkout, contrassegno per l’aggiunta, import ed export. Puoi aprire più schede Documento contemporaneamente; aprire un percorso già aperto porta il focus sulla scheda esistente.

Per importare, usa l’azione Locus del Content Browser e scegli un file .md UTF-8 valido. Locus conserva byte sorgente e terminatori di riga e usa un nome numerato sicuro se la destinazione esiste già.

La barra degli strumenti Documenti rimane su una riga. Le azioni con priorità più bassa si spostano progressivamente in Altre azioni; Esporta e Aggiorna rimangono lì. Le azioni di controllo del codice sorgente sono assenti quando non è configurato alcun provider.

Modifica e salvataggio

I Documenti nuovi o vuoti si aprono in Modalità modifica; quelli popolati in Modalità lettura. Premi Ctrl+E per la Modalità modifica, Ctrl+R per la Modalità lettura e Ctrl+S per salvare. I Documenti usano il salvataggio esplicito, non l’autosalvataggio delle Nota.

L’editor sorgente offre comandi per intestazioni, enfasi, codice inline e delimitato, elenchi ordinati e non ordinati, elenchi di attività, citazioni, link, tabelle, righe orizzontali, riferimenti ad asset e riferimenti Pin. L’Anteprima divisa mostra il buffer non salvato corrente accanto alla sorgente dopo un breve ritardo di aggiornamento; aprire o aggiornare l’Anteprima non salva il file.

In Modifica, la barra degli strumenti compatta fornisce Intestazione, Grassetto, Corsivo, Codice in linea, Elenco puntato, Elenco numerato, Link esterno, Riferimento all’asset e Riferimento al pin; gli altri comandi rimangono in Formatta. Anteprima divisa renderizza il buffer corrente accanto alla sorgente dopo un breve rimbalzo senza salvare; il suo divisore, lo stato aperto e il rapporto sono preferenze personali.

Modalità lettura e supporto Markdown

La Modalità lettura usa UI Unreal nativa. Supporta le costruzioni Markdown necessarie alla barra degli strumenti dell’editor, incluse intestazioni, paragrafi, enfasi, testo in grassetto, elenchi, elementi attività solo visualizzati, citazioni, codice, link, tabelle con allineamento, righe orizzontali e testo barrato.

Conservazione della sorgente

La presentazione leggibile e l’Anteprima non rigenerano mai Markdown. Il cambio di modalità conserva esattamente la sorgente scritta.

Locus non promette un rendering equivalente al browser o Markdown completo. L’HTML grezzo resta testo sorgente inerte, JavaScript non viene mai eseguito, gli schemi URL non sicuri non vengono attivati e il contenuto remoto non viene recuperato automaticamente. I link HTTP e HTTPS si aprono solo dopo un’azione esplicita nel browser del sistema operativo.

I Documenti conservano Markdown come sorgente mentre la Modalità lettura presenta la struttura supportata nella UI nativa dell’Editor.

I riferimenti ad asset e Pin usano etichette leggibili nella presentazione. Un Pin della mappa corrente può essere focalizzato; un Pin di un’altra mappa può localizzare il livello proprietario senza caricarlo automaticamente. I riferimenti mancanti restano inerti e diagnosticabili.

I riferimenti a Asset risolti, Pin, Nota, Documento e Actor utilizzano etichette leggibili. I riferimenti Actor vengono creati solo trascinando uno World Outliner Actor caricato idoneo in uno Documento in modalità Modifica; non sono offerti da Inserisci Riferimento o @. HTML e JavaScript non elaborati non vengono mai eseguiti e il contenuto remoto non viene recuperato.

Rinomina, sposta ed elimina

Rinomina e spostamento restano nella radice Documenti. Per un Documento Non tracciato idoneo, usa Rinomina nella barra degli strumenti o nel menu contestuale, premi F2, usa Sposta nella barra degli strumenti oppure trascinalo in una cartella esistente valida. L’area di lavoro Documenti Locus è il punto di riferimento per rinominare o spostare; l’elemento Content Browser è una proiezione e la rinomina diretta nel Content Browser non è supportata.

Dopo Contrassegna per l’aggiunta, Rinomina e Sposta sono intenzionalmente non disponibili. Restano non disponibili anche per Documenti controllati, perché Locus non può garantire uno spostamento transazionale indipendente dal provider. Questo limite di sicurezza impedisce che una modifica del filesystem desincronizzi Documento e controllo del codice sorgente. Documenti aperti sporchi o in conflitto bloccano anch’essi rinomina, spostamento ed eliminazione dall’area di lavoro.

L’eliminazione è permanente, richiede conferma e non può essere annullata tramite Unreal. Per i file tracciati, Locus valida lo stato e instrada l’eliminazione tramite il provider attivo prima della pulizia locale.

Le modifiche al percorso sono disponibili solo per locali o Untracked Documento. La ridenominazione e lo spostamento sono disabilitati dopo Contrassegna per l’aggiunta o il controllo del provider perché Locus non esegue spostamenti di depot indipendenti dal provider né trasferisce lo stato aperto tra percorsi.

Esporta

Esporta un Documento selezionato, una cartella, tutti i Documenti o una copia dell’editor. L’export conserva la sorgente corrente — incluso un buffer non salvato quando esporti una copia — e può conservare la struttura delle cartelle. La destinazione non può essere dentro ProjectDocuments; in caso di collisione puoi sovrascrivere, ignorare o creare una copia numerata. L’export non cambia Documento sorgente, scheda o stato del controllo del codice sorgente.

Recupero e modifica esterna

Locus archivia i dati di recupero dei Documenti sotto <Project>/Saved/Locus/Recovery/Documenti/. Un salvataggio riuscito rimuove la copia di recupero corrispondente. Le modifiche esterne senza modifiche locali vengono ricaricate; una modifica esterna in conflitto con testo locale non salvato blocca il salvataggio finché non scegli una risoluzione sicura.

Poiché il file .md è la fonte primaria, gli editor esterni sono supportati. Aggiorna il rilevamento dopo operazioni esterne sui file se l’area di lavoro non si aggiorna rapidamente. Le schede dell’Editor non vengono ripristinate automaticamente dopo il riavvio di Unreal Editor.

Un nuovo Locus Documento preferisce lo stack di schede attivo o Locus Documento attivo più recentemente; lo stesso percorso normalizzato focalizza la scheda esistente. Le schede rimangono liberamente agganciabili ma non vengono ripristinate dopo il riavvio dell’editor.

Anteprima del Documento selezionato

Selezionare un Documento mostra un’anteprima Markdown di sola lettura nel pannello dettagli dell’area di lavoro. Presenta il file di riferimento salvato; usa l’editor Documento dedicato per leggere o modificare il contenuto. Durante una breve transizione normale di selezione, l’anteprima resta neutra finché il contenuto selezionato non è pronto. Solo un’attesa superiore a circa un secondo mostra una spiegazione di caricamento nativa compatta invece di contenuto non aggiornato.

Nome file e percorso del Documento forniscono la sua identità dell’area di lavoro. Un’intestazione Markdown è contenuto, quindi rinominare il file aggiorna il nome visualizzato senza riscrivere un’intestazione come # My Title.

Nel menu Documento Editor Vista, Dimensione carattere sorgente influisce sull’editor di origine e Dimensione carattere lettura influisce sulla lettura completa e sull’anteprima divisa. Ctrl+mouse wheel regola la vista applicabile.

Controllo del codice sorgente

I Documenti sono di proprietà del progetto. Un Documento appena creato resta Non tracciato finché non scegli esplicitamente Contrassegna per l’aggiunta, così puoi organizzarlo mentre il percorso cambia. Un Documento locale o non tracciato resta legittimamente modificabile in Modalità locale. Se Contrassegna per l’aggiunta fallisce, il Markdown valido resta in posizione e può essere ritentato.

Un Documento controllato dal depot resta leggibile ma non può entrare in Modalità modifica o essere Salvato finché il checkout esplicito non riesce. Locus mantiene queste azioni non disponibili quando il Documento è pulito e non in checkout, in checkout da altro utente o client, non aggiornato o disconnesso dal provider. Non offre una soluzione alternativa Rendi scrivibile; Modalità lettura ed Esporta copia restano disponibili quando applicabile.

Dopo la riconnessione del controllo del codice sorgente, l’aggiornamento ripristina lo stato controllato. Il Documento resta di sola lettura finché il checkout non riesce. Locus non invia, sincronizza, gestisce changelist o cambia typemap. Vedi Controllo del codice sorgente, Impatto sul progetto e dipendenze e Risoluzione dei problemi.

Senza provider configurato, Documenti non mostra stato, guida, descrizione comando o azione specifici del controllo del codice sorgente. Un provider configurato ma non disponibile mantiene protetti i file controllati noti.