Assimilation Software editor
============================

This editor allows the creation of OBJECTS for ass engine games (not MAPS). Maps may contain multiple objects and the actual architecture of a map is defined as an object. Objects themselves are static, but within a map, they can move and rotate according to specially written code.

The editor is based upon technology within the game itself and uses the same "data repository" system.

Notes on the editor:
   - Creates objects, not maps (ie. must wrap the object into a map before use)
   - Polygons must be PLANAR
   - Polygons and vertices are renumbered when some are deleted. Just be aware that numbers can change!


File formats
------------

See modedit.txt

Hardpoint Editing
-----------------

This only applies to Armada and SFC files (all versions).

Actually this is more than just hardpoint editing, but it is often referred to as mere hardpoint editing in
the program. For SFC, it can edited all types of points. For SOD, it can edit the entire node hierachy.

There is quite a bit to explain about this so please bear with me. I'll try to document it well...

Each SOD or MOD file (3D file) being "edited" has an associated "hardpoint dump file". The file is named simply 
with the same name as the 3D file, but with ".pnt" appended to it. The first time the 3D file is loaded, its 
hardpoint dump file will be auto-generated from the original hardpoints of the 3D file. Once the file is in place,
it will not be altered unless the user specifically asks for it to be by saving their changes to it.

Editing hardpoints is a three step process:
 - Load up the 3D file for the first time, and the hardpoint dump file will be generated.
 - Edit the hardpoints in the editor and save your changes to the dump file. You can save your work and quit the
   editor as many times as you like. Next time you open up the 3D file in the editor, your changes will be there
   (hardpoint dump file is automatically loaded after the 3D file is).
 - When you are completely done, you can "lock" your changes back into the 3D file itself. Now your work is done.

If in the future you want to go back to editing hardpoints for this 3D file, you have two options:
 - If there is a hardpoint dump file associated with the 3D file, you can delete it. Whatever hardpoints are in
   the 3D file will be put into a new dump file.
 - If the 3D file has been updated by the modeller, you can still use your old hardpoint dump file in it, if it
   is in place with the proper filename (if the 3D filename hasn't changed, then the file is already named
   correctly). Just make sure the hardpoint dump file is in the same folder as the 3D file. This is a good
   reason to keep backups of your hardpoint dump files.

I hope you understood that. I will try to explain it in another way just incase...

Each 3D file has one hardpoint dump file associated with it. It has a specific name (same name as 3D file, but
with .pnt appended) and is in its folder. If you open up a 3D file and there is no hardpoint dump file yet,
it will be generated from the original hardpoints in the 3D file. The operations of the editor always work
upon your hardpoint dump file until you choose to lock your changes back into the 3D file. If you want to
edit hardpoint dump files manually, or back them up, or use them on different models, this all works. You just
have to use Windows Explorer to fiddle with the files yourself. The files are just plain text files and as
long as they have the correct filename for the 3D file you are working with, and are in the same folder as that
3D file, the editor won't care how they got there.


Now I will explain the hardpoint editing features available...

Keypresses:
 - For the various menu options, they're keypresses are shown on the actual menu.
 - To move the selected hardpoint hold down shift and use A,Z and the arrow keys. I highly recommend that you
     use the frame view whilst doing it: you will get a much better grip of where the hardpoint is in 3D space
     (damn perspective ;).

From the menus:
 - Add. Add a new hardpoint on the origin. It will automatically become selected so you can move it to the
   desired location in the usual way.
 - Delete. You will be asked which hardpoints you wish to delete.
 - Select. You will be asked which hardpoint to select.
 - Move. You will be asked the desired location to move the selected hardpoint to.
     If there is no selected hardpoint, you will be asked which hardpoint to move also.
 - Lock. Lock your changes back into the 3D file.
 - Save. Save your changes to the hardpoint dump file.
 - Load. Load your changes from the hardpoint dump file.
 - Renumber. Sequentially number the hardpoints.
 - Relabel. You will be asked for a new ID for the selected hardpint.
     If there is no selected hardpoint, you will be asked which hardpoint to relabel also.
 - Scale. This will stretch all the hardpoint coordinates. Please see note about scaling. An example of when to
     use this feature would be if you are using hardpoints from, say, Deemons lovely Akira vessel and manually
     copying the hardpoint dump file so it is set up to work with an Akira for SFC. Chances are you will need
     to do a slight rescale of the hardpoints to make it fit.
 - Hierachy. See Armada notes.
 - Filter. Applies a filter string so only points containing that filter string are shown. See Armada notes.
     This is not a wildcard system, so * and so on will not have the desired effect.
 - Change point drawing axis size. The axes of points are drawn for the selected SOD hardpoint. You will want
     to change how large they are drawn depending on how far you are viewing the hardpoint from.

