CreateBuilding: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (add note about map limits (-3000 3000))
No edit summary
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__  
{{Client function}}
{{Client function}}
{{New feature/item|3.0161|1.6.0|22410|Creates a [[building]] [[element]] at a given position and rotation.}}
{{New feature/item|3.0161|1.6.0|22410|Creates a [[building]] [[element]] at a given position & interior with a certain rotation.}}
{{Note|Access the [[Building]] page to read more about how this feature works. '''Buildings support LOD models.'''}}
{{Note|Some [[Object|objects]]/[[Building|buildings]] in '''interior 13''' show in all interiors.}}
{{Note|This function can only create [[building|Buildings]] inside the regular GTA:SA map limits (X between -3000 and 3000; Y between -3000 and 3000). Use [[createObject]] to spawn objects outside the normal map boundaries.}}
{{Note|Unlike [[createObject]], this function does not have an '''isLowLOD''' argument. When using [[setLowLODElement]], the system will automatically define the building as a LOD.}}
{{Note|This function expects valid non-dynamic object model IDs. Check the examples below to understand how to validate the model ID before calling the function. Use [[createObject]] to spawn dynamic objects.}}
{{BuildingInfo}}


==Syntax==
==Syntax==
Line 11: Line 11:


===Required Arguments===
===Required Arguments===
*'''modelId:''' A whole integer specifying the GTA:SA object model ID.
*'''modelId:''' A whole integer specifying the GTA:SA object model ID. See [[Object_IDs|Object IDs]] for a list of model IDs.
*'''x:''' A floating point number representing the X coordinate on the map.
*'''x:''' A floating point number representing the X coordinate on the map.
*'''y:''' A floating point number representing the Y coordinate on the map.
*'''y:''' A floating point number representing the Y coordinate on the map.
Line 28: Line 28:


==Example==
==Example==
<section name="Validate building model ID" class="client" show="true">
{{ExampleCreateObjectOrBuilding}}
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:
<syntaxhighlight lang="lua">
-- Dynamic object models will always have a physical properties group different than -1.
local isNonDynamic = ( engineGetModelPhysicalPropertiesGroup(modelID) == -1 )
if isNonDynamic then
  -- createBuilding
else
  -- createObject
end
</syntaxhighlight>
</section>
<section name="Simple example" class="client" show="true">
<section name="Simple example" class="client" show="true">
This example creates a building when the resource starts:
This example creates a building when the resource starts:
Line 47: Line 36:
   createBuilding(4550, 1985, -2544, 94, 0,0,0) -- Maze Bank Tower in LS airport
   createBuilding(4550, 1985, -2544, 94, 0,0,0) -- Maze Bank Tower in LS airport
end
end
addEventHandler("onClientResourceStart", resourceRoot, loadMap)
addEventHandler("onClientResourceStart", resourceRoot, loadMap, false)
</syntaxhighlight>
</syntaxhighlight>
</section>
</section>


==See Also==
==See Also==
===Building functions===
{{Building functions}}
{{Building functions}}
===Object functions===
{{Object functions}}
===Client world functions===
{{Client_world_functions}}

Latest revision as of 13:14, 23 October 2024

ADDED/UPDATED IN VERSION 1.6.0 r22410:
Creates a building element at a given position & interior with a certain rotation.
[[{{{image}}}|link=|]] Note: Some objects/buildings in interior 13 show in all interiors.
[[{{{image}}}|link=|]] Note: Unlike createObject, this function does not have an isLowLOD argument. When using setLowLODElement, the system will automatically define the building as a LOD.

Dialog-warning.svg 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).
  • 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. See Object IDs for a list of model IDs.
  • 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 automatically create an object or building element according to certain parameters.

This script onlys works CLIENTSIDE due to createBuilding and engineGetModelPhysicalPropertiesGroup. 

-- Creates an 'object' or 'building' element based on certain parameters or one of the functions fails
-- This function will throw an error when unexpected arguments are used
-- TODO: Add LOD support
function createObjectOrBuilding(modelID, x, y, z, rx, ry, rz, interior, dimension)
    -- Validate the arguments passed
    assert(type(modelID)=="number", "invalid modelID passed: " .. tostring(modelID))
    assert(type(x)=="number" and type(y)== "number" and type(z)=="number", "invalid position passed: " .. tostring(x) .. ", " .. tostring(y) .. ", " .. tostring(z))
    if not rx then rx = 0 end
    if not ry then ry = 0 end
    if not rz then rz = 0 end
    assert(type(rx)=="number" and type(ry)== "number" and type(rz)=="number", "invalid rotation passed: " .. tostring(rx) .. ", " .. tostring(ry) .. ", " .. tostring(rz))
    if not interior then interior = 0 end
    if not dimension then dimension = 0 end
    assert(type(interior)=="number" and interior >= 0 and interior <= 255, "invalid interior (must be 0-255) passed: " .. tostring(interior))
    assert(type(dimension)=="number" and dimension >= -1 and dimension <= 65535, "invalid dimension passed (must be -1 65535): " .. tostring(dimension))

    -- Dynamic object models will always have a physical properties group different than -1.
    local isNonDynamic = engineGetModelPhysicalPropertiesGroup(modelID) == -1
    -- Buildings can't be affected by dimension
    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

    local obj, bld
    if isNonDynamic and isNormalDimension and isInsideMapLimits then
        bld = createBuilding(modelID, x, y, z, rx, ry, rz, interior)
        assert(bld, ("Failed to create building with model ID %d at %f, %f, %f in interior %d"):format(modelID, x, y, z, interior))
    else
        obj = createObject(modelID, x, y, z, rx, ry, rz, false)
        assert(obj, ("Failed to create object with model ID %d at %f, %f, %f"):format(modelID, x, y, z))
        setElementInterior(obj, interior)
        setElementDimension(obj, dimension)
    end
    return obj or bld
end

-- Test this create object/building function
addCommandHandler("testobject", function()
    -- 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

    -- We use pcall to catch any errors that may be thrown
    local success, element = pcall(createObjectOrBuilding, modelID, x, y, z, rx, ry, rz, interior, dimension)
    if not success then
        outputDebugString(("Failed to create object or building: %s"):format(tostring(element)), 4, 255, 25, 25)
        return
    end

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

Building functions


Object functions


Client world functions



Retrieved from "https://wiki.multitheftauto.com/wiki/CreateBuilding?oldid=80892"