Welcome to the SparkEdit 3D Scene Editor!!

Mission Goal
How to Install
How to Start
Plugins
Recompiling
Known bugs, problems

1. Mission Goal

I release the editor with full source here with the hope, that it will help many programmers who start writing their own engines and don't have time to implement an editor.
It should help getting started.
The file format is very easy and can be edited with a normal editor to try new feature of your own engine very quickly.

Also I hope that some people help me improving the editor, so that it gets better and better, maybe something of a small standard for getting started.
Just send me your changes and I will incorporate them in the next update for everyone to share. You will of course be fully credited.

I would really appreciate it, if also a collection of scenes / levels could be established on this page. I will also put up more and more of my own test-levels.
Maybe we get a nice collection of scenes and textures for everyone to download. I would really like that, because I know by myself how annoying it is to have a nice 3d-engine but no level or nice textures to run it with.

Please: If you downloaded the program and finally say: "No, that is not what I was looking for...", please tell me why.

2. How to Install

Just untar the file in an arbitrary directory. The directory structure should be kept as in the archive.
On Linux/Unix platforms type "tar xvfz [filename]" to do so. On Windows use WinZip or a similar tool ;-)

The editor is precompiled for i386 Linux ("editor"). I have tested it under SuSE 7.1, but I think it should run on any other Linux system also.

You don't need the GUI-library for starting the editor.

3. How to Start

Just start the executable. The program looks for a file editor.conf in the directoy where it was started to read the configuration (e.g. path to textures).

Here is a quick command overview:

Don`t forget the context-menu! Click right in the view-windows. It has the most important features!

Add a surface by

Context-menu -> "Add Surface"

Select a surface

Change editor mode in context-menu -> "Select surface". Then click on the surfaces (add new ones with ctrl-button or select regions with left mouse-button+drag)

Select a vertex

Change editor mode in context-menu -> "Select vertex", then click on the vertices (hold ctrl down to add more).

Select a light

Select the light like selecting a vertex.

Enhance a selection

by holding the ctrl-key down while selecting another item. You can only select objects from the active section.

Leave a selection

by clicking somewhere else (edtior mode must be "select vertex" or "select surface".

Move a polygon, vertex or selection

Change editor mode (context-menu) to "Modify Selection". Then drag while pressing the left mouse button. To drag in z-direction, you have to press the shift key!! Have a look at all 2D-windows at once to get the way, things are moved!! (The 3D-movement is independent of the window in which you drag the mouse!)

Assign a texture to a polygon

by selectiong one or more polygons and then click onto a texture in the texture-window. You will see the name of the texture also be printed in the console.

Assign mapping-coordinates

A texture for each selected surface has to be assigned first. Then choose a view (a 2D or 3D-window) where you call the context-menu and choose "Assign Mapping". The min/max values are used to scale the selected surface onto the texture. Have a look at the texture window. You can manipulate the coordinates by hand there, too. Drag vertices with the mouse or choose functions from under the texture to modify all coordinates.

Delete a selection (only polygons and lights)

by choosing delete from the context menu (right mouse button).

Add a light

by choosing "add light" from the context menu.

Mirror a polygon (change orientation)

by using "mirror" from the context menu.

Dublicate a selection

Context menu: "Duplicate selection"

Change view:

Editor mode must be (context-menu): "Move Eye" Then drag the mouse while pressing the left or middle mouse-button. For movement in z-direction press the shift-key. shift+right mouse-button zooms in and out (drag the mouse in x-direction)

Reset view:

context menu. "Reset view"

Add a new section

section-browser: click on button to create an empty section

Make section active

click on section-line in the section-browser; it is highlighted then and drawn in a different colour

Move a selection into another section

Make the selection, then click on the destination selection in the browser. Answer the question in the popup-window with yes. The selection will be deleted in the source section.

Show / hide a section

Right-click on the section in the browser, then choose "toggle display".

Delete a section

Right-click on the section in the browser, then choose "delete".

Rename a section

Right-click on the section in the browser, then choose "Change name". Or double-click on a section-line in the browser.

Add a portal

Select a surface, then right-click to get the context-menu, select "type -> portal" and choose the section you want the portal to lead to. Note: When a portal-surface is moved into another section, the portalinformation is deleted: it is just a normal surface afterwards.

Delete a portal

Just delete the surface.

Import 3DS-MAX ASCII, LWO, DXF, MD3-files

Just load the files with the appropriate ending! Look at the plugins-configuration on startup or in editor.conf. (and read section 4 in this file)

Use the buttons on the small editor-window!!

Animations

There is a window representing the animation-frames. Modify the matrices for every frame of every section there. But you can only select things if the data is not modified there (this is a bug). So start the animation with the second frame. This animation data ist ONLY stored in the .ska-files!! Not in the .mesh!! But the mesh-data is ONLY stored in the .mesh-files!! This way you can have ONE mesh for multiple animations in different files.
To load an animation, you first have to load the .mesh-file and the .ska-file afterwards!!

4. Plugins & Fileformats

The sources for the plugins are in the "plugins/" subdirectory. Which plugin for loading/saving is used is determined by the entries in the editor.conf-file. See details there.
The entry looks like:

import (".scene", "plugins/import_scene.so", load) import (".ska", "plugins/import_ska.so", modify) export (".sec", "plugins/export_sec.so", none)

First we say, if it is a plugin for loading or saving. Then we associate the plugin with a file-extension and give the filename of the plugin. The last parameter tell the editor, if previously loaded data in the editor is replaced or just modified by the plugin.

So if you save files, the data written into the file is determined by the extension of the filename!
A list of all available plugins is printed during startup of the editor.

5. Recompiling

The Linux port was compiled with egcs-2.95.2 but I think any gcc will do. Just rename Makefile.Linux in Makefile and type "make" or type "make -f Makefile.Linux". It should compile without a warning.
Remember to have installed the GUI-library fltk. It is available for Linux and Windows, so recompiling under Windows should be no problem. The Makefile is very easy.
With the given Makefile it compiles without warning (-Wall) on my machine.

6. Known Bugs

Many :-)
Sometimes, selecting things is inaccurate. Selection only works in unanimated data.

Have fun!
Christian Fleischer, January 2002

daydream@cs.tu-berlin.de