- Documentation
- Game engine
Category
Game engine
All Lua functions and events in the Game engine category, on the server and the client.
Server functions 1
Client functions 82
callCalls a game script command by number and returns the result and variables. Developer mode only; it returnsGame Command falsefor players.createCreates a preview of an element (a vehicle, a player, a ped, an object, a model object) as an image forElement Preview dxDrawImage, e.g. for a car shop or a wardrobe.falseas the target = the scene from the camera. By default the camera orbits the target so that it fits in the frame.createPlaces a model fromMesh Object engineLoadMeshin the world, only for this player: position, rotation and scale. Control the object with thesetMeshObject*functions.destroyRemoves a preview fromElement Preview createElementPreview.destroyRemoves a model object from the world.Mesh Object engineFrees a model fromFree Mesh engineLoadMesh; objects placed from it disappear.engineCreates a COL3 collision from a model fromGenerate COL engineLoadMeshwhen the author did not supply a.colfile. You set the triangle count (QEM simplification keeps the shape), the mode (mesh, convex hull, boxes, sphere) and the surface. Pass the result toengineReplaceCOL.engineReturns data about a collision fromGet COLInfo engineLoadCOL: the version, the name, the number of spheres, boxes, faces and vertices and theboxbounds.engineReturns the list of animations in a loaded IFP block: a table ofGet IFPAnimations { name, duration, bones }(duration in seconds, bone count).engineReturns the model file formatsGet Mesh Formats engineLoadMeshcan load.engineReturns a model's collision box: the minimum and maximum x, y, z relative to the model centre, and finally the radius of the collision sphere. The data comes from the collision loaded by the game, so it works for cars, peds and objects. Useful for placing things on the ground, measuring size and framing the camera.Get Model Bounding Box engineReturns the model flags set withGet Model Flags engineSetModelFlagas a name ->true/falsetable.engineReturns a model's draw distance in metres: set withGet Model LODDistance engineSetModelLODDistanceor from the San Andreas files.engineReturns a model's San Andreas texture names (number or name), also the vehicle wheels. A model that is not loaded is pulled in for a moment. Useful for shaders that replace textures.Get Model Texture Names engineReturns the model's visible hours set withGet Model Visible Time engineSetModelVisibleTime(0 and 24 by default).engineReturns how the bones of a model from a file map to the game skeleton bones: a list ofGet Ped Model Bones { hid, bone, occurrence }. Game animations drive the model through these bones.engineReturns the capacity of a game pool, e.g.Get Pool Capacity "building","ped","object","vehicle","col-model","task". Trilogy Hub enlarges the pools when the game starts.engineReturns the default pool capacity in the Definitive Edition, before Trilogy Hub enlarged it.Get Pool Default Capacity engineReturns how many places in a game pool are used now.Get Pool Used Capacity engineReturns every replaced model: a number -> asset path table.Get Replaced Models engineAssigns textures fromImport TXD engineLoadTXDto a model number.engineLoads a game engine (Unreal) asset by path, e.g. a model or a material from the game files. Pass the handle toLoad Asset engineReplaceModel.engineLoads a collision from a resource file (COLL, COL2, COL3, COL4 formats; from an archive it takes the first model) or from file bytes.Load COL engineLoads a model from a resourceLoad DFF .dfffile (likeengineLoadMesh). It takes textures from a.txdassigned earlier withengineImportTXDfor that number or from a.txdwith the same name. A path other than a.dfffile means an engine asset.engineLoads an IFP animation library (ANPK from Vice City, ANP2/ANP3 from San Andreas) from a file or data under your own block name (preferablyLoad IFP "resource.block"). Play animations withsetPedAnimation(ped, block, animation)or substitute them withengineReplaceAnimation. Stopping the resource frees the block.engineLoads a 3D model from a resource file:Load Mesh .obj,.stl,.ply,.gltf,.glb,.fbx,.3dsand.dfffrom GTA SA (textures from a.txdnext to it). Place the model withcreateMeshObjector put it under a number withengineReplaceModel.engineLoads a resourceLoad TXD .txdfile with textures forengineImportTXDandengineLoadDFF. Another path means a texture as an engine asset.engineMakes a game animation (block and name) play on this ped as an animation from a loaded IFP file. It works only for this player; if it is your own ped, others see the effect in the streamed pose.Replace Animation engineReplaces the image of a game blip icon (number 0-63, e.g. 40) with your own image. The image is a resource file (PNG, JPG, BMP or GIF, listed inReplace Blip Icon meta.xmlas<file>, also:resource/file.png) or image data, e.g. read withfileRead. The new icon shows everywhere the game draws that number: on the radar, on the ESC menu map and in its legend. Blips with that icon keep working the same way (mouse hover, names, ordering). A square image with a transparent background works best; anything larger than 256 px is scaled down. When the resource stops, the game icon comes back.engineReplaces an object model's collision with one fromReplace COL engineLoadCOLorengineGenerateCOL(also for map objects with that number and the day/night pair model). Objects only, not peds and vehicles. If the model does not exist in the game yet (a newengineRequestModelmodel while the player joins or a resource restarts), the collision waits and applies as soon as the model appears; a model number that does not exist givesfalse.engineReplaces the look of a model number: with an engine asset (Replace Model engineLoadAsset) or a model from a file (engineLoadMesh). Objects, vehicles and peds (skins 0-312; a file model without a skeleton is static) with that number show the new model. An object without its own collision gets one from the.dffor from the model triangles;engineReplaceCOLgives a custom collision. It works for this player, so call it in a client script. Replacing a newengineRequestModelmodel that the game has not created yet (the player is just joining, a resource restart) waits for it; a model number that does not exist givesfalse.engineClears all model flags set withReset Model Flags engineSetModelFlag.engineRestores the draw distance of a model's objects set by the game.Reset Model LODDistance engineUndoes animation replacements fromRestore Animation engineReplaceAnimationon a ped: all, one game block's or one animation.engineRestores the game icon afterRestore Blip Icon engineReplaceBlipIcon. Without an argument it restores every icon replaced by this resource.engineRestores a model's original collision.Restore COL engineRestores the original look of a model number.Restore Model engineRestores a model's original textures.Restore TXD engineAnother name forRestream engineRestreamWorld: reloads the world around the player.engineMakes the game reload the world around the player, e.g. after replacing many models.Restream World engineBackground model loading. In the Definitive Edition it is always on (Unreal streaming):Set Asynchronous Loading truechanges nothing,falsereturnsfalsewith a warning.engineSets a model flag (Set Model Flag is_road,draw_last,additive,is_treeand others). In the Definitive Edition Unreal does the drawing, so the flag is only stored (read withengineGetModelFlags) and does not change the image.engineSets from which distance (0-1400 m) objects of this model fromSet Model LODDistance createObjectstop being drawn, also shorter than the default. It changes the model's draw distance in the game (like the San Andreas IDE distance, 40-300 m by default), so editor maps are visible from far away; a distance above 300 m also makes these objects load further away. It does not change map objects (buildings, plants), because they are part of the Unreal levels.engineSets the game hours (0-24) when objects of this model fromSet Model Visible Time createObjectare visible; outside them they are hidden. From > to means across midnight (e.g. 20 and 6 = at night), 0 and 24 = always.engineAlways returnsSet Pool Capacity falsein Trilogy Hub: the game pools are enlarged when the game starts, and their size cannot be changed safely while it runs.engineAsks the game to free streaming memory.Streaming Free Up Memory engineTells whether a model is loaded:Streaming Get Model Load State "loaded","loading"or"notloaded".engineReturns how much memory loaded models use (bytes).Streaming Get Used Memory engineTells the game the model is no longer needed and it may free the memory.Streaming Release Model engineAsks the game to load a model into memory (e.g. before creating many objects at once).Streaming Request Model engineChecks whether a model from a file (a pedValidate Ped Model .dff) works as a skin: bone weights, hierarchy and required bones. Returns the result and a report with errors and warnings, orfalsewhen the model has no skeleton (it will be static).findSearches game engine objects by a name or path fragment and returns a list of hits. Developer mode only; it returnsEngine Object falsefor players.getReturns the path of a shot saved in the persistent preview store byElement Preview Cache setElementPreviewCacheKey. Pass the path todxDrawImageordxCreateTexture. The shot stays between game sessions.getReturns the path of the preview PNG file (forElement Preview Image dxDrawImageanddxCreateTexture) orfalsewhen there is no first shot yet.getReturns the preview state (Element Preview State "czeka"waiting,"gotowy"ready,"czeka na cel"waiting for the target,"blad: ..."error) and the number of shots taken.getReturns what the client knows about the game engine: the version, addresses and reflection readiness. Developer mode only; it returnsEngine Info falsefor players.getReturns data about a model fromMesh Info engineLoadMesh: the format, the number of vertices and triangles and the bounds{ minX, minY, minZ, maxX, maxY, maxZ }in metres.getReturns a model object's colour orMesh Object Color falsewhen it has the default material.getReturns a model object's position.Mesh Object Position getReturns a model object's rotation in degrees.Mesh Object Rotation getReturns a model object's scale on three axes.Mesh Object Scale getReturns the object state in the game:Mesh Object State "czeka"(waiting),"gotowy"(ready) or"blad:..."(error).getReturns the path of the asset put under a model (Model Asset false= original).isChecks whether the blip icon with this number has a custom image fromBlip Icon Replaced engineReplaceBlipIcon.isChecks whether a value is an existing preview fromElement Preview createElementPreview.isChecks whether the client can call game script commands (the base of some functions, e.g.Game Script Available dxDrawModel3DandcreateExplosionon the client).isChecks whether a value is an existing object fromMesh Object createMeshObject.isChecks whether a model object is visible.Mesh Object Visible setThe next preview shot is also saved in the persistent preview store under the given key. The store stays after leaving the game, so next time you can show the image right away withElement Preview Cache Key getElementPreviewCache, without creating a preview. Saving applies to one shot; after it the key is cleared. An empty key turns saving off.setSets a fixed preview camera: the position, the target and the field of view (San Andreas metres).Element Preview Camera setA ped preview shows only what the ped holds in its hand (a weapon), without the body. The camera orbits the item alone, e.g. in a gun shop.Element Preview Held Only setSets a model preview without an element in the world (e.g. a list of cars or skins in a shop): the kind (Element Preview Model "vehicle","ped","object") and the model number. The model only exists for this player, for the shots.setSets a camera orbiting the target: the horizontal angle (Element Preview Orbit yaw, 0 = from the north), the vertical angle (pitch), the distance (0 = the whole target in frame), the height and the field of view.setSets how often in milliseconds the preview takes a new shot (at least 50; 0 = only after a change andElement Preview Refresh updateElementPreview). One shot costs about 10 ms of a frame.setChanges the preview target (an element, a model object orElement Preview Target false= the scene).setGives a model object a solid colour (r, g, b 0-255) with lighting; without a colour the default material comes back.Mesh Object Color setMoves a model object (metres).Mesh Object Position setRotates a model object (degrees, Z, X, Y order).Mesh Object Rotation setScales a model object: with one number or separately on three axes.Mesh Object Scale setPuts a PNG/JPG image from the resource on a model object (by the UV coordinates in the file);Mesh Object Texture falseremoves the image.setShows or hides a model object.Mesh Object Visible updateRequests a new preview shot in the next frame.Element Preview
Shared functions 5
engineFrees a model fromFree Model engineRequestModel. On the server the model is shared: objects, cars and peds using it get the parent model; on the client it frees the local model. A named model keeps its number inmodel-ids.jsonunlessforgetName=true.engineReturns a model number by name. On the server it finds new named models (Get Model IDFrom Name engineRequestModel) and vehicles; on the client also game models by name.engineReturns a model name by number: of a new named model or of a vehicle.Get Model Name From ID engineReturns the parent model of a model fromGet Model Parent engineRequestModel(falseif it is not such a model).engineCreates a new model under a new number, shared by every player (also those who join later). An object (Request Model "object"/"timed-object", parent 1337 by default) gets a number from the 18631-19999 pool and is a copy of the parent;engineReplaceModelandengineReplaceCOLgive it a look and a collision. A vehicle ("vehicle", parent 400), a ped ("ped", parent 7) and a tuning part ("upgrade", parent 1000-1193) get a number 20000-29999 and behave like the parent (seats, sound, handling, tuning), whileengineReplaceModelin a client script gives the look. The third argument is a specific number or a name: the same name always gives the same number (stored in the server'smodel-ids.json), so cars and objects from a database are still that model after a restart, and a named model stays when the resource stops. On the client, the name of a server model returns its shared number. A model requested on the client before the game has loaded its models gets its number at once and is created once loading finishes.