MapGen UI - (Very) Preliminary Information - VERSION 0.1

Written By Vito Plantamura - Italian Version

NOTE PER I TESTER E GLI SVILUPPATORI

QUESTA VERSIONE DEL MAPGEN E DELLA DOCUMENTAZIONE APPARTENGONO AD UNA DISTRIBUZIONE INTERNA NON PUBBLICA

(c)1999,2000 3D Heavy Industries, Vito Plantamura

SE NON AVETE RICEVUTO QUESTA COPIA DEL MAPGEN DIRETTAMENTE DALL'AUTORE, SI PREGA DI NOTIFICARLO A VITO PLANTAMURA.

Precisazioni

Le informazioni di questo documento sono assolutamente preliminari; poichè il programma (MapGen, editor) ed il motore stesso sono in piena fase di sviluppo le informazioni di questo documento possono essere modificate in qualsiasi momento, se necessario, a seconda delle modifiche apportate al programma. Più specificatamente questo documento dovrebbe essere inteso come una guida sommaria alle attuali funzioni e comandi del MapGen (per aiutare il testing ed il quality assurance) e come una descrizione per sommi capi della attuale tecnologia implementata. Non sono discussi qui tutti i comandi del programma, quindi è necessaria, per la totale comprensione di questo documento, una buona conoscenza di editor CSG di ultima generazione e di una sommaria conoscenza di IDE di sviluppo C.

Note Per I Level Designer

E' altamente consigliato utilizzare un mouse con 3 tasti e la rotellina, che consente di effettuare l'operazione di zoom senza dover selezionare l'apposità modalità dalla toolbar "Mode".

BCGControlBar

E' possibile personalizzare praticamente ogni aspetto dell'interfaccia utente del programma. Tenendo premuto il tasto Alt è possibile trascinare i pulsanti delle toolbar oppure i menù. Per accedere a tutte le funzionalità di personalizzazione, aprire il dialog "File - Customize - Customize".

MiniC

Il MiniC è un linguaggio di programmazione di tipo procedurale molto simile al C. Nel MapGen è incluso il compilatore MiniC, che produce file con estensione ".o" che vengono linkati run-time dall'engine. L'attuale installazione del MapGen dovrebbe contenere nella directory "include" il set *preliminare* degli standard header file. Gli header file specifici dell'engine, verranno inclusi successivamente. Attraverso questo linguaggio, è possibile descrivere il comportamento degli shader e delle entità nel contesto del gioco.

Entità

Le entità sono rappresentate nel contesto del MapGen da file con estensione ".ent". Questi file descrivono le caratteristiche di ciascuna entità come lista di parametri da passare alle equivalenti procedure scritte in MiniC. Nel MapGen questi parametri sono rappresentati, ad esempio, per la entità "light", dall'intensità o dal tipo di light.

ENT e script

Il MapGen permette di scrivere sia file ".ent" che script MiniC. E' possibile caricare file ".ent" nell'entity manager del programma oppure controllarne la sintassi con l'apposito comando del workspace ed è possibile compilare gli script MiniC.

Mouse

Di seguito la lista delle funzioni accessibili attraverso il mouse:

- TASTO SINISTO: funzione selezionata
- TASTO DESTRO: modalità "pan".
- TASTO CENTRO: rende le brush selezionate strutturali e modifica l'attuale modalità a seconda del tipo di selezione (è appropiato fare qualche prova per prendere dimestichezza con questa feature).
- ROTELLINA: modalità "zoom".

Standard Toolbar

Permette di effettuare le operazioni classiche di una applicazione Windows: apri, salva etc...

Object Wizard Toolbar

Permette di selezionare il tipo di primitiva da utilizzare nelle creazioni "freehand" oppure di creare l'oggetto attualmente selezionato. I vari oggetti creabili sono disposti secondo una logica categoria-classe-oggetto. Le categorie attualmente disponibili sono:

- Brushes
- Entities
- Patches

Nella versione definitiva del MapGen sarà inclusa anche la categoria "Meshes". Premendo il pulsante "default action" viene intrapresa l'azione di default, mentre aprendo il popup menù al lato è possibile scegliere quale azione intraprendere a seconda del tipo di oggetto attualmente selezionato.

Mode Toolbar

Permette di selezionare l'attuale modalità di editing. Le funzioni delle modalità messe a disposizione sono di facile intuizione. La modalità freehand ha diverse funzioni all'interno del programma:

- Creare Primitiva-Entità (selezionata la primitiva dalla object wizard è possibile crearla premendo e rilasciando il tasto sinistro del mouse su una editor pane nella posizione desiderata oppure premendo il tasto sinistro del mouse, descrivendo la forma della primitiva e successivamente rilasciando il tasto).
- Muovere Primitiva (premendo il tasto sinistro del mouse e trascinando la primitiva già creata e SELEZIONATA). Premendo il tasto "shift" è possibile modificare l'attuale posizione nello spazio delle editor panes.
- Trascinare Faccia Primitiva (premendo il tasto sinistro del mouse in corrispondenza di una faccia della brush TENENDO PREMUTO IL TASTO SHIFT).
- Scalare Primitiva (premendo il tasto sinistro del mouse in corrispondenza di una faccia della brush oppure di un corner).
- Altre accessibili attraverso la toolbar "patch mode" (vedi).

E' necessario notare che tutte le funzioni messe a disposizione dalla modalità "freehand" sono utilizzabili su una sola brush selezionata. Se per esempio sono selezionate due brush, utilizzando la modalità freehand si provoca la deselezione delle brush selezionate e la creazione di una nuova primitiva secondo le regole sopra descritte. Per scalare due o più brush selezionate utilizzare la modalità "Uniformly Scale Object" oppure "Non-Uniformly Scale Object". L'utilizzazione della modalità freehand è ideale in combinazione con il tasto centrale del mouse.

La modalità select and add può dare problemi se non utilizzata con giudizio: per evitare di creare gruppi "indesiderati" utilizzare il tasto SHIFT per selezionare la brush o il gruppo di brush giusto e rilasciarlo per includere la selezione nel gruppo.

Operations Toolbar

Questa toolbar fornisce accesso alle operazioni CSG ed alle operazioni sulla clipboard. L'operazione di undo fornisce un unico livello di protezione (e solo le operazioni "distruttive" sono protette escluso l'operazione "CSG subtract" e "ungroup"). Le operazioni "scope up" e "scope down" permettono di "attraversare" la gerarchia del gruppo selezionato. L'operazione "ungroup" distrugge il gruppo selezionato: se sono selezionate, ad esempio, tre brush (che appartengono allo stesso gruppo) e si applica l'operazione "ungroup", viene distrutto il gruppo e le tre brush possono essere selezionate singolarmente dal livello precedente di scope.

Build Toolbar

Questa toolbar permette di accedere alle funzionalità dei compilatori inclusi nel programma.

Patch Mode Toolbar

Permette di selezionare l'attuale modalità di editing per la patch selezionata. Per poter accedere alle funzionalità di questa toolbar devono essere verificate alcune condizioni:

- Deve essere selezionata la modalità "freehand" dalla "Mode Toolbar".
- Deve essere selezionata un'unica patch.
- Deve essere aperta la "Selection Properties Bar" e deve essere selezionata la tab "Surface" (vedi).

Premendo il tasto shift è possibile modificare l'attuale patch mode.

Per edittare più patch contemporaneamente premere "Alt+W" attivando la modalità Mode - Bezier Patches - Weld Control Points Of Different Patches. In questa maniera anche se è selezionata un'unica patch, tutti i control point corrispondenti (a prescindere dal livello di scope!) di tutte le patch della mappa verranno trasformati assieme ai control point selezionati.

I pulsanti di questa toolbar sono i seguenti:

