
DromAddOn
=========

A tool that strives to facilitate working in DromEd.

(Written by Quant, released under the GPL v2)


Use it to:
- locate/work on your objects faster
- have all the objects you're currently working on easily reachable
- check your mission file for typical mistakes
- create links between objects intuitively and quickly, especially for multiple objects


-------- release notes ---------

For a summary about what has changed since the last release, see History.txt.

This is a beta relase, so you bet it contains bugs!
Please let me know of any problems you find (PM me in TTLG).
Suggestions are of course very welcome too.

DromAddOn has so far only been fully tested with DromEd 1.18(for T2) with window size 1024x768.
Lower DromEd-window-sizes were partially tested and should work, but it is likely that there are
problems with other DromEd versions, especially with T1-DromEd.

----- end of release notes -----


Note:
While technically almost everything in DromEd is a "brush", I use the following terms in this manual:
"Brush":  Terrain- (solid,air,...), Area-, Light-, Room- and Flowbrushes
"Object": Objects (duh!)
"Item":   Either a brush or an object


Basic operation:
DromAddOn keeps a list of items from your mission, which you can sort, filter and search.
For objects, you can call up the links- or properties dialog (and others) in DromEd with a click.
Double-click an item to select it in DromEd and move the camera to it.
Right-click on an item to see all the available options.

Link painting facilitates adding links and is described in a separate section below.

So how do you get items from your mission into DromAddOn?
Two ways: either just load your mission file [File/Load from mission file...], or just add single items
from DromEd by pressing the hotkey [Default: Alt-A] or the "Add" button in DromAddOn.
If you want all of your mission items in DromAddOn, importing from the mission file is the obvious way.
If however you only want a small selection of your "favorite" items, using the hotkey may be faster.

Caveat - long object names:
Caution if you use very long object names: When using the hotkey (or Add-button), DromAddOn can only see what
you can see in DromEd. If the object name is truncated there, only the readable part will show up in DromAddOn.
This problem does not exist if you load the items from a mission file.


Main menu:
----------

File/New:
Clear DromAddOn's item list.

File/Open; Save As; Save:
Load an item list you have saved before, or save the current one.

File/Load from mission file:
Read a mission file, and put all items into DromAddOn's list.
Also does a sanity check on the mission file (if so configured in Settings)

File/Check mission file for errors:
Just does a sanity check on a mission file.
Not much at the moment; so far DromAddOn only looks for Death Stage 12 and duplicate links.

File/Generate loot list from mission file:
Generates a report of all loot objects and their individual values.
You will also be asked if you want to put the loot objects into DromAddOn's item list.

File/Settings:
Displays the settings dialog. Most of it should be pretty much self-explaining.

File/Exit:
You don't want to click there. Ever.

Edit/Properties:
For the currently selected item (in DromAddOn): Bring up the properties dialog in DromEd.

Edit/Links; Sources; Receptrons:
Same as Properties, but bring up the Links or Sources or Receptrons dialog.

Edit/Select (in DromEd):
Select the item, that is selected in DromAddOn, in DromEd.

Edit/Go to (in DromEd):
Like Select (in DromEd), but also moves DromEd's camera to the item.
You can also do this by double-clicking an item in DromAddOn.

Edit/Display filter:
Lets you choose which items to show on the list. Hidden items are not deleted, they're just not displayed.
You can also do this by clicking on "Filter" at the bottom of the item list.

Edit/Find object by name:
This lets you quickly locate an object by name. Just type the first few letters.

Edit/Remove from favorites:
Deletes the selected items from DromAddOn's item list.

Edit/Clear all favorites:
Clears all items from DromAddOn's item list.
(The small difference to File/New is that you stay in the same "project", i.e. if you saved the filename
will not be reset to Unnamed)

Misc/Docking:
Usually you want both DromEd's and DromAddOn's windows to be visible. Choose one of the docking options
(default is: to the right of DromEd) to "stick" DromAddOn to DromEd's window.

Misc/Start DromEd:
Well... guess what that one does. You have to configure where DromEd.exe is in File/Settings first.

Misc/Link Painter:
Brings up a new Link Painter window. The Link Painter is explained below.

Misc/Go to DromAddOn web site:
Opens the DromAddOn web site in your browser.

Misc/About DromAddOn...:
Just your typical About dialog.


Toolbar
-------

Add:
Adds the item that is selected in DromEd to DromAddOn's list.
This is the same as using the Add-hotkey (configurable in File/Settings)

Sel:
Select the item that is selected in DromEd in DromAddOn's list.
This is the same as using the Select-hotkey (configurable in File/Settings)

