Scripting Core

Constants

Season enum - Contains types of possible seasonal events:
- Season.None - No season
- Season.Valentine - Valentine's Day week
- Season.Birthday - Serious Sam anniversary week
- Season.Halloween - Halloween month
- Season.Christmas - Christmas & New Year holidays
- Season.Anniversary - Classics Patch anniversary week
- Season.Max - Maximum amount of seasons
TestType enum - Contains types of testing that a ray can perform when hitting models:
- TestType.NONE - Ignores models altogether
- TestType.SIMPLE - Tests whether a ray passes through a sphere that approximately covers an entire model
- TestType.COLLISIONBOX - Tests whether a ray passes through the current collision box of a specific model
- TestType.FULL - Tests whether a ray hits any of the model triangles
- TestType.FULLSEETHROUGH - Tests whether a ray hits any of the model triangles but ignoring entities marked with an ENF_SEETHROUGH flag
LineMask enum - Pre-defined pattern types (bit masks) for rendering lines on drawports:
- LineMask.Full - Full line
- LineMask.Symmetric_16 - 16-pixel long dash-dot pattern
- LineMask.Symmetric_32 - 32-pixel long dash-dot pattern
- LineMask.Point - Dotted line
- LineMask.Dot_2 - 2-pixel long dashed line
- LineMask.Dot_4 - 4-pixel long dashed line
- LineMask.Dot_8 - 8-pixel long dashed line
- LineMask.Dot_16 - 16-pixel long dashed line
- LineMask.Pattern_3_1 - 3-pixel long line with 1-pixel long spacing
- LineMask.Pattern_6_2 - 6-pixel long line with 2-pixel long spacing
- LineMask.Pattern_12_4 - 12-pixel long line with 4-pixel long spacing
- LineMask.Pattern_1_3 - 1-pixel long line with 3-pixel long spacing
- LineMask.Pattern_2_6 - 2-pixel long line with 6-pixel long spacing
- LineMask.Pattern_4_12 - 4-pixel long line with 12-pixel long spacing

Classes

CBrushPolygon

Class for representing a polygon of some brush within the current world.

Metamethods

`CBrushPolygon(other = null)`

Sets up a new pointer to a brush polygon.

Arguments:

other (optional) - Another CBrushPolygon to reference with this instance.

Methods

`Equal(other)`

Compares this brush polygon pointer with another brush polygon pointer (or null). A helper method for the lack of the == operator overloading.

Arguments:

other - Another CBrushPolygon to compare this one with.

Return value: bool

`GetPlane()`

Returns plane of the brush polygon. Equivalent to the engine's CBrushPolygon::bpo_pbplPlane->bpl_plAbsolute.

Return value: FLOATplane3D

`GetSurface()`

Returns surface type of the brush polygon. Equivalent to the engine's CBrushPolygon::bpo_bppProperties.bpp_ubSurfaceType.

Return value: integer

`GetDistanceFromEdges(point)`

Returns distance from the specified point to the closest edge of the brush polygon. Equivalent to the engine's CBrushPolygon::GetDistanceFromEdges().

Arguments:

point - FLOAT3D with the absolute position.

Return value: float

CCastRay

Class for casting physical rays within the current world.

Metamethods

`CCastRay(owner, placement, max_distance = INF)`

Sets up a ray from a specific entity to shoot from the specified placement until some maximum distance.

Arguments:

owner - CEntityPointer with the entity that's casting the ray (or null).
placement - CPlacement3D with the placement to shoot the ray from in the direction of the angle.
max_distance (optional) - Maximum distance that the ray can reach in meters.

`CCastRay(owner, source, destination)`

Sets up a ray from a specific entity to shoot from the specified point until another point.

Arguments:

owner - CEntityPointer with the entity that's casting the ray (or null).
source - FLOAT3D with the source point of the ray to shoot from.
destination - FLOAT3D with the destination point of the ray to shoot towards.

Methods

`GetPlacement()`

Returns origin of the ray pointed in the direction of shooting. Equivalent to the engine's CCastRay::cl_plRay.

Return value: CPlacement3D

`GetEntity()`

Returns entity that's shooting the ray (may be none). Equivalent to the engine's CCastRay::cr_penOrigin.

Return value: CEntityPointer

`GetOrigin()`

Returns origin point of the ray. Equivalent to the engine's CCastRay::cr_vOrigin.

Return value: FLOAT3D

`GetTarget()`

Returns target point of the ray. Equivalent to the engine's CCastRay::cr_vTarget.

Return value: FLOAT3D

`GetHitEntity()`

Returns the hit entity after casting a ray (may be none). Equivalent to the engine's CCastRay::cr_penHit.

Return value: CEntityPointer

`GetHitPoint()`

Returns the hit point after casting a ray. Equivalent to the engine's CCastRay::cr_vHit.

Return value: FLOAT3D

`GetHitDistance()`

Returns distance between the ray origin and the hit point after casting a ray. Equivalent to the engine's CCastRay::cr_fHitDistance.

Return value: float

`GetHitPolygon()`

Returns hit brush polygon after casting a ray (may be null). Equivalent to the engine's CCastRay::cr_pbpoBrushPolygon.

Return value: CBrushPolygon

`Cast()`

Casts a ray for the first time within the currenly running world. Equivalent to the engine's CCastRay::Cast().

Return value: null

`ContinueCast()`

Casts a ray again from the last hit point within the currenly running world. Equivalent to the engine's CCastRay::ContinueCast().

Return value: null

Variables

`bHitPortals`

