CreateBuilding

ADDED/UPDATED IN VERSION 1.6.0 r22410:

Creates a building element at a given position and rotation.

Important info about Buildings

• There is a distinction in GTA: San Andreas between static and dynamic models (these use a separate streaming system). Examples of buildings include building models, roads, and terrain. Objects created as Buildings can contain glass and shadows, unlike those created as Objects (which are missing these features).

• Buildings cannot be created with dynamic object model IDs (like a door that opens when you push it), they are meant to be used for static objects, mainly buildings as the name suggests. For example, object ID 1502 (Gen_doorINT04) is a dynamic object model, which can only be spawned using createObject. On the other hand, object ID 3556 (compmedhos3_LAe) is a static object model, which should be created with createBuilding.

• Using buildings for mapping is more optimized than using objects. Gains in FPS can be noticed in areas where a lot of objects were replaced with buildings of this new system.

• Buildings can only be created inside regular GTA:SA Map Boundaries (X between -3000 and 3000; Y between -3000 and 3000). Use createObject to spawn objects outside these normal limits. This limitation is probably going to stop existing in the near future.

• Created buildings can have LOD models. The procedure is as follows: spawn the LOD building using createBuilding, then use setLowLODElement to associate it with the non-LOD building element you created beforehand. LOD model distance changed with engineSetModelLODDistance works for buildings.

• Buildings cannot appear in certain a dimension, and not show in others. Function setElementDimension returns false on any building. A building is created in a specific interior world (such as 0, the main world), like the default GTA:SA landscape objects. All buildings appear in EVERY DIMENSION.

Syntax

building createBuilding ( int modelId, float x, float y, float z [, float rx, float ry, float rz, int interior = 0 ] )

OOP Syntax Help! I don't understand this!

Method: Building(...)

Required Arguments

• modelId: A whole integer specifying the GTA:SA object model ID.
• x: A floating point number representing the X coordinate on the map.
• y: A floating point number representing the Y coordinate on the map.
• z: A floating point number representing the Z coordinate on the map.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.

• rx: A floating point number representing the rotation about the X axis in degrees.
• ry: A floating point number representing the rotation about the Y axis in degrees.
• rz: A floating point number representing the rotation about the Z axis in degrees.
• interior: The interior you want to set the building to. Valid values are 0 to 255.

Returns

• Returns the building element if the creation was successful, throws an error otherwise.

Example

Click to collapse [-]

How to automatically perform object/building creation

This example shows you how to easily verify if any object model ID is non-dynamic, so it can be used with the createBuilding function, as long as it's outside within the map boundaries:

function createObjectOrBuilding(modelID, x, y, z, rx, ry, rz, interior, dimension)
    -- Dynamic object models will always have a physical properties group different than -1.
    local isNonDynamic = engineGetModelPhysicalPropertiesGroup(modelID) == -1
    -- Buildings can't be placed outside dimension 0
    local isNormalDimension = dimension == 0
    -- Buildings can't be placed outside regular map boundaries
    local isInsideMapLimits = x >= -3000 and x <= 3000 and y >= -3000 and y <= 3000

    if isNonDynamic and isNormalDimension  and isInsideMapLimits then
      createBuilding(modelID, x, y, z, rx, ry, rz, interior)
    else
      local obj = createObject(modelID, x, y, z, rx, ry, rz, false)
      setElementInterior(obj, interior)
      setElementDimension(obj, dimension)
    end
end

-- This would be your object's model ID
local modelID = 3556
-- This would be your object's position coordinates
local x, y, z = 0, 0, 69
-- This would be your object's rotation coordinates
local rx, ry, rz = 0, 0, 90
-- This would be your object's interior ID
local interior = 0
-- This would be your object's dimension ID
local dimension = 0

local element = createObjectOrBuilding(modelID, x, y, z, rx, ry, rz, interior, dimension)

-- OPTIONAL: Then you can apply additional properties, like so:
if getElementType(element) == "object" then
    setObjectScale(element, 1.69)
    setObjectBreakable(object, false)
end
setElementAlpha(element, 255)
setElementCollisionsEnabled(element, true)
setElementFrozen(element, false)

Click to collapse [-]

Simple example

This example creates a building when the resource starts:

function loadMap()
   -- create a *building* at a specified position with a specified rotation
   createBuilding(4550, 1985, -2544, 94, 0,0,0) -- Maze Bank Tower in LS airport
end
addEventHandler("onClientResourceStart", resourceRoot, loadMap, false)

See Also

ADDED/UPDATED IN VERSION 1.6.0 r22410:
createBuilding