P:
Same as Edit/Properties

L:
Same as Edit/Links


The item (or favorite) list
---------------------------

From left to right, for each item:
Type:  T(errain) L(ight) A(rea) O(bject) F(low) R(oom)
#:     This is the brush number of the item (in DromEd: the number below the Time control)
ObjID: The object ID if the item is an object or a room brush.
Name:  The name of the item.

Right-clicking brings up a popup menu, which contains most of the options from the Edit menu.
Multiselection is possible for some actions (but at the moment "Select in DromEd" does not create a multibrush).
As usual you can sort the columns as you like by clicking on the column headers.

At the bottom you see the current filter settings. Click there to change the filter, or use Edit/Display filter.


The log area
------------

At the very bottom of the main window status messages are print.
New messages always appear at the top.
Red lines indicate error conditions (like trying to select some item that doesn't exist in DromEd anymore).




The Link Painter
================

The intention of the Link Painter is to be able to add links between objects in a more intuitive and
quicker way than in DromEd, and to have a better overall (or partial) view of the links in your mission.

It is best explained by example (detailed reference following):
Let's assume you want to add a new patrol route to your mission.
Add the TrolPt's in DromEd and bring them to DromAddOn (by loading the mission file, or pressing Alt-A
on each TrolPt).
Start the Link Painter (Misc/Link Painter), select the TrolPt's and just drag them from the item list into
the white area in Link Painter.
Things look a bit cramped, so drag a box around the objects to select them all, hold down Shift and drag one
of the objects to space them apart.
Select AIPatrol from the link flavor combobox, hold down Ctrl and drag a line from the first TrolPt to the second.
Repeat this until your patrol path is finished.
Now select "DromEd/Add links in DromEd" and voila - your patrol route is there.

Or assume you want to do a complicated trigger/trap setup that you may want to use more than once:
Start with an empty Link Painter, add some template objects (right-click the drawing area -> Add new template object),
and rename them to something intuitive (like "main switch", "lamp 1", etc.).
Then paint the necessary ControlDevice links between them.
Let's assume there is also a RelayTrap with a couple of targets. Rather than painting each link separately,
select all the targets by shift-clicking, check the "invert" checkbox, then paint the link from one of the targets
to the relay trap. As you see, adding multiple links to/from one object is easy.
[Note: when adding multiple links at once you link FROM the multiple selected objects TO one target.
Select the "invert" checkbox before drawing the links to reverse the direction]
Now you have a nice "blueprint" for your setup, you might want to save it (File/Save link template as...),
so you can reuse it for similar tasks later.
Now create the necessary objects in DromEd if you haven't already done so, and bring them into DromAddOn.
Drag them into the Link Painter.
Move each of the "real" objects into the corresponding template object. DromEd/Add links in DromEd. Done.


Drawback:
Unfortunately I haven't found a way to set link data via DromEd console commands yet.
So for links that need additional data, that data must be filled in afterwards in DromEd.
(In future versions DromAddOn might offer to write link data to a mission file, but not for now.
At the moment mission files are treated strictly read-only.)


Into the details...

Terminology:
"Node": A small circle representing either a real object (filled yellow) or a template object (hollow).
"Link": Well, you should know that this is. Painted as an arrow between nodes, optionally with a label.