Notes:
 - The selected hardpoint is drawn in a different color to the others.
 - Scaling: There is the option for 3D files to be scaled when they are loaded. This is because the editor
   can load many different file types and they are often set to different scales. The issue with hardpoints
   is that they are also scaled on loading so they still fit the geometry. When the hardpoints are locked
   back into the 3D file, they are descaled again.

SFC notes
---------

Name the hardpoints like "hardpoint1".

Name damagepoints (where sparks etc fly from) like "damagepoint4".

Armada notes
------------

As the whole hierachy can be edited, there needs to be a way to edit the tree structure. This is done from
the hardpoints pull down, under the option "Hierachy". Mesh nodes are locked into place.

There are some conventions so that it is known whether nodes are NULL nodes (hardpoints, and general nodes
used to glue things together), sprite nodes, emitter nodes or lod control nodes.
 s_WHATEVER = sprite. Sprite used is determined by the identifier name
 e_WHATEVER = emitter. Emitter used is determined by the identifier l_e
 l_WHATEVER = LOD control node
All others are NULL nodes.

Note: For Armada, nodes located at the origin that aren't selected aren't drawn, to avoid a mess due to
so many nodes being in the hierachy. To make it even cleaner, press 'O' to turn of all but the
selected hardpoint. If you want a compromise, choose a filter from the hardpoints pulldown.
Only nodes that contain the filter in will be shown. eg. choose "hp" to only show things with
hp in them (eg. hp1, blahp01, etc).

Textures
--------

See modedit.txt

Textures in the game are all given names, and are defined in a data repository format (see "tech manual" on the website for more info).

Textures are currently auto-mapped to polygons in a pseudo-sensible way (although the user can remap them), but soon there will be an option to do much more intelligent auto-mapping.

Important facts:
   - Texture dimensions have to be 2^x by 2^y. where x and y are whole numbers. ie, 1,2,4...64...256...1024. eg. 512 by 512 is a valid texture dimension, but 304 by 324 isn't. This shouldn't be a problem, as this is a fairly standard precondition.
   - The following textures are supported: png (our prefered format), pcx, bmp, tga, jpg, gif, lif. 32 bit colour depth is preferred.

Autosave
--------

The editor autosaves every 15 operations to "autosave". This is up to the user to reload if they want it.

Models, Meshes and Objects
--------------------------

These are all the same thing in the engine.

Cameras and frames
------------------

The camera is the viewpoint the user of the editor has when they are editing a model. The engine supports frames, which allows the editor interface to be split into four sections, each with its own camera. By default 3 frames are non-perspective (looking along each x,y,z axis respectively) and frame 4 is the standard perspective, on-looking frame. The current frame is the frame the mouse is over.

The Editing screen
------------------

At the top of the screen the current cameras angles are shown, as well as the object filename (if the resolution is at least 800x600) and the Menus. At the bottom of the screen the current cameras position is shown, as well as information about currently selected polygons and vertices.

The rest of the screen is taken up by editing frames.

Menus and keymapping
--------------------

By clicking on the menu labels at the top of the screen access to pulldown menus can be obtained. There are loads of options available from these menus, and most have keys associated with them (shown in brackets after the description). The General menu gives access to a keyboard-help-screen and other important functions.

Editor syntax
-------------

Usually various functions are done on the selected vertices or polygons. However, the editor is clever enough to react to whether vertices or polygons are selected or not and if they aren't then it will ask for some in editor syntax. This syntax allows comma separated terms to be input, with support for ranges and the * wildcard.

For example:
   - to use everything for an operation, enter "*"
   - or to use just the vertex/polygon numbered 0, enter "0"
   - or to use a few unconnected vertex/polygon's, enter eg. "0,1,5,3,7"
   - or to use some ranges, enter eg. "0-5,7-10"
   - or to do something more complex, enter eg. "0-10,13,15,18-34"

Viewing methods
---------------

Perspective, back-face-viewing and drawing-mode can be toggled for all frames. Drawing-mode is either wireframe or solid. If back-face-viewing is on then polygons can be seen, whatever side of them you are looking at, even if the polygon is two-sided.

Vertices are drawn by a red (unselected) or orange (selected) circle with a number inside them. Polygons have numbers put approximately in their middle. Sometimes models can be so complicated that they just get covered in polygon-numbers and vertex circles/numbers when viewed from a distance. Therefore these numberings can be turned off.

Polygons can be temporariliy-hidden to make editing easier, so that they don't get in the way.

The farplane is the cutoff position infront of the camera, after which, nothing is drawn.

Orthographic-scaling changed non-perspective frames so that they're content is scaled. Perspective frames are scaled by simply moving the camera, but this can't be done on non-perspective frames without orthographic-scaling.