Whether the ray should hit brush polygons marked with the "Portal" flag. Equivalent to the engine's CCastRay::cr_bHitPortals.

Type	Default value	Readable	Writeable
`bool`	`false`	Yes	Yes

`bHitTranslucentPortals`

Whether the ray should hit brush polygons marked that are both visible and can be seen through. Equivalent to the engine's CCastRay::cr_bHitTranslucentPortals.

Type	Default value	Readable	Writeable
`bool`	`true`	Yes	Yes

`bHitFields`

Whether the ray should hit invisible field brushes (e.g. TouchField entities). Equivalent to the engine's CCastRay::cr_bHitFields.

Type	Default value	Readable	Writeable
`bool`	`false`	Yes	Yes

`bHitBrushes`

Whether the ray should hit brushes at all. Equivalent to the engine's CCastRay::cr_bHitBrushes.

Important

This variable is only available starting with The Second Encounter v1.07!

Type	Default value	Readable	Writeable
`bool`	`true`	Yes	Yes

`bHitTerrainInvisibleTris`

Whether the ray should hit invisible terrain polygons. Equivalent to the engine's CCastRay::cr_bHitTerrainInvisibleTris.

Important

This variable is only available starting with The Second Encounter v1.07!

Type	Default value	Readable	Writeable
`bool`	`false`	Yes	Yes

`bPhysical`

Whether the ray is "physical", i.e. can pass where bullets can pass, like brush polygons marked with the "Shoot through" flag. Equivalent to the engine's CCastRay::cr_bPhysical.

Type	Default value	Readable	Writeable
`bool`	`false`	Yes	Yes

`fTestR`

Radius of the ray. Equivalent to the engine's CCastRay::cr_fTestR.

Type	Default value	Readable	Writeable
`float`	`0` (infinitely thin)	Yes	Yes

`ttHitModels`

Type of testing to perform when hitting models. Equivalent to the engine's CCastRay::cr_ttHitModels.

Type	Default value	Readable	Writeable
`integer`	`TestType.SIMPLE`	Yes	Yes

CDrawPort

Class for representing a drawable surface on screen.

Methods

`Equal(other)`

Compares this draw port pointer with another draw port pointer. A helper method for the lack of the == operator overloading.

Arguments:

other - Another CDrawPort to compare this one with.

Return value: bool

`IsDualHead()`

Checks whether the drawport is in dual-head mode (has a resolution in 8:3 aspect ratio).

Return value: bool

`IsWideScreen()`

Checks whether the drawport was created as a "widescreen" one.

Return value: bool

`GetWidth()`

Returns width of the drawport in pixels.

Return value: integer

`GetHeight()`

Returns height of the drawport in pixels.

Return value: integer

`SetFont(font)`

Sets a new font for all text that will be drawn later and resets all font settings below to defaults.

Arguments:

font - CFontData with the new font to set.

Return value: null

`SetTextCharSpacing(spacing)`

Sets new spacing between each character in pixels.

Arguments:

spacing - Amount of pixels to set between each text character.

Return value: null

`SetTextLineSpacing(spacing)`

Sets new spacing between each line in pixels.

Arguments:

spacing - Amount of pixels to set between each text line.

Return value: null

`SetTextScaling(scaling)`

Sets new scale factor for text.

Arguments:

scaling - Text scaling factor to set.

Return value: null

`SetTextAspect(aspect)`

Stretches text horizontally based on the specified factor.

Arguments:

aspect - Horizontal text scaling factor to set.

Return value: null

`SetTextMode(mode)`

Changes text output mode:

-1 - prints decorations as normal text

0 - ignores all decorations

1 - parses and applies all decorations

Arguments:

mode - Text mode to set.

Return value: null

`GetTextWidth(text)`

Calculates width of the specified text in pixels based on the last font setup.

Arguments:

text - String to calculate the width of.

Return value: integer

`PutText(text, x, y, color)`

Draws text of the specified color at the specified coordinates aligned to top left.

Tip

Using color tags such as ^c and ^a in text can override the specified default color.

Arguments:

text - String to draw on screen.
x - Horizontal position to draw the text from in pixels.
y - Vertical position to draw the text from in pixels.
color - Integer with the color value in the 32-bit RGBA format.

Return value: null

`PutTextC(text, x, y, color)`

Draws text of the specified color at the specified coordinates aligned to top center.

Tip

Using color tags such as ^c and ^a in text can override the specified default color.

Arguments:

text - String to draw on screen.
x - Horizontal position to draw the text from in pixels.
y - Vertical position to draw the text from in pixels.
color - Integer with the color value in the 32-bit RGBA format.

Return value: null

`PutTextCXY(text, x, y, color)`

Draws text of the specified color at the specified coordinates aligned to middle center.

Tip

Using color tags such as ^c and ^a in text can override the specified default color.

Arguments:

text - String to draw on screen.
x - Horizontal position to draw the text from in pixels.
y - Vertical position to draw the text from in pixels.
color - Integer with the color value in the 32-bit RGBA format.

Return value: null

`PutTextR(text, x, y, color)`

Draws text of the specified color at the specified coordinates aligned to top right.

Tip

Using color tags such as ^c and ^a in text can override the specified default color.

Arguments:

text - String to draw on screen.
x - Horizontal position to draw the text from in pixels.
y - Vertical position to draw the text from in pixels.
color - Integer with the color value in the 32-bit RGBA format.

Return value: null

`TextFitsInWidth(max_width, text)`

Returns position of the last character of a string that fits in the specified width of pixels from the first argument.

Arguments:

max_width - Maximum width in pixels that the text should fit in.
text - String to fit within maximum width.

Return value: integer

`FormatStringForWidth(max_width, text)`

Formats the string to fit it in the specified width of pixels from the first argument by inserting line breaks after full words at right places.

Arguments:

max_width - Maximum width in pixels to fit the text in.
text - String to format to fit within maximum width.

Return value: string

`PutTexture(texture, xy0, xy1, colors)`

Draws specified texture on the drawport as a rectangle with two points specified as arrays of X,Y coordinates and tinted using either one color for the entire texture or an array of four colors per each corner of the texture.

Arguments:

texture - CTextureObject with the texture to draw.
xy0 - Array with the X,Y coordinates of the top left corner in pixels, e.g. [0, 0].
xy1 - Array with the X,Y coordinates of the bottom right corner in pixels, e.g. [20, 20].
colors - integer value with the color for the entire texture OR array with four integer values with the colors for each corner. All in the 32-bit RGBA format.

Return value: null

`PutTextureUV(texture, xy0, uv0, xy1, uv1, colors)`

Draws specified texture on the drawport as a rectangle with two points specified as arrays of X,Y coordinates and two arrays of UV map coordinates for drawing a part of the texture. The last argument is for tinting the texture using either one color for the entire texture or an array of four colors per each corner of the texture.

Arguments:

texture - CTextureObject with the texture to draw.
xy0 - Array with the X,Y coordinates of the top left corner in pixels, e.g. [0, 0].
uv0 - Array with the U,V coordinates of the top left corner from 0.0 to 1.0, e.g. [0, 0.2].
xy1 - Array with the X,Y coordinates of the bottom right corner in pixels, e.g. [20, 20].
uv1 - Array with the U,V coordinates of the bottom right corner from 0.0 to 1.0, e.g. [0.8, 1].
colors - integer value with the color for the entire texture OR array with four integer values with the colors for each corner. All in the 32-bit RGBA format.

Return value: null

`InitTexture(texture, clamp)`

Sets a new texture to be used when drawing shapes with AddTexture* functions. Needs to be reset using FlushRenderingQueue() after all drawing is done.

Arguments:

texture - CTextureObject with the current texture to set.
clamp - Whether to clamp the edges of the texture instead of repeating it when using UV map values past the 0.0 - 1.0 boundaries. Recommended to disable for tiled textures.

Return value: null

`AddTexture(xy0, xy1, colors)`

Draws texture from the last InitTexture() call on the drawport as a rectangle with two points specified as arrays of X,Y coordinates and tinted using either one color for the entire texture or an array of four colors per each corner of the texture.

Arguments:

xy0 - Array with the X,Y coordinates of the top left corner in pixels, e.g. [0, 0].
xy1 - Array with the X,Y coordinates of the bottom right corner in pixels, e.g. [20, 20].
colors - integer value with the color for the entire texture OR array with four integer values with the colors for each corner. All in the 32-bit RGBA format.

Return value: null

`AddTextureUV(xy0, uv0, xy1, uv1, colors)`

Draws texture from the last InitTexture() call on the drawport as a rectangle with two points specified as arrays of X,Y coordinates and two arrays of UV map coordinates for drawing a part of the texture. The last argument is for tinting the texture using either one color for the entire texture or an array of four colors per each corner of the texture.

Arguments:

xy0 - Array with the X,Y coordinates of the top left corner in pixels, e.g. [0, 0].
uv0 - Array with the U,V coordinates of the top left corner from 0.0 to 1.0, e.g. [0, 0.2].
xy1 - Array with the X,Y coordinates of the bottom right corner in pixels, e.g. [20, 20].
uv1 - Array with the U,V coordinates of the bottom right corner from 0.0 to 1.0, e.g. [0.8, 1].
colors - integer value with the color for the entire texture OR array with four integer values with the colors for each corner. All in the 32-bit RGBA format.

Return value: null

`AddTexture_4points(xy0, uv0, xy1, uv1, xy2, uv2, xy3, uv3, color0, color1, color2, color3)`

Draws texture from the last InitTexture() call on the drawport using 4 arbitrary X,Y points paired with UV map coordinates.

Arguments:

xy0 - Array with the X,Y coordinates of the first point in pixels, e.g. [0, 0].
uv0 - Array with the UV coordinates of the first point from 0.0 to 1.0, e.g. [0, 0.2].
xy1 - Array with the X,Y coordinates of the second point in pixels, e.g. [20, 0].
uv1 - Array with the UV coordinates of the second point from 0.0 to 1.0, e.g. [0.8, 0.2].
xy2 - Array with the X,Y coordinates of the third point in pixels, e.g. [20, 40].
uv2 - Array with the UV coordinates of the third point from 0.0 to 1.0, e.g. [0.8, 1].
xy3 - Array with the X,Y coordinates of the fourth point in pixels, e.g. [0, 40].
uv3 - Array with the UV coordinates of the fourth point from 0.0 to 1.0, e.g. [0, 1].
color0 - Integer with the color value in the 32-bit RGBA format for the first point.
color1 - Integer with the color value in the 32-bit RGBA format for the second point.
color2 - Integer with the color value in the 32-bit RGBA format for the third point.
color3 - Integer with the color value in the 32-bit RGBA format for the fourth point.

Return value: null

`FlushRenderingQueue()`

Wraps up rendering of some texture after setting it up with InitTexture().

Return value: null

`DrawPoint(x, y, radius, color)`

Draws a point at the specified X,Y coordinate of the specified radius and color.

Important

