This document isn't actually a tutor. Just as I observed, many people seem to use JED in ways that even scare me. Not that there is a single certified way of using it, but many things can be done much simpler and in more effective manner. Besides, it might be of some interest to you to know how exactly JED tools work - it might help you using them more effectively. So I decided to write this document to explain how some basic tools work and were intended to be used. You can go from there.


Table of Content:


Map controls

Frankly, I'm not too clear on this myself. I couldn't quite make it work the way I wanted because of some strange ways OpenGL works, so I just put it off until I implement custom wireframe renderer. Anyway, basically you need to rotate it in all three directions (Shift+left/right/up/down/pgup/pgdn) until you like it. If you get lost use 1..6 and Shift+1..6 to switch to left,right,front,back,top,bottom views. Adding shift also positions the grid perpendicular to the view - the most effective position to move things on it.

Selecting things

To select something, click on it. If what you wanted to select didn't get selected, click once again while keeping the mouse still (important). The next possible thing gets selected. Sometimes, for instance when you want to select a surface, it might be a better idea to select an edge or a sector, then switch to surface mode and use N (next) and P (previous) to get to the surface you need. For edges you can also use Shift+N,Shift+P to cycle edges within a surface.
Also, in edge mode the first vertex of the selected edge is big and the line in the middle of the edge shows the direction of the plane this edge belongs to. This is useful to tell which edge you have selected.
Selecting things and lights is trivial. BTW, the selected thing shows its approximate size (that's the size specified in the template. It looks wrong in may cases, I know. In the next version I hope to have an actual bounding box of the 3DO). The vector shows the orientation of the thing.

Editing Attributes

To edit object attributes you need to invoke Item Editor. It's done by pressing "Enter" or picking "Item Editor" in "Tools" menu. There's really not much to tell here. Except a couple of things:

And a couple of things on editing thing attributes. "Add Value" button lets you add extra thing values. Most times it's "THINGFLAGS" or "NFRAMES" and "FRAME" fields. If the field you added is assigned a value in thing's template, it will be automatically extracted. "Delete Value" will delete the selected value (naturally you can't delete values from "LAYER" and above). "Copy As Frame" will copy to clipboard the position and orientation of the current object in a form required for "Frame" value in elevators, doors, etc.

Using grid

Grid is the center of JED universe. Just about every editing operation uses grid in one way or another. The idea of the grid is to let you do all operations in 2D, while performing them in 3D. The way it works is the following: Grid is a plane 3D space. The reference point - i.e. the point where, for instance, an object will be added if you press "INS" is the point on the grid plane under the mouse cursor. So, depending on grid orientation that will be a different point.
The grid is displayed as a series of dots and lines. You can set the distance at which dots and lines are drawn on "Grid" tab in "Map Settings" (a.k.a. ToolBar) window. These two are just visual things. The third - grid step ("Snap every:"field in Toolbar) affects editing. The grid has a center and sort of a coordinate system. The grid lines show the direction of axis. This coordinate system, together with grid snapping step determines the location of "snap points" - points to which the reference point is snapped (moved) if "Snap to Grid" is active. While the grid is shown as a finite structure, the grid plane is actually infinite.
To do most operations you must position the grid appropriately. IMPORTANT - when you view the grid from the side (it looks like a line) you can't do any editing! Well, except moving things perpendicular to the grid, which is a quick hack. Because mouse position cannot be projected on the grid plane in this case. Theoretically you can rotate the grid (hold R and move the mouse), but it doesn't work too well. The more useful ways are:
Moving objects around

To move objects around you need to hold down "Ctrl" and drag the mouse. The object will move along the grid. If an object doesn't lie on the grid plane it's moved along the plane parallel to the grid plane. If "Snap to grid" is enabled, the object will be snapped to grid. If you hold down "Ctrl" and "Shift" then object will be snapped to vertices. When dragging sectors, the point that is snapped is vertex 0 of the sector, in case of surfaces and edges - 1st vertex of the surface/edge. That reminds me - in the next version those vertices will be clearly visible in selected sectors/surface.
Although dragging geometry objects (sectors/surfaces/edges/vertices) is implemented, it is not recommended to do that. You're only likely to introduce errors.

Cleaving

Cleaving is intended to be the main editing operation. Combined with merging, extrusion and deletion it lets you create anything. Theoretically using it you won't ever need to move individual vertices/surfaces/etc.
The cleave is activated by pressing "C". The cursor changes to what I meant to be the LightSaber. Then you need to hold down left mouse button and draw a line on the grid that will define the cleaving plane (don't confuse - you draw the line on the grid, not on geometry! Look at the grid to predict the position of the cleave!). When you release the mouse button the cleave is executed. If "Snap to Grid" is active, then the starting and the ending points of the line are snapped to grid. You can also hold down "Shift" to snap the start and/or the end of the line to vertex.
The cleaving plane is defined in the following way - it is perpendicular to grid and goes through the line you drew on the grid. This PLANE cleaves the selected (and only the selected!) sector/surface/edge in two.
The best position to cleave is when grid is perpendicular to screen. However, when you get the hang of it, you mind find it even more convenient to cleave in titled view.
As this is a pretty complex operation to program, I had to make some assumptions when making it. Thus there are some things you need to look out for to avoid problems in cleaving. I assume that the sector/surface you cleave is correct - convex, planar, etc. So, if you try to cleave sectors/surfaces that exhibit consistency errors, be careful. Save first. Also look out that adjoin of the surface (if it's adjoined) is valid, as it's automatically cleaved as well.
When cleaving non-convex surfaces/sectors the thing to look out of is that your cleave doesn't create more than two sectors/surfaces. if it doesn't - you're OK. Otherwise you are in trouble...

Merging

Merging is the opposite of cleaving. To merge sectors you must select and adjoined surface that connects two sectors you wish to merge and press "M". To merge surfaces you need to select and edge that connects them. In that operation you need to watch out for creating non-convex sectors/surfaces. The rest is pretty trivial. A couple more things, actually - you can't merge adjoined surfaces so far. I promise to fix that. For now you'll need to unadjoin them, merge both pairs and readjoin. Also, when you merge surfaces you might have extra vertices - you don't want. You can delete them. There's actually only one type of vertices that can be deleted - the ones that lie on the edge shared between two just surfaces. You can experiment with that - JED won't let you delete vertices that can't be deleted.

Placing things

A lot of confusion seems to be in placing things. It's generally not a good idea to place things in tilted view. To place things it's best to use Shift+1..6 to switch top/bottom/left/right/etc. views. Another trick would be using [ and ] to move things/lights perpendicular to the grid. To do that it's best to have look at the side of the grid. When you look for things in resource picker its useful to use display masks. These masks accept wildcards. For instance, if you need to find something with substring "gun", type "*gun" in mask edit box. You'll have just a handful of things to pick from. Simplifies things tremendously. And yes, I do plan to add 3DO preview, but not just yet :-).

Stitching

While other texturing tools are pretty trivial, I've been getting some questions about stitching. Stitching is aligning surfaces on faces so that the texture smoothly went from face to face as if it is the same face.
The stitching works as follows:
First you select a surface you want to start stitching from. Then press "Select stitch surface" key - ";". In the next release you can also use "Ctrl+INS" as "Select stitch surface" is inconvenient to use on some national keyboards. Then you select a surface you wish to stitch to the one you chose. Then press "stitch" key. The texture from the original surface is set on the current surface. If the current surface shares and edge with the original one, the texture is also aligned. Then the current surface is set as the origin for stitching. So you can proceed further to align textures without pressing ";" again.
You should try this - it's really useful.
Stitching might work strange on some surfaces. It happens on surfaces where the texture is flipped. If it happens, try this:
Select the starting surface and press "Straighten texture" key. Then proceed with regular stitching routine.

Consistency Errors

Sooner or later you will run into those. Many of those errors are critical and will prevent your level from working properly, or loading at all. Here's the list of consistency errors JED detects, description of them and suggestions to fix them.

Less than 4 vertices or surfaces
That one is easy. You can't have a valid sector with less that 4 surfaces or vertices. Delete this sector.

Sector is not convex
That's a hard one. Convex sector is such a sector sector so that relative to every surface of it all the other surfaces are in front of it. All sectors must be convex. To fix non-convex sector you either need to move the offending vertices or cleave the sector. For example (top view of prism sector):
+-----+
|     | 
|     +  
+    /
 \  /
  \/
Convex sector.

+-----+
|     | 
|     +  
+      \
 \      \
  \      \
   +------+
Non-convex sector. You would fix it either by moving the edge:
+-----+
|     | 
|     +  
+     | 
 \    | 
  \   |
   +--+

or by cleaving
+-----+
|     |/
|     /  
+    / \
 \  /   \
  \/     \
  /+------+

Often non-convex sector error is caused by surface errors in the sector. Fix surface error and see if it goes away.

More than 24 vertices in a surface
That one is also easy. Surfaces must have less than 24 vertices. Cleave the surface in two (or more).

Less than 3 vertices in a surface
The surface must consist of at least 3 vertices. That's one can be hard. You can try merging the offending surface with another one. Or deleting the sector and recreating it.

Incorrect normal - surface must be invalid
This happens when JED can't calculate a normal for the surface. Usually it's the surface of zero width. Try moving vertices of the surface, or neighbor surfaces so that the surface is not more so thin. Careful as you can instroduce non-planar errors this way.

Invalid reverse adjoin
That means surface's adjoin doesn't refer back to it. It should. Try unadjoining and readjoining the surface. Or enter adjoin info manually.

Adjoined surfaces don't overlap
That means that adjoined surfaces don't have precisely the same number of vertices or don't overlap. They should overlap vertex to vertex. A bug in JED 0.1 through 0.3 caused insertion of extra vertex into a surface, but not its adjoin. This gave this error, while the level was still working fine. It'll be fixed in the next version. You can ignore this error if you see that surfaces seem to overlap (usef Shift+F to switch between surface and its adjoin). You can still fix this error by inserting the missing vertex into face by cleaving an edge.

The face is not planar
That means that not all of surface's vertices lie on the same plane. They should. You can ignore this error if the surface looks planar to you - that means that the deviation from the plane is minimal. To fix this error you will have to move vertices. Snap the grid to face and try to move the vertices with [ and ]. Look out, as by trying to make one face planar you can force another out of plane. The other solution is to cleave the surface to triangles. Use "Snap to Vertex" to draw a cleave line preciese through vertices. To prevent such an error avoid moving vertices/edges/surfaces unless you really have to. Use cleave too instead.

The face is convex
This is basically the same thing as non-convex sector, just in 2 dimensions. Use the same techniques to fix it. Jed 0.3 had a bug in non-convex surface detection so that this error never showed up. Will be fixed in the next version.

Thing not in sector
That means the thing "Sector" filed doesn't refer to any sector. That usually means that thing is out of sector or the sector the thing was in was deleted. If the thing is out of sector, moved it inside one. If it's in sector, select it and press "Shift+A". This will find a sector this thing is in.

Thing is not in specified sector
That means that the thing isn't in the sector that is specified in its "sector" field. Select a thing and press "Shift+A". This could also mean that the sector the thing is allegedly in has an error. If it does, try to fix it and see if it goes away.








That's it for now. If I remember anything else, I'll be sure to add it.