The origin is marked on a frame by default, but can be turned off. The same is true for the view grid.

Tooltips
--------

Holding the mouse over a vertex will show that vertex's position, if tooltips are turned on.

Selecting vertices and polygons
-------------------------------

These can be selected in a number of ways...

Vertices:
   - Usually these are selected using the left mouse button. If the Ctrl key is down when the button is clicked then the vertex will be selected in conjunction to the ones that already are selected. If Ctrl is not down then the other vertices will be deselected first. If Ctrl is down and the vertex is already selected, then it will be deselected instead, but the other vertices will still be kept intact.
   - Because there may be many vertices close together, it may be better to select manually. Therefore there is an option on the menus to select vertices using editor-syntax.

Polygons:
   - Same as vertices except with right mouse button for easy selection.
   - Equivalent options exist on the menus for manual selection.
   - They can also be selected by texture from the menus.

When a polygon or vertex is created, they are selected, along with what was already selected.

Transformations
---------------

The editor supports a few mathematical transformations on parts of the object being edited. These are:
   - translate: shift selected/chosen vertices along axes
   - move: move selected/chosen vertices to a specific location
   - scale: multiply selected/chosen vertices by a number
   - rotate: rotate around different axes
   - flip: invert selected/chosen co-ords in axes

The Centre object simply places the averaged centre of the object on the origin.

Visual-transformation-modes allow transformations to be done using the keyboard, bit-by-bit. When in a mode, Ctrl+Arrow keys and Ctrl+A/Z allow the function to be performed. For example, when in visual rotation mode, Ctrl+Arrow keys rotate the selection/chosen vertices bit-by-bit. Non-visual-transformation-mode allows translation to be done like when inside the visual-translation-mode.

Transformations can either be done around the origin, or the centre of the selected/chosen vertices. This is toggled using the "Transform about origin/vertex centre" option.

The Move speed
--------------

This defines how far the camera moves, or something translates in visual-translation-mode, in one-go. It is defaulted, but it may be useful to change for large or small objects.

Making a mesh
-------------

The vertex creation position is in-front of the camera somewhere and can be tuned with +/- as above. When you press insert, a vertex is created at the vertex creation position (unless manual-vertex-coords is turned on, where vertices co-ords must be manually specified). The vertex is auto-selected. When three or more are made, a polygon can be created. Polygon vertices must be selected in clockwise order for the polygon to be sensible (if done in anti-clockwise order, then the polygon will be flipped). Therefore, the vertices should be made in clockwise order before a polygon can be made. When this is done Ctrl-insert will create a polygon from them (with default texture), and the vertices will be deselected. The new polygon will be selected and its texture can be changed (Press T). A suitable one can be selected. This process is then repeated, except vertices connected to existing polygons are used as part of the next polygon (using the standard selection methods, clockwise).

Combining objects: duplication and inserting
--------------------------------------------

To stop the user having to remake all the standard components for every model they make, if is possible to insert objects that are already saved into the current object. The editor supports three built in directories of objects, for saving to and loading from:
   - final: objects to eventually be used in the game
   - geometric: objects like cubes
   - components: objects like nacelles and saucer-sections

When the old object is inserted (at the vertex create position), its vertices are selected and visual translation-mode is entered, so that it can be moved to a sensible position.

The duplication mode simply copies specififed vertices and polygons made from specified vertices as if they were an old object being inserted.

Setting permanent editor options
--------------------------------

The data repository config file data\text\tech.ini holds a number of options that can define editor/game default-behaviour. I'll leave it to you to work out what does what.

Keypresses and Mouse input
--------------------------

Left-click           Select vertex
Ctrl + Left-click    Select multiple vertices

Insert               Create a new vertex
Del                  Delete selected vertices

Esc                  Quit to menu

Up/Down/Right/Left   Move upwards/downwards/rightwards/leftwards
A/z                  Move forwards/backwards

</>                  Turn left/right
Page Up/Down         Turn up/down

Alt + Up/Down        Circle the origin in a vertical plane
Alt + Right/Left     Circle the origin in a horizonal plane

+/-                  Move the vertex create position forwards/backwards

Ctrl + Arrows/A/Z    Do the current transformation on selection

Shift + Arrows/A/Z   Move the selected hardpoint

Shift + Page up/down Rotate the selected hardpoint around its x axis
Shift + </>          Rotate the selected hardpoint around its y axis
Shift + {/}          Rotate the selected hardpoint around its z axis

Print Screen         Take a screenshot


You can use the mouse for rotation and zooming:
 Zoom by holding down the right-button and dragging up and downwards.
 Rotate by dragging the mouse around when holding down the left button.


See the pulldown menus for the other keypresses. They are detailed next to the commands on those
menus.
