CreateObject: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
 
(46 intermediate revisions by 22 users not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__  
Creates any GTASA world object at a specified location using x,y,z. The object rotation can also be set with the optional arguments rx, ry, rz.
{{Server client function}}
Creates an [[object]] [[element]] at a given position and rotation.
{{ObjectInfo}}
{{Note|Dynamic objects do not automatically have physics applied to them. Use [[setElementVelocity]](object, 0, 0, 0) to fix this.}}


==Syntax==  
==Syntax==
<syntaxhighlight lang="lua">createObject ( id, x, y, z, [rx, ry, rz] )</syntaxhighlight>  
<syntaxhighlight lang="lua">object createObject ( int modelId, float x, float y, float z, [ float rx, float ry, float rz, bool isLowLOD = false ] )</syntaxhighlight>  
{{OOP||[[Object]]||}}


===Required Arguments===  
===Required Arguments===
*'''ID:''' A Whole integer specifying the GTASA 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 Float value that specifies the X coordinate to spawn the object in the GTASA world
*'''x:''' A floating point number representing the X coordinate on the map.
*'''Y:''' A Float value Specifies the Y coordinate to spawn the object in the GTASA world
*'''y:''' A floating point number representing the Y coordinate on the map.
*'''Z:''' A Float value Specifies the Z coordinate to spawn the object in the GTASA world
*'''z:''' A floating point number representing the Z coordinate on the map.


===Optional Arguments===  
===Optional Arguments===
{{OptionalArg}}  
{{OptionalArg}}  
*'''rx:''' explaination Specifies the created objects X rotation
*'''rx:''' A floating point number representing the rotation about the X axis in degrees.
*'''ry:''' explaination Specifies the created objects Y rotation
*'''ry:''' A floating point number representing the rotation about the Y axis in degrees.
*'''rz:''' explaination Specifies the created objects Z rotation
*'''rz:''' A floating point number representing the rotation about the Z axis in degrees.
{{New items|3.0120|1.2|
*'''isLowLOD:''' A bool value specifying if the object will be low LOD. A low LOD object has no collision and a longer draw distance. See [[setLowLODElement]] for linking a LOD object.
}}


==Example==  
===Returns===
Explain what the example does here
* Returns the [[object]] element if the creation was successful, ''false'' otherwise.
<syntaxhighlight lang="lua">root = getRootElement ()
 
addEventHandler ( "onMapLoad", root, "onMapLoad" )
==Example==
function onMapLoad ( name, root )
{{ExampleCreateObjectOrBuilding}}
createObject ( 5540.6654, 1020.55122, 1240.545, 15, 10, 4.4, 6.2] )
<section name="Server-only Example 1" class="server" show="true">
end</syntaxhighlight>
This example creates an object when the resource starts:
<syntaxhighlight lang="lua">
function loadMapObjects()
  -- create an object at a specified position with a specified rotation
  createObject(1337, 5540.6654, 1020.55122, 1240.545, 90, 0, 0)
end
addEventHandler("onResourceStart", resourceRoot, loadMapObjects)
</syntaxhighlight>
</section>
 
<section name="Server-only Example 2" class="server" show="true">
This example creates an object near the player who write /createObject in the chat:
<syntaxhighlight lang="lua">
-- this function is called whenever someone types 'createObject' in the console:
function createObjectCommand(thePlayer, commandName)
  if (thePlayer) then
      local x, y, z = getElementPosition(thePlayer)
      -- create a object next to the player:
      local theObject = createObject(980, x + 2, y + 2, z, 0, 0, 0)
      if (theObject) then -- check if the object was created successfully
        outputChatBox("Object created successfully.", thePlayer)
      else
        outputChatBox("Failed to create the object.", thePlayer)
      end
  end
end
addCommandHandler("createobject", createObjectCommand)
</syntaxhighlight>
</section>
 
==See Also==
===Object functions===
{{Object functions}}
===Building functions===
{{Building functions}}
===Client world functions===
{{Client_world_functions}}

Latest revision as of 13:15, 23 October 2024

Creates an object element at a given position and rotation.

Dialog-warning.svg Important info about Objects

  • Objects only represent models created by a script, they do not represent objects that are part of GTA's default landscape (these belong to the "building pool").
  • There is a distinction in GTA: San Andreas between static and dynamic models. The alternative createBuilding function allows you to create objects that are non-dynamic.
  • The createObject function can also create non-dynamic objects, but for optimization reasons it is recommended to spawn Buildings when creating static objects that don't rely on the Dimension system (buildings don't use the same MTA object-streaming system).
[[{{{image}}}|link=|]] Note: Dynamic objects do not automatically have physics applied to them. Use setElementVelocity(object, 0, 0, 0) to fix this.

Syntax

object createObject ( int modelId, float x, float y, float z, [ float rx, float ry, float rz, bool isLowLOD = false ] )

OOP Syntax Help! I don't understand this!

Method: Object(...)


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.
  • isLowLOD: A bool value specifying if the object will be low LOD. A low LOD object has no collision and a longer draw distance. See setLowLODElement for linking a LOD object.

Returns

  • Returns the object element if the creation was successful, false 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 [-]
Server-only Example 1

This example creates an object when the resource starts: 

function loadMapObjects()
   -- create an object at a specified position with a specified rotation
   createObject(1337, 5540.6654, 1020.55122, 1240.545, 90, 0, 0)
end
addEventHandler("onResourceStart", resourceRoot, loadMapObjects)
Click to collapse [-]
Server-only Example 2

This example creates an object near the player who write /createObject in the chat: 

-- this function is called whenever someone types 'createObject' in the console:
function createObjectCommand(thePlayer, commandName)
   if (thePlayer) then
      local x, y, z = getElementPosition(thePlayer)
      -- create a object next to the player:
      local theObject = createObject(980, x + 2, y + 2, z, 0, 0, 0)
      if (theObject) then -- check if the object was created successfully
         outputChatBox("Object created successfully.", thePlayer)
      else
         outputChatBox("Failed to create the object.", thePlayer)
      end
   end
end
addCommandHandler("createobject", createObjectCommand)

See Also

Object functions


Building functions


Client world functions



Retrieved from "https://wiki.multitheftauto.com/wiki/CreateObject?oldid=80893"