This function is only available starting from The Second Encounter v1.07!

Arguments:

x - X position of the point in pixels.
y - Y position of the point in pixels.
radius - Radius of a centered square point in pixels.
color - Integer with the color value in the 32-bit RGBA format.

Return value: null

`DrawLine(x0, y0, x1, y1, color, line_mask = LineMask.Full)`

Draws a line from point X0,Y0 to point X1,Y1 of the specified color with an optional line mask.

Arguments:

x0 - Starting X position of the line in pixels.
y0 - Starting Y position of the line in pixels.
x1 - Ending X position of the line in pixels.
y1 - Ending Y position of the line in pixels.
color - Integer with the color value in the 32-bit RGBA format.
line_mask (optional) - Line pattern as a bit mask of pixels. A few default patterns are specified in the LineMask enum.

Return value: null

`DrawBorder(x0, y0, x1, y1, color, line_mask = LineMask.Full)`

Draws a rectangle from the top left corner (X0,Y0) to the bottom right corner (X1,Y1) of the specified color with an optional line mask.

Arguments:

x0 - Position of the left edge of the border in pixels.
y0 - Position of the top edge of the border in pixels.
x1 - Position of the right edge of the border in pixels.
y1 - Position of the bottom edge of the border in pixels.
color - Integer with the color value in the 32-bit RGBA format.
line_mask (optional) - Line pattern as a bit mask of pixels. A few default patterns are specified in the LineMask enum.

Return value: null

`Fill(x0, y0, x1, y1, color)`

Fills a section of the drawport from the top left corner (X0,Y0) to the bottom right corner (X1,Y1) of the specified color.

Arguments:

x0 - Position of the left edge of the rectangle in pixels.
y0 - Position of the top edge of the rectangle in pixels.
x1 - Position of the right edge of the rectangle in pixels.
y1 - Position of the bottom edge of the rectangle in pixels.
color - Integer with the color value in the 32-bit RGBA format.

Return value: null

`FillGradient(x0, y0, x1, y1, color_tl, color_tr, color_bl, color_br)`

Fills a section of the drawport from the top left corner (X0,Y0) to the bottom right corner (X1,Y1) with a gradient of colors for each corner.

Arguments:

x0 - Position of the left edge of the rectangle in pixels.
y0 - Position of the top edge of the rectangle in pixels.
x1 - Position of the right edge of the rectangle in pixels.
y1 - Position of the bottom edge of the rectangle in pixels.
color_tl - Integer with the color value in the 32-bit RGBA format for the top left corner.
color_tr - Integer with the color value in the 32-bit RGBA format for the top right corner.
color_bl - Integer with the color value in the 32-bit RGBA format for the bottom left corner.
color_br - Integer with the color value in the 32-bit RGBA format for the bottom right corner.

Return value: null

`FillScreen(color)`

Fills the entire screen with the specified color.

Arguments:

color - Integer with the color value in the 32-bit RGBA format.

Return value: null

CRawDataBuffer

Class for representing a container of raw bytes.

Metamethods

`CRawDataBuffer(bytes)`

Sets up a new data buffer of the specified length in bytes. All bytes are set to 0 by default.

Arguments:

bytes - Amount of bytes that the buffer should contain.

`tostring()`

Returns an array of byte values formatted as %02X within [] separated by spaces, e.g. [01 22 3A FF].

Return value: string

Methods

`Equal(other)`

Compares contents of this data buffer with another data buffer. A helper method for the lack of the == operator overloading.

Arguments:

other - Another CRawDataBuffer to compare this one with.

Return value: bool

`Size()`

Returns length of the data buffer in bytes.

Return value: integer

`Reset()`

Resets all bytes in the data buffer to 0.

`SetByte(offset, value)`

Sets the specified integer value in the buffer starting from the specified offset.
Throws a runtime error if the data doesn't fit within the bounds of the buffer.

Arguments:

offset - Starting position in the buffer to write the value to.
value - Integer value that will be truncated to a single byte.

`SetBool(offset, value)`

Sets the specified boolean value in the buffer starting from the specified offset.
Throws a runtime error if the data doesn't fit within the bounds of the buffer.

Arguments:

offset - Starting position in the buffer to write the value to.
value - Boolean value that will be written as a 32-bit integer (occupying the next 4 bytes).

`SetIndex(offset, value)`

Sets the specified integer value in the buffer starting from the specified offset.
Throws a runtime error if the data doesn't fit within the bounds of the buffer.

Arguments:

offset - Starting position in the buffer to write the value to.
value - Integer value that will be written as a 32-bit integer (occupying the next 4 bytes).

`SetFloat(offset, value)`

Sets the specified float value in the buffer starting from the specified offset.
Throws a runtime error if the data doesn't fit within the bounds of the buffer.

Arguments:

offset - Starting position in the buffer to write the value to.
value - Float value that will be written as a single-precision float (occupying the next 4 bytes).

`SetString(offset, value)`

Copies all characters from the specified string byte-by-byte in the buffer starting from the specified offset. Doesn't include the null terminator at the end. Example: "Hello" will write 5 bytes.
Throws a runtime error if the data doesn't fit within the bounds of the buffer.

Arguments:

offset - Starting position in the buffer to write the value to.
value - String value that will be written byte-by-byte.

`GetByte(offset)`

Retrieves a byte value from the specified offset in the buffer and converts it to a 64-bit integer.

Arguments:

offset - Starting position in the buffer to read the value from.

Return value: integer

`GetBool(offset)`

Retrieves a 32-bit boolean value (4 bytes) from the specified offset in the buffer and converts it to either true or false.

