Creates a new section from the given data. The section is loaded asynchronously, and the engine calls the passed specified callback in the given object when all clients have loaded the section.
int CreateSection(any data, string callback, object obj);Either a string, which is the name of the section template (e.g. "Foo" for SectFoo.c4g) to be loaded, or a map describing the Scenario.txt options for the new empty section.
Currently, only the Landscape subkey is supported, with the following properties:
- BottomOpen (bool)
- TopOpen (bool)
- LeftOpen (bool)
- RightOpen (bool)
- AutoScanSideOpen (bool)
- SkyDef (string)
- SkyDefFade (array of six integers)
- NoSky (bool)
- Gravity (C4SVal)
- MapWdt (C4SVal)
- MapHgt (C4SVal)
- MapZoom (C4SVal)
- KeepMapCreator (bool)
- SkyScrollMode (int)
- FoWRes (int)
- ShadeMaterials (bool)
Gravity, MapWdt, MapHgt and MapZoom can be specified as either an array of four integers [Std, Rnd, Min, Max], of which the final value is calculated as BoundBy(Std + Random(2 * Rnd + 1) - Rnd, Min, Max), or as a single integer, which is directly used as the value.
A callback function to be called when the section has finished loading. The callback function receives the new section number as first parameter and whether the section has loaded successfully on all clients as second parameter.
The calback function is always called in the section context from which the call to CreateSection occured; in case that section has been deleted in the meantime, it is called in the first section.
[opt] Object in which the callback should be called. Can be nil in local calls.
The new section's number. Note that the section doesn't exist yet at that time, as it is loaded asynchronously.
func LoadHappySection()
{
CreateSection("Happy", "SectionLoaded");
}
func SectionLoaded(int newSection, bool success)
{
if (!success)
{
Log("No happy section :(");
return;
}
SetObjectContext(nil);
SetSectionContext(newSection);
for (int i = 0; i < 100; ++i)
{
PlaceAnimal(WIPF);
}
}Loads the Happy section from a template and places 100 wipfs in it once it is loaded.
func CreatePrison()
{
CreateSection({
Landscape = {
MapWdt = [100, 3, 50, 200],
MapHgt = 300,
MapZoom = 1,
Gravity = 50
}
}, "GotPrison");
}
func GotPrison(int newSection, bool success)
{
if (!success)
{
Log("No prison");
return;
}
for (var obj in FindObjects(Find_OCF(OCF_CrewMember)))
{
obj->SetPosition(0, 0);
obj->SetSection(newSection);
}
}Creates an empty section with variable width and fixed height and half gravity and moves all crew members into it. They are moved to 0, 0 to ensure they are in the new section's bounds.
Removes the section with the given number. Note that section number 0 cannot be removed.
bool RemoveSection(int section);The section to remove.
true if the section has been successfully removed, false otherwise.
Returns the number of existing sections.
int GetSectionCount();The number of existing sections.
Gets the section by the given index. As section numbers aren't contiguous, this is the only way to iterate over sections.
int GetSectionByIndex(int index);
The number of the section at the given index, or -1 if none exists.
Gets the section of a given object.
int GetSection(object obj);[opt] The object ot get the section from. Can be nil in local calls.
The section of the given object, or nil if none was passed.
Sets the section of a given object. Attached and contained objects are moved with the object they are attached to / contained in.
bool SetSection(int section, object obj);The section to move the object to.
[opt] The object to move. Can be nil in local calls.
true if the section exists, false otherwise.
Gets the section context of the calling function.
int GetSectionContext();The section context of the calling function. If the function executes with an object context, this is equivalent to a call to GetSection().
Sets the section context of the calling function. If the function executes with an object context, calling this function throws an error.
int SetSectionContext(int section);The section to set as new section context.
The old section context, or nil if section does not refer to a valid section.
// a flint that spawns a monster in every section on hit
protected func Hit()
{
var that = this;
SetObjectContext(nil);
for (int i = 0; i < GetSectionCount(); ++i)
{
SetSectionContext(GetSectionByIndex(i));
PlaceAnimal(MONS);
}
SetObjectContext(that);
RemoveObject();
}Sets the object context of the currently executing function. The equivalent getter function is this. This function throws an error if it is called in a global context (= not a definition / object call) or if the defintion of obj isn't equal to the definition of this.
void SetObjectContext(object obj);The new object context to set, or nil.
Adds a section to a background section, creating a parent-child relationship between them where the child section is rendered on top of the parent section.
bool AddBackgroundSection(int section, int backgroundSection, int x, int y, int width, int height);The child section - the section to attach to a background section.
The parent section - the section to which the child section is attached to.
The x coordinate in the background section at which the child section is attached to.
The y coordinate in the background section at which the child section is attached to.
The width of the rectangle in the background section in which the child section is rendered.
The height of the rectangle in the background section in which the child section is rendered.
true if all sections have been found and the bounds don't exceed the background section's bounds.
false if the section already has a different background section as parent than the one specified.
Updates the section's position within the background section.
bool SetSectionPosition(int section, int x, int y);The child section to move.
The new x coordinate in the background section at which the child section should be attached to.
The new y coordinate in the background section at which the child section should be attached to.
true if the section is valid and the bounds don't exceed the parent section's bounds, false otherwise.