Concrete (real) objects vs. template objects:
Link Painter offers you to not only create links between real objects from your DromAddOn list, but also
to create template objects, which are just placeholders to be filled in with real objects later.
That way, you can make yourself a collection of useful link templates that are not associates with a
specific mission (let's say for example a dual light switch/multiple lamps combination), that you can just
load whenever you build such a setup, drag in the concrete objects and you're done.
Another nice aspect is that you can exchange complicated link templates with fellow DromEders.



The painting area
-----------------

Modes:
There are three modes, you can switch between with the 3 toolbar buttons: Move, Link and Size.
Move: move nodes around
Link: paint links between nodes
Size: move multiple nodes closer to or farther away from their common center.

Modes are just a commodity, you never actually need to leave Move mode:
If you Ctrl-drag you paint links, if you Shift-drag you can size while in Move mode.


Selecting nodes:
For some operations a selection of multiple nodes is useful or even necessary (sizing).
To select a single node, just click on it. This will make all other nodes unselected.
Shift-click on a node to add it to/remove it from your selection.
Or just drag a rectangle around a bunch of nodes to select them.

Moving nodes:
Make sure you are in "Move mode" (the arrow-button on the toolbar).
Click and drag (keep the left mousebutton down) a node to move it around.
If multiple nodes are selected, all of them will move.

Linking nodes:
Select the desired link flavor.
Either go to "Link mode", or hold down Ctrl, then drag from the source to the target node.

Linking multiple nodes at once:
If you paint a link while nodes are selected, a link from each selected node to the target will be created.
If you want to link from a single node to the selected nodes, just check the "invert" checkbox.

Sizing (and rotating):
Select a couple of nodes, go to "Size mode", or hold down Shift, than drag one of them.
This will move the selected nodes around and closer to/farther away from their center point.

Associating template nodes with real objects:
Just move a concrete (yellow) node over a template (hollow) node.


The popup menu in the painting area
-----------------------------------

Right-click a node or the label of a link to show the popup menu.

If multiple nodes are selected you will be asked whether to apply the command to all of them or only the node
you right-clicked at. You can not multiselect links in the paint area, so the link commands only affect the
link you right-clicked at (but you can do operations on multiple links in the link list to the left!).


Rename:
Give a meaningful name to a template object.

Remove object or template:
Just deletes the node (and all connected links)

Remove concrete object but keep template:
This removes the object from Link Painter (not from DromAddOn's list), but the node stays (as a template node).

Unbind concrete object from template:
Similar to the above, however the object is not removed, but becomes a separate node.

Change link flavor:
Change the flavor of the link.

Reverse link direction:
Change the direction of the link.

Link active:
Toggle the link between active (green) and inactive (grey).
Only active links will be set in DromEd when you choose "DromEd/Add links in DromEd".

Remove link:
Removes the link.

Add new template object:
Adds a new template object.

Add 10 new template objects:
guess...

Select unlinked objects:
This will select all nodes that have no link connected.

Inverse object selection:
All selected nodes become unselected, all unselected nodes become selected.
[Hint: to select all objects, click into the white area, then choose Inverse object selection]


The link list
-------------

To the left of the painting area you see a list of all the links.
You can show/hide this list with the "Show link list" checkbox or the View menu.

For each link from left to right:
Active-symbol: A green dot indicates an active link, a red dot an inactive link.
Flavor: The link flavor.
From: The source node of the link.
To: The target node of the link.

Multiselection is possible, Right-clicking brings up a popup menu.
As usual you can sort the columns as you like by clicking on the column headers.

The link list popup menu contain the same link-related commands as the popup menu in the painting
area, but here you can multiselect links and alter them all at the same time.


The main menu
-------------

File/New:
Clears all nodes and links.

File/Open link template:
Loads a previously saved link template.

File/Save link template as:
Save your nodes and links.
If there are any real objects present, you will be asked if you want to save them too, or just the
templates.

File/Load links from mission file:
This exists mainly to analyze foreign FMs, but can also be useful if you already have added some links
in DromEd but want to work on the same objects in Link Painter without worrying about adding duplicates.
(Though there is another option specific to the latter part, see below)
You first need to drag in all the objects you're interested in, then choose the "Load links from mission file"
command. All links in the mission whose source and target node is present in Link Painter will be added.
[Hint: Sometimes it is tempting to display all links in a mission file; this is possible by dragging all objects
from DromAddOn's list to the Link Painter and then using this menu command, but usually there are just
way too many links and the painting area just gets overcrowded. Remove flavors you are not interested in,
then select all unlinked nodes and delete them. You might also want to play with the view menu settings.]

File/Disable links already present in mission file:
This will disable (deactivate) any links in your diagram, that are already present in the mission file.
The purpose is to avoid adding duplicate links in DromEd by accident.
When you choose "DromEd/Add links in DromEd" you will be asked if the mission file should be checked first,
so usually you don't need to select that command manually.
[Note: A link is considered as already present if source, target and flavor are identical. Data can't
be checked at the moment]

File/Close:
Closes the Link Painter

View/Draw link flavors:
Toggles drawing of labels on links.

View/Rotate link flavors:
When active, labels are drawn alongside the link arrow (which sometimes looks just plain ugly).
When inactive, labels are drawn horizontally.

View/Draw object names:
Toggles drawing of node labels.

View/Show link list:
Hides/Shows the link list on the left.


The Auto-adapt checkbox
-----------------------

This is more of a gimmick, but can be useful occasionally, especially when you have a lot of links.
While the checkbox is checked an algorithm continually tries to tidy up your diagram by moving nodes.
Expect your CPU usage to stay at 100% while this is checked.
You can manually move nodes while the algorithm is running, but it might feel a bit awkward.
Adding links while this is checked is not recommended.



-- Quant