Arguments:

offset - Starting position in the buffer to read the value from.

Return value: bool

`GetIndex(offset)`

Retrieves a 32-bit integer value (4 bytes) from the specified offset in the buffer and converts it to a 64-bit integer.

Arguments:

offset - Starting position in the buffer to read the value from.

Return value: integer

`GetFloat(offset)`

Retrieves a 32-bit float value (4 bytes) from the specified offset in the buffer.

Arguments:

offset - Starting position in the buffer to read the value from.

Return value: float

`GetString(offset, characters)`

Retrieves specified amount of bytes starting from the specified offset and constructs a string with each byte as a character in order. Automatically appends a null terminator at the end.

Arguments:

offset - Starting position in the buffer to read the value from.
characters - Amount of bytes to read as string characters (excluding the null terminator), e.g. 5 for "Hello".

Return value: string

Core.LocalStorage

Class for serializing custom data from scripts in JSON format.

Important

Each method of the local storage class takes a directory-like path to the keys. Each time a / character is encountered, it enters an object with the name prior to it and keeps doing it until the last key, which is supposed to contain the respective value.
Example: "container/inner/my data" key name will resolve to a "my data" key inside "inner" object inside another "container" object inside local storage. Whereas "custom data" key name will resolve to a simple "custom data" key inside local storage.

Metamethods

`LocalStorage(name)`

Loads local storage under the specified name or creates a new one if it doesn't exist yet.

Warning

All local storage configs are shared between any and all scripts. Make sure not to use generic local storage names or the names used by other scripts for serializing their data in order to avoid collision or potential loss of data from other scripts.

Arguments:

name - Name of a local storage to use.

Caution

Local storage names only support alphanumeric characters (0-9, a-z, A-Z), spaces and underscores (_)! Unsupported characters are replaced with underscores, which may lead to collisions with other storages!
Example: my_data, my@data, my.data and my/data will all utilize the exact same local storage (my_data).

`tostring()`

Returns a string with the current contents of the entire storage as a formatted JSON.

Return value: string

Methods

`Save()`

Saves modified contents of local storage to disk. Any subsequent creation of local storage with the same name will access newly saved contents.

Return value: null

`Clear()`

Clears all contents of local storage, resulting in an empty JSON object.

Return value: null

`KeyExists(path)`

Checks whether the specified key exists in local storage.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`DeleteKey(path)`

Deletes the specified key from local storage, if it exists.

Note

This method only deletes the last key in the path. To delete all data under a specific object, end the path at the key name of that object instead of each individual key inside of it.

Arguments:

path - Key name as a directory-like path.

Return value: null

`IsFalse(path)`

Checks whether the specified key has a boolean value and it's equal to false.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsTrue(path)`

Checks whether the specified key has a boolean value and it's equal to true.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsBool(path)`

Checks whether the specified key has a boolean value.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsNull(path)`

Checks whether the specified key has a null value.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsNumber(path)`

Checks whether the specified key has a number value.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsString(path)`

Checks whether the specified key has a string value.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsArray(path)`

Checks whether the specified key has an array value.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsObject(path)`

Checks whether the specified key has an object value.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsVector(path)`

Checks whether the specified key has a vector value, i.e. a JSON value that has the exact syntax of [ number, number, number ].

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsPlane(path)`

Checks whether the specified key has a plane value, i.e. a JSON value that has the exact syntax of [ [ number, number, number ], number ].

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsMatrix(path)`

