KINETIC WORM DIMENSION V1.10                           Building your own levels
-------------------------------------------------------------------------------
You are encouraged to design and create your own levels for KW. Play them for
yourself, share with your friends or send your work to us and we'll consider
it to be included into the future versions of KW.

[ contents ]

	using external levels with KW
	KW coordinate system
	external level file structure
	how does it work
	build limitations
	sending new levels to ZDG and acceptance terms

[ using external levels with KW ]

	To start KW with the external (user-defined) set of levels, type:

	kw.exe -file <filename>

	where <filename> is any file containing level descriptions.
	Looks pretty much like Doom :) Just don't forget to specify
	the file extension (.txt, .dat, .lev or whatever you prefer).

[ KW coordinate system ]

	KW uses the following 3D coordinate system:
 
	   Z ___________
	    /.         /|
	   / :        / |
	0 /  :     X /  |
	 +----------+   |
	 |   :      | yz|
	 |   :......|...|
	 |  . xy    |  /
	 | .        | /
	Y|__________|/

	In fact, this cubic space is turned around Y axis so that planes
	xy and yz are seen from equal angle, but due to ASCII constrains
	i can't draw them exactly as they are.
	KW doesn't use negative coordinate values, therefore when building
	a scene you should remember that minimum coordinate is 0, and
	define all other coordinates relatively. Don't bother about aligning
	the scene - KW will auto-center it on the screen.

[ external level file structure ]
|
|	External level file is simple ASCII text file, containing keywords
|	and 3D coordinates of surfaces and objects. Keywords can have one
|	or more numeric, character or string parameters, separated by commas
|	or spaces. If string parameter contains spaces, it should be embraced
|	with double quotes (""). You can place one or more keywords on one line,
|	and use any number of spaces or tabs to format the line as you want.
|	The following keyword hierarchy can be used to define a level, or,
|	in KW's terminology, a scene:
|
+------	# <text>
|		any <text> after the "#" is ignored. Used to comment anywhere
|		in line. From now and everywhere, the corner-bracketed words
|		are parameters and should be substituted with real values.
|
+------	scene
	|	starts definition of the new scene and enables scene-specific
	|	keywords.
	|
	+------	name <name>
	|		sets the scene <name> (up to 32 chars). If name
	|		contains spaces, it must be embraced with double
	|		quotes (").
	|
	+------ brief <text>
	|		gives one-string description of a scene. You can
	|		use several brief keywords to define additional
	|		strings. Don't forget to quote text.
	|
	+------	time <time>
	|		sets the <time> seconds given to player to complete
	|		the scene.
	|
	+------ charges <charges>
	|		sets the number of charges needed to activate exit.	
	|
	+------ growth <growth>
	|		sets the <growth> value to be added to the worm's
	|		length for each gained charge.
	|
	+------ music <music>
	|		sets the <music> resource name to be played in the
	|		scene. Available names are:
	|		KW_ACID, KW_WALTZ, KW_BLUES, KW_TECH, KW_MOBIL,
	|		KW_THEME, KW_RAIN, KW_RAVE, KW_SHOGO, KW_END
	|	
	+------	plane <type>, <x>, <y>, <z>, <w>, <h>
	|		defines a single surface.
	|		<type>: xy, yz, or xz (use exactly as shown!).
	|		<x>,<y>,<z>: 3D coordinates of the surface's start
	|			     (local "left-up" corner).
	|		<w>,<h>: local width and height of the surface.
	|
	+------ start <x>,<y>,<dir>
	|		defines worm starting point within current plane.
	|		<x>,<y> are local plane coordinates
	|		<dir> is initial worm direction
	|		      (clockwise 0=up, 1=right, 2=down, 3=left)
	|
	+------	teleport <id>, <x>, <y>, <dest>, <anim>
	|		defines a teleport.
	|		<id>: teleport id, any readable symbol.
	|		<x>,<y>: local coordinates of teleport point within
	|			 current (most recently defined) plane.
	|		<dest>: destination teleport id, any readable symbol.
	|		<anim>: if 0, the teleport isn't animated. Useful for
	|			teleports partially or wholly covered by the
	|			surface (for example, see level "AREA 34").
	|			Any non-zero value will turn animation on.
	|
	+------ vis <x>,<y>
			enables oscilloscope display at specified screen
			location <x>,<y>. Note that <x>,<y> coordinates
			are pixel coordinates, not KW space coordinates.
			KW screen size is 640x480 pixels.
			Oscilloscope size is 128x16 pixels.

	An example of a typical file:
	
		scene	name TEST
		brief	"this is a first line of brief"
		brief	"this is a second line of brief"
		music	KW_ACID
		charges	12 growth 4 time 100
		plane	xy,0,0,0,20,20 start 2,2,1
		plane	xz,0,0,0,20,20
		plane	yz,20,0,0,20,20

		scene	... # beginning of the next scene

	Thus, the file can contain several scenes defined by the "scene"
	blocks, and each scene can contain a number of surfaces defined by the
	"plane" keywords. KW plays all scenes in the order of appearance.

[ how does it work ]

	KW reads file in memory and builds a playable level. The main task	
	that KW engine does, is to determine what surfaces are to be attached
	together, so the worm can pass from one to another. This is done by
	detecting the coincident EDGES of the surfaces. So if you have one
	surface crossed other, they will NOT be attached, even if there's
	visible coincidence. Again, if you have one surface's edge lying
	somewhere on the middle of another surface, they will NOT be attached.
	If you have surface's edge lying somewhere on the other surface's edge,
	they WILL be attached, even if edges have different lengths and
	endpoints.
 
[ build limitations ]

	Presently, there is a limitation of 128 planes and 32 teleports per
	scene. This will be changed in future versions of KW.
	Levels must be convex. Well, that's not a real meaning of the "convex"
	word, that just means you must see all the whole surfaces, they cannot
	overlap or cross even a pixel. If you don't see the surface - don't
	create it. Don't create levels that won't fit into the screen. However,
	if you want to do some tricks, you can play around with the KW space,
	create some weird-attached surfaces etc. and see what will happen...
	Probably nothing good. Anyway, if you manage to do some funny tricks
	or cheats without getting KW crashed - you're welcome!

[ sending new levels to ZDG and acceptance terms ]

	Once you've done some levels, you can send them to us so we can
	consider using them in further versions of KW. We will reply to you
	if your level is accepted. We also MAY reply to you if your level
	is not accepted, but generally we won't. Our main acceptance terms:

	- if you want money, try other things - KW is a freeware, so are levels.
	- levels MUST be sent in a ZIP archive (it would be good if you
	  include some comment or description file).
	- levels without idea are not accepted (you know what we mean).
	- levels that are messing with someone's copyright or federal
	  laws or whatever are not accepted.
	- any levels that are accepted, will be appearing in KW with your
	  name or nick as the author.
	- we can change levels to suit some particular purposes, keeping
	  you as the original author.
	- before you send, give it a try to play.

	address to send the levels to:

	dr_noise@mail.ru
	dr_noise@hotmail.com
