Making a Starsiege mission is laborious, repetitive, and error-prone. This is especially true when creating one from scratch. Each team needs a base - including a nav point, one or more pads (with triggers and maybe generators), drop points, and some buildings.
objlib.cs defines functions that make it convenient to write programs to help you create such missions. The idea is to use objlib.cs to create and position most or all of the mission's objects. To see an example of what it can do start the mission editor, select the mission ObjlibTest. Notice it is a mostly empty mission. In fact besides the terrain and other objects every mission must have it contains only one object, NavOmega. Open your console and type
exec("mktest.cs");
The mission should now contain four bases centered on NavOmega;
each one with walls, buildings, nav points, pads, triggers,
generators, and drop points.
Want to rearrange things?
You can alter them by hand in the editor, or you can just
delete the objects, edit mktest.cs and exec() it again.
There is no need to restart the mission editor -
you can run a script, place or move things,
then delete them and try again as many
times as you want before you save the mission.
And if you don't save or the editor crashes, who cares?
All the essentials are encoded in your script.
At some point you'll have done as much as you can or want with your script
and then you can finish the remaining details by hand.
What mktest.cs produces is in fact "ready-to-play"
and was used as-is to create the CTF_Arbeit and DM_Arbeit missions,
no hand tweaking required.
The scripts mkctf.cs, mktdm.cs and mkov.cs create the core objects required for CTF, DM/TDM, and OV (Overrun) missions. These scripts do only part of the job - you'll probably want to reposition and add objects. You can of course also make copies of these scripts to make them into something more complete like mktest.cs.
objsetteam(%t); %t = objgetteam();
objsetteam() specifies the team for all subsequently created objects. 0=neutral, 1=yellow, 2=blue, 3=red, 4=purple. For some reason this setting (made with setTeam()) doesn't stick to many objects, notably StaticShapes and StaticInteriors. If you must set an object's team you can either change it by hand in the mission editor or create the object with lobj(). objgetteam() returns the last value specified.
objsetorigin(%x,%y,%z,%r);
objsetx(%x); %x = objgetx();
objsety(%y); %y = objgety();
objsetz(%z); %z = objgetz();
objsetr(%r); %r = objgetr();
objsetorigin() (and friends) specifies the origin for all subsequently created objects. Objects are created relative to coordinates %x,%y,%z and rotation %r. If %z is -10000 the terrain height at %x,%y is used. %r is in degrees. The objget*() functions return the last value specified.
objsimgroup(%id,%name);
objsimshapegroup(%id,%name);
Creates a SimGroup (or SimShapeGroup) called %name. %id is the object (usually another SimGroup or SimShapeGroup) to put it in. If %id is 0 the new group will be put in MissionGroup.
nobj(%id,%name,%type,%shape,%dx,%dy,%dz,%dr);
Creates an object using newObject(%name,%type,%shape). When %type is StaticShape or StaticInterior you must specify a %shape that ends in ".dts" or ".dis" (respectively) or Starsiege will crash. See objlist.cs for objects that have already been tested. Consult scripts.vol/RegisterObjects.cs for a stock list of objects. (Buzzbumm and S-110 modded this file to expose many additional undocumented objects. Get the mods from AlphaBlue.) For StaticShape and StaticInterior objects (which are mostly buildings and other visible structures) the %dx, %dy, %dz, and %dr values set the position and rotation of the object relative to the values passed to objorigin(). Not every object can be created using nobj(). For some (eg. SimDropPoint) the proper parameters for newObject() are not known. For still others (eg. ESNavMarker) there are certain critical properties (like Team) that can't be set programmatically. In either case you can use lobj() to load a pre-built object from a file.
lobj(%id,%name,%type,%shape,%dx,%dy,%dz,%dr);
Creates an object using loadObject(%name,"obj/obj_"@%type@".dat"). Of course the object file must have been previously created with svobj() or storeObject(). Several common objects (eg. ESNavMarkers and SimTriggers) are included with this package. If necessary you can create your own and save them in the obj folder. Many times you'll need to use do this for objects that require special values for their Short Name or Script Class. Note: Not all object properties are preserved when you storeObject() and then loadObject(). In these cases the only choice is to edit the objects afterward by hand.
svobj(%id,%type);
Use the editor to create an object with any properties you desire, then save it with this command for later use by lobj(). The object data file is called "obj_"@%type@".dat" and is created in your top-level Starsiege folder. You have to move it to the obj folder for lobj() to be able to use it. Move such files before you restart the editor, otherwise they'll be automatically deleted. You must exec("objlib.cs"); before you use this function.
objdpgroup();
objdp(%dpgid,%k,%dx,%dy,%dz,%dr);
objdpline(%dpgid,%n,%g,%dx,%dy,%dz,%dr);
objdpbox(%dpgid,%nc,%nr,%gc,%gr,%dx,%dy,%dz,%dr);
objdpcircle(%dpgid,%n,%rad,%dx,%dy,%dz,%dr);
objdpgroup() creates an ESDropPointGroup called MissionGroup/DropPointGroupT, where T is the last team specified with objsetteam(). T is "" (for Deathmatch drop points) if the team is 0 (neutral). objdp() creates a single drop point. objdpline() creates %n drop points arranged in a line. objdpbox() creates %nc columns and %nr rows of drop points spaced %gc and %gr meters apart. objdpcircle() creates %n inward-facing drop points arranged in a circle of radius %rad.
objverbosity(%v);
Specifies how much output to send to the console. 0 means only error messages, 1 will show each object that's created. The default is 0.
objsetlogfn(%fn); objgetlogfn();
objsetlogfn() specifies that all output should be saved to %fn. It will overwrite whatever %fn already contains. Note: if %fn is not in the Starsiege folder top-level or multiplayer folder it will not work and the engine could crash.
objgetteamsym();
objgetteambase();
objgetteamcolor();
These functions return a value that depends on the last team specified with objsetteam(). For example, for team 1 objgetteamsym() returns *IDSTR_TEAM_YELLOW, objgetteambase() returns "yellowBase", and objgetteamcolor() returns "Yellow".