Checks whether the specified key has a matrix value, i.e. a JSON value that has the exact syntax of [ number, number, number, number, number, number, number, number, number ].

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsAABB(path)`

Checks whether the specified key has an axis-aligned bounding box value, i.e. a JSON value that has the exact syntax of [ number, number, number, number, number, number ].

Arguments:

path - Key name as a directory-like path.

Return value: bool

`IsPlacement(path)`

Checks whether the specified key has a placement value, i.e. a JSON value that has the exact syntax of [ [ number, number, number ], [ number, number, number ] ].

Arguments:

path - Key name as a directory-like path.

Return value: bool

`SetBool(path, value)`

Sets boolean value to the specified key, overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - bool value to set.

Return value: null

`SetNull(path)`

Sets null value to the specified key, overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.

Return value: null

`SetNumber(path, value)`

Sets number value to the specified key, overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - integer or float value to set.

Return value: null

`SetString(path, value)`

Sets string value to the specified key, overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - string value to set.

Return value: null

`SetArray(path, value)`

Sets array value to the specified key, recursively copying all contents from it and overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - array value to set.

Return value: null

`SetObject(path, value)`

Sets object value to the specified key, recursively copying all contents from it and overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - table value to set.

Return value: null

`SetVector(path, value)`

Sets vector value to the specified key as an array of 3 numbers (X, Y, Z; e.g. [1, 2, 3]), overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - FLOAT3D value to set.

Return value: null

`SetPlane(path, value)`

Sets plane value to the specified key as an array of an array and a number (Normal, Distance; e.g. [ [0, 1, 0], 4]), overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - FLOATplane3D value to set.

Return value: null

`SetMatrix(path, value)`

Sets matrix value to the specified key as an array of 9 numbers (e.g. [1, 0, 0, 0, 1, 0, 0, 0, 1]), overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - FLOATmatrix3D value to set.

Return value: null

`SetAABB(path, value)`

Sets axis-aligned bounding box value to the specified key as an array of 6 numbers (X0, Y0, Z0, X1, Y1, Z1; e.g. [-1, -2, -3, 10, 20, 30]), overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - FLOATaabbox3D value to set.

Return value: null

`SetPlacement(path, value)`

Sets placement value to the specified key as an array of 2 arrays of 3 numbers (Position, Rotation; e.g. [[1, 2, 3], [90, 45, 180]]), overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - CPlacement3D value to set.

Return value: null

`SetValue(path, value)`

Sets any supported value to the specified key, overwriting existing data if there's any.
Throws a runtime error if it fails to set the value.

Arguments:

path - Key name as a directory-like path.
value - Value to set that may only be one of the following types:
- bool, null, integer, float, string, array, table, FLOAT3D, FLOATplane3D, FLOATmatrix3D, FLOATaabbox3D, CPlacement3D

Return value: null

`GetBool(path)`

Retrieves a boolean value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain a boolean value.

Arguments:

path - Key name as a directory-like path.

Return value: bool

`GetNull(path)`

Retrieves a null value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain a null value.

Arguments:

path - Key name as a directory-like path.

Return value: null

`GetNumber(path)`

Retrieves a number value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain a number value.

Arguments:

path - Key name as a directory-like path.

Return value: float

`GetString(path)`

Retrieves a string value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain a string value.

Arguments:

path - Key name as a directory-like path.

Return value: string

`GetArray(path)`

Retrieves an array value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain an array value.

Arguments:

path - Key name as a directory-like path.

Return value: array

`GetObject(path)`

Retrieves an object value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain an object value.

Arguments:

path - Key name as a directory-like path.

Return value: table

`GetVector(path)`

Retrieves a vector value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain a vector value (see IsVector function for valid values).

Arguments:

path - Key name as a directory-like path.

Return value: FLOAT3D

`GetPlane(path)`

Retrieves a plane value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain a plane value (see IsPlane function for valid values).

Arguments:

path - Key name as a directory-like path.

Return value: FLOATplane3D

`GetMatrix(path)`

Retrieves a matrix value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain a matrix value (see IsMatrix function for valid values).

Arguments:

path - Key name as a directory-like path.

Return value: FLOATmatrix3D

`GetAABB(path)`

Retrieves an axis-aligned bounding box value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain an AABB value (see IsAABB function for valid values).

Arguments:

path - Key name as a directory-like path.

Return value: FLOATaabbox3D

`GetPlacement(path)`

Retrieves a placement value from the specified key.
Throws a runtime error if the key doesn't exist or doesn't contain a placement value (see IsPlacement function for valid values).

Arguments:

path - Key name as a directory-like path.

Return value: CPlacement3D

`GetValue(path)`

Retrieves any value from the specified key.
Throws a runtime error if the key doesn't exist or contains a value of an unsupported type.

Note

This function does not distinguish between custom types (such as FLOAT3D) and regular JSON values that they are encoded as, resulting in the latter return value instead.

Arguments:

path - Key name as a directory-like path.

Return value: bool/null/float/string/array/table depending on the held value.

`GetBoolDefault(path, default_value)`

Retrieves a boolean value from the specified key.
If the key doesn't exist or doesn't contain a boolean value, returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: bool

`GetNumberDefault(path, default_value)`

Retrieves a number value from the specified key.
If the key doesn't exist or doesn't contain a number value, returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: float

`GetStringDefault(path, default_value)`

Retrieves a string value from the specified key.
If the key doesn't exist or doesn't contain a string value, returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: string

`GetArrayDefault(path, default_value)`

Retrieves an array value from the specified key.
If the key doesn't exist or doesn't contain an array value, returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: array

`GetObjectDefault(path, default_value)`

Retrieves an object value from the specified key.
If the key doesn't exist or doesn't contain an object value, returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: table

`GetVectorDefault(path, default_value)`

Retrieves a vector value from the specified key.
If the key doesn't exist or doesn't contain a vector value (see IsVector function for valid values), returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: FLOAT3D

`GetPlaneDefault(path, default_value)`

Retrieves a plane value from the specified key.
If the key doesn't exist or doesn't contain a plane value (see IsPlane function for valid values), returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: FLOATplane3D

`GetMatrixDefault(path, default_value)`

Retrieves a matrix value from the specified key.
If the key doesn't exist or doesn't contain a matrix value (see IsMatrix function for valid values), returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: FLOATmatrix3D

`GetAABBDefault(path, default_value)`

Retrieves an axis-aligned bounding box value from the specified key.
If the key doesn't exist or doesn't contain an AABB value (see IsAABB function for valid values), returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: FLOATaabbox3D

`GetPlacementDefault(path, default_value)`

Retrieves a placement value from the specified key.
If the key doesn't exist or doesn't contain a placement value (see IsPlacement function for valid values), returns the provided default value instead of throwing an error.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: CPlacement3D

`GetValueDefault(path, default_value)`

Retrieves any value from the specified key.
If the key doesn't exist or contains a value of an unsupported type, returns the provided default value instead of throwing an error.

Note

This function does not distinguish between custom types (such as FLOAT3D) and regular JSON values that they are encoded as, resulting in the latter return value instead.

Arguments:

path - Key name as a directory-like path.
default_value - Default value that will be returned on failure.

Return value: bool/null/float/string/array/table depending on the held value.

Functions

`Core.IsSE105()`

Return value: bool with whether the script is running on 1.05 version of Serious Engine 1.

`Core.IsSE107()`

Return value: bool with whether the script is running on 1.07 version of Serious Engine 1.

`Core.IsTFE()`

Return value: bool with whether the script is being run from The First Encounter game.

`Core.IsTSE()`

Return value: bool with whether the script is being run from The Second Encounter game.

`Core.GetVersion()`

Returns an array of version numbers: release, update, patch. For example, version "1.2.3" would return [1, 2, 3].

Return value: array of integer values with the current version of the patch.

`Core.GetVersionName()`

It may omit the patch version number if it's set to 0 (e.g. 1.10 if the version numbers are 1.10.0) and it may append a special development suffix to it, depending on the build (e.g. 1.10-pre1).

Return value: string with the formatted version of Classics Patch.

`Core.GetInitTime()`

Consistent across all running instances of the game on the same computer, depending on the time they've been started.

Return value: Timer.Value with the precise CPU timestamp of when Classics Patch was initialized.

`Core.IsGame()`

Return value: bool with whether the script is running from a game client.

`Core.IsServer()`

Return value: bool with whether the script is running from a dedicated server application.

`Core.IsEditor()`

Return value: bool with whether the script is running from Serious Editor.

`Core.IsModeler()`

Return value: bool with whether the script is running from a modeler application, e.g. Serious Modeler or Serious SKA Studio.

`Core.GetSeason()`

Return value: integer with the current seasonal event, represented by the Season enum.

`Core.IsCustomModActive()`

Return value: bool with whether Classics Patch is currently running with its own custom mod over vanilla functionality.

`Core.IsEntitiesModded()`

Return value: bool with whether the current used Entities library (e.g. EntitiesMP.dll) is from the currently active mod and not from the base game.

`IncludeScript(path_string)`

This function keeps track of the current script depth and will throw a runtime error if nested scripts go deeper than 16 to avoid a potential stack overflow error.

Arguments:

path_string - Path to another script file to include and evaluate at runtime.

Return value: Return value from the specified script or null if nothing is returned.

`CompileScript(path_string)`

This function does not keep track of the current script depth and may lead to a stack overflow error, if used improperly.

Arguments:

path_string - Path to another script file to compile at runtime.

Return value: function with the compiled script for executing at any point.

String functions

`StringLength(string)`

Returns the amount of printed characters in a string. Equivalent to the engine's CTString::Length() function.

Arguments:

string - String to count the characters in.

Return value: integer with the amount of characters in a string.

`StringLengthNaked(string)`

Returns the amount of printed characters in a string, skipping any decorations (e.g. color tags). Equivalent to the engine's CTString::LengthNaked() function.

Arguments:

string - String to count the characters in.

Return value: integer with the amount of undecorated characters in a string.

`StringUndecorated(string)`

Strips all decorations (e.g. color tags) from the specified string. Equivalent to the engine's CTString::Undecorated() function.

Arguments:

string - String to undecorate.

Return value: string

`StringFindSubstr(string, sub)`

Finds the position of the first occurrence of the specified substring in a string. Equivalent to the engine's CTString::FindSubstr() function.

Arguments:

string - String to go through.
sub - Substring to search for.

Return value: integer of the position with the first occurrence of the substring (-1 if not found).

`StringReplaceSubstr(string, oldsub, newsub)`

Replaces all occurrences of a certain substring with a new substring.

Arguments:

string - String to go through.
oldsub - Old substring to replace.
newsub - String to replace the old substring with.

Return value: string with every old substring replaced with a new substring.

`StringHasPrefix(string, prefix)`

Checks whether a string starts with the specified prefix. Equivalent to the engine's CTString::HasPrefix() function.

Arguments:

string - String to go through.
prefix - Prefix to check for.

Return value: bool with whether the string starts with the specified prefix.

`StringRemovePrefix(string, prefix)`

Removes a prefix from the specified string if it starts with it. Equivalent to the engine's CTString::RemovePrefix() function.

Arguments:

string - String to go through.
prefix - Prefix to check for and remove.

Return value: string of the specified string without the prefix in the beginning, if it was removed.

`StringTrimLeft(string, characters)`

Trims the specified string from the left side to a certain amount of characters. Equivalent to the engine's CTString::TrimLeft() function.

Arguments:

string - String to trim.
characters - Amount of characters to trim the string to.

Return value: array that contains a string with the resulting trimmed string and an integer with the amount of characters that have been trimmed.

`StringTrimRight(string, characters)`

Trims the specified string from the right side to a certain amount of characters. Equivalent to the engine's CTString::TrimRight() function.

Arguments:

string - String to trim.
characters - Amount of characters to trim the string to.

Return value: array that contains a string with the resulting trimmed string and an integer with the amount of characters that have been trimmed.

`StringTrimSpacesLeft(string)`

Removes all leading spaces the specified string from the left side. Equivalent to the engine's CTString::TrimSpacesLeft() function.

Arguments:

string - String to trim.

Return value: array that contains a string with the resulting trimmed string and an integer with the amount of spaces that have been trimmed.

`StringTrimSpacesRight(string)`

Removes all trailing spaces the specified string from the right side. Equivalent to the engine's CTString::TrimSpacesRight() function.

Arguments:

string - String to trim.

Return value: array that contains a string with the resulting trimmed string and an integer with the amount of spaces that have been trimmed.

`StringGetHash(string)`

Calculates a unique hash value based on string contents. Equivalent to the engine's CTString::GetHash() function.

Arguments:

string - String to hash.

Return value: integer with a 32-bit hash value.

`StringOnlyFirstLine(string)`

Erases everything from the specified string after the first occurrence of a line break, otherwise leaves it as is. Equivalent to the engine's CTString::OnlyFirstLine() function.

Arguments:

string - String to process.

Return value: string with only the first line of the specified string.

`StringMatches(string, pattern)`

Matches the specified string with a case-insensitive pattern with wildcards. * symbol matches any 0+ characters and ? matches any one character.

Arguments:

string - String to check.
pattern - String pattern to match the string to.

Return value: bool with whether the string matches the specified pattern.

`StringSplit(string, pos)`

Splits the specified string into two parts at the pos character. Equivalent to the engine's CTString::Split() function.

Arguments:

string - String to split.
pos - Position of the split.

Return value: array with two string values: left part from position 0 up to pos - 1; right part from position pos up to the string length.

`StringInsertChar(string, pos, char)`

Inserts a new character at the specified position in the string. Equivalent to the engine's CTString::InsertChar() function.

Arguments:

string - String to insert the character into.
pos - Position for insertion.
char - Character code to insert (as integer, not string).

Return value: string with the newly inserted character.

`StringDeleteChar(string, pos)`

Deletes a character from the middle of the string. Equivalent to the engine's CTString::DeleteChar() function.

Arguments:

string - String to delete the character from.
pos - Position for deletion.

Return value: string with the specified character deleted.

`StringLoad(path)`

Loads contents of a file as a string. Equivalent to the engine's CTString::Load_t() function.

Arguments:

path - Path to the text file to load the contents of.

Return value: string with the contents of the text file.

`StringSave(string, path)`

Saves contents of the string into a text file. Equivalent to the engine's CTString::Save_t() function.

Arguments:

string - String to save into a file.
path - Path to the text file to save the string into.

Return value: null

`StringReplaceChar(string, oldchar, newchar)`

Replaces all occurrences of the old character with the new one (both as integer, not string).

Arguments:

string - String to replace characters in.
oldchar - Character code to replace.
newchar - Character code to replace the old ones with.

Return value: string with all old characters replaced with new ones.

`StringFindChar(string, char, offset)`

Finds the first occurrence of the specified character (as integer, not string) from some offset in a string.

Arguments:

string - String to go through.
char - Character code to search for.
offset - Offset within the string to start searching from (0 to search from the beginning).

Return value: integer with the position of the first found character (-1 if not found).

`StringCountChar(string, char, offset)`

Counts all occurrences of the specified character (as integer, not string) from some offset in a string.

Arguments:

string - String to go through.
char - Character code to search for.
offset - Offset within the string to start searching from (0 to search from the beginning).

Return value: integer with the amount of characters in the string.

`StringExtractSubstr(string, offset, chars)`

Extracts a part of a string from the specified offset.

Arguments:

string - String to extract from.
offset - Offset to extract a substring from.
chars - Amount of characters to extract (-1 to extract until the end of the string).

Return value: string with the extracted substring.

`StringSeparateByChar(string, separator)`

Separates the string into parts between a specific character. Example: StringSeparateByChar("abc|x|y|", '|') -> ["abc", "x", "y", ""]

Arguments:

string - String to go through.
separator - Character code that separates the string (as integer).

Return value: array of strings between each separator, excluding the separators themselves.

`StringSeparateByString(string, separator)`

Separates the string into parts between a specific character. Example: StringSeparateByString("abc##x##y###", "##") -> ["abc", "x", "y", "#"]

Arguments:

string - String to go through.
separator - Substring that separates the string (as string).

Return value: array of strings between each separator, excluding the separators themselves.

`StringGetDecoratedChar(string, offset)`

Gets the actual index of the printed character in a string after all the decorations (e.g. color tags). Example: StringGetDecoratedChar("^cff0000Hello", 1) -> 9

Arguments:

string - String to go through.
offset - Offset of the printed character to retrieve the actual position of.

Return value: integer with the actual position of the character in the string.

`StringMatchesMask(string, masks)`

Goes through every line in the masks string and matches string until it works, as if using StringMatches().

Arguments:

string - String to match.
masks - List of patterns separated by line breaks to match the string against.

Return value: bool with whether the string matched any pattern in the mask.

`StringFileDir(path)`

Removes all characters after the last found \ character (or everything if none found). Example: dir\\file.ext -> dir\\. Equivalent to the engine's CTFileName::FileDir() function.

Arguments:

path - Path string to get the file directory of.

Return value: string with the directory to the specified file.

`StringFileName(path)`

Removes everything prior to the last found \ character (including it) and everything after the last . character (if found). Example: dir\\file.ext -> file. Equivalent to the engine's CTFileName::FileName() function.

Arguments:

path - Path string to get the file name of.

Return value: string with the name of the specified file.

`StringFileExt(path)`

Removes everything prior to the last found . character (or everything if none found). Example: dir\\file.ext -> .ext. Equivalent to the engine's CTFileName::FileExt() function.

Arguments:

path - Path string to get the file extension of.

Return value: string with the file extension of the specified file, inluding the dot.

`StringNoExt(path)`

Removes everything after the last found . character (if found). Example: dir\\file.ext -> dir\\file. Equivalent to the engine's CTFileName::NoExt() function.

Arguments:

path - Path string to remove the file extension from.

Return value: string with the specified path, excluding the file extension at the end.

`StringRemoveAppPath(path)`

If the path starts with the absolute path to the root directory of the currently running game, it gets removed, otherwise keeps it. Example: C:\\SeriousSam\\MyTextures\\Example.tex -> MyTextures\\Example.tex. Equivalent to the engine's CTFileName::RemoveApplicationPath_t() function.

Arguments:

path - Path string to remove the application path from.

Return value: string without the preceeding application path, if it started with it.