- NORMAL: si tratta della normale freehand mode: cliccando sulla patch è possibile traslarla e cliccando su un lato o un corner è possibile scalarla.
- SELECTION: permette di selezionare un gruppo di control point. Tenendo premuto il tasto alt si scartano dalla selezione i control point evidenziati; tenendo premuto il tasto ctrl si includono nella selezione i control point evidenziati. Cliccando su un control point selezionato, tutti i control point selezionati vengono traslati.
- ROTATE: permette di ruotare i control point selezionati. Attenzione: cliccando SU un control point selezionato i control point vengono traslati e non ruotati. Se non sono selezionati control point, viene visualizzato il selection box che permette di selezionarne senza modificare l'attuale patch mode.
- SCALE: permette di scalare i control point selezionati. Attenzione: cliccando SU un control point selezionato i control point vengono traslati e non scalati. Se non sono selezionati control point, viene visualizzato il selection box che permette di selezionarne senza modificare l'attuale patch mode.

Help Toolbar

Permette di accedere alle funzionalità dell'help del programma. Il controllo internet explorer si trova nella workspace bar (vedi) premendo la tab "help".

Workspace Bar - Files

Permette di gestire i file attualmente inclusi nel workspace. Cliccando col tasto destro del mouse su un file è possibile attivare un menù contestuale che permette di eseguire operazioni specifiche sul file selezionato. Attenzione: alcune operazioni messe a disposizione da questo menù contestuale non sono accessibili da nessun'altro menù o dialog del programma.

Workspace Bar - Shaders

Permette di gestire gli shader attualmente inclusi nel workspace attraverso lo shader browser. Se si clicca su uno shader col tasto sinistro del mouse, questo shader diventa il "default shader": tutte le seguenti operazioni di creazione di brush utilizzeranno questo shader. E' importante notare che esiste uno shader speciale (col nome univoco di "entity"): questo shader viene utilizzato per la creazione di tutte le entità a prescindere dall'attuale selezione nello shader browser. Se si clicca su uno shader col tasto destro si attiva un menù contestuale che permette di eseguire alcune operazioni specifiche sullo shader selezionato. Le funzionalità di questo menù contestuale non sono accessibili da nessun altro menù o dialog del programma.

NOTE PER CREARE UNA SEMPLICE TEXTURE DI PROVA

- cliccare col tasto destro su qualsiasi punto dello shader browser
- selezionare new shader
- utilizzare il tasto sinistro del mouse per scrollare lo shader wizard
- immettere in "shader name" il nome dello shader
- selezionare la tab "ass. textures"
- doppio-cliccare sull'item (empty) del list box sottostante oppure cliccare su "new" ()
- specificare il file bmp (a 24 o a 8 bit) contenente la texture
- immettere un nome per la texture (è significativo se si crea uno shader con più layer oppure si eredità da uno shader esistente)
- premere invio oppure "accept" dello shader wizard

Workspace Bar - Help

Permette di consultare l'help del programma.

Selection Properties Bar - Face

Permette di modificare le caratteristiche e gli attributi di una faccia. La maggior parte delle opzioni presenti in questa bar sono comuni a tutti gli editor CSG. Per poter scrollare la bar (se la modalità video impostata non fosse sufficiente a visualizzare l'intero contenuto) utilizzare il tasto destro del mouse (oppure il tasto sinistro cliccando su una client area non occupata da pulsanti, edit box oppure check box). "Recalc ST Axes" permette di ricalcolare gli assi st della texture (shader) applicata alla faccia corrente sulla base del cube mapping. Il "cube mapping" consente al level designer di disporre le brush nella mappa in maniera che le texture applicate sulle rispettive facce rimangano naturalmente allineate. Questa feature però crea una leggera "distorsione" della texture per tutte quelle facce non allineate agli assi. In alcune circostanze questo effetto non è desiderato oppure le intenzioni del mapper sono totalmente differenti: ad esempio se si desidera creare una colonna inclinata con due capitelli in maniera che le rispettive texture abbiano un allineamento consistente:

è necessario attivare l'opzione "Mode - Textures Lock - During Rotations": in questa maniera viene disattivato il cube mapping è le texture vengono mappate secondo l'inclinazione delle rispettive facce. L'operazione "Recalc ST Axes" permette di riapplicare il cube mapping su queste facce.

Le face attributes permettono di modificare i bit del vettore di attributes della faccia corrente. Gli attributi disponibili di una determinata faccia dipendono esclusivamente dallo shader attualmente applicato su quella faccia: per la creazione degli shader e la definizione dei bit di attributes (che possono appartenere anche a super-shader dello shader corrente) si utilizza lo "shader wizard" (vedi).

Selection Properties Bar - Entity

Permette di:

- Applicare ad una brush o ad un gruppo di brush una determinata entità.
- Applicare ad una brush o ad un gruppo di brush una entità diversa da quella attualmente applicata.
- Eseguire il detach della entità della selezione corrente (è possibile farlo anche attraverso il pop-up menù della object wizard (vedi)).
- Modificare i parametri della entità applicata alla selezione corrente.

Se non è selezionata alcuna brush, vengono visualizzati i parametri della entità applicata alla mappa (di solito l'entità "world").

La colonna details fornisce informazioni specifiche sull'attuale settaggio del parametro. Questa informazione è consistente se il parametro è di un tipo definito (non di base): ad esempio il parametro "Angle" è di tipo angle_t; angle_t definisce i quattro punti cardinali come angoli assegnabili: se si assegna ad un parametro di tipo angle_t il valore di 90 (che corrisponde a North), details riporta l'informazione sul settaggio noto. Se si assegna ad esempio 89, details è "custom" poichè il tipo angle_t non definisce nessun membro col valore di 89.

Per visualizzare i membri del tipo del parametro premere il tasto "giù" o doppiocliccare sull'edit box quando si viene promptati per inserire il nuovo valore per quel parametro (doppiocliccando sul parametro stesso). MapGen visualizza una finestra di questo tipo (elencando tutti i membri ed evidenziando quello selezionato):

E' importante notare che i tipi definiti possono anche rappresentare vettori di bit (permettendo di selezionare più membri(bit) del tipo del parametro). In questo caso details informa sul significato del valore inserito come lista di tutti i bit selezionati.

Selection Properties Bar - Surface

Permette di creare e modificare patch di bezier. Per creare patch è possibile utilizzare la object wizard che può rivelarsi più versatile in alcune circostanze. Per accedere alle funzionalità di "texture offset", "texture scale", "rotation angle", "patch actions" e "patch attributes" è necessario che sia selezionata un'unica patch.

"texture offset", "texture scale" e "rotation angle" hanno lo stesso significato delle facce delle brush ed il loro valore viene "trattenuto" dalla patch anche quando quest'ultima viene deselezionata e poi riselezionata. "patch attributes" ha lo stesso significato di "Selection Properties Bar - Face" e dipende esclusivamente dallo shader attualmente applicato alla patch.

CodeView Bar

Permette di edittare gli entity set e i file di script MiniC.

PROBLEMI: attualmente la codeview bar presenta problemi riguardo alla consistenza dell'operazione di undo: questa funzione (con un solo livello di protezione) è attivabile solo in alcune circostanze. Ci sono problemi inoltre sotto WindowsNT e Windows2000 a causa di una differente implementazione del rich edit control nel sistema operativo: questo si traduce in problemi (assenti se il programma è utilizzato sotto Windows98) per le operazioni di "paste" quando il contenuto della clipboard è formattato in una determinata maniera (nella fattispecie il testo trattiene alcune caratteristiche della precedente formattazione una volta incollato).

Output Bar

Visualizza l'output della compilazione della mappa e degli script MiniC.