- Documentation
- Miscellaneous
Category
Miscellaneous
All Lua functions and events in the Miscellaneous category, on the server and the client.
Server functions 39
addAttaches a function to events or function calls, for tracing and profiling.Debug Hook preEventandpostEventwork for events,preFunctionandpostFunctionfor the functions in a name list (the list is required then). ApreEventorpreFunctionfunction can return"skip"to block the event or the call.clearRemoves the visibility limits set withElement Visible To setElementVisibleTo, so everyone sees the element again.createCreates a rectangular radar area (e.g. a gang turf) in an RGBA colour. The area exists on the server: it has a colour, a size, flashing andRadar Area isInsideRadarArea, but the current client version does not draw it on the radar yet.derefReturns the value stored byrefunder a number.getReturns the reason given inCancel Reason cancelEvent(true, reason)by the last event cancellation, e.g. the reason for rejecting a connection inonPlayerConnect.getReturns the LOD object assigned withLow LODElement setLowLODElement.getReturns network statistics for the server or one player: bytes and packets sent and received. The packet loss and buffer fields are zeros for now.Network Stats getReturns the radar area colour.Radar Area Color getReturns the radar area width and height.Radar Area Size getReturns how much player synchronisation has cost since the last call: the number of cycles (Sync Cost ticks), the average and longest cycle time in ms (avgMs,maxMs), states per cycle (statesPerTick) and the measured time (seconds). Helps to find server hitches.getTells what kind a handle is:Userdata Type element,lua-timer,resource-data,xml-node,text-displayand others.isChecks whether a point (x, y) lies inside the radar area.Inside Radar Area isChecks whether the resource has the object syntax (OOPEnabled <oop>true</oop>, e.g.player:getName()). In Trilogy Hub it always returnsfalse; use functions (getPlayerName(player)).isChecks whether the radar area is flashing.Radar Area Flashing passwordCreates a secure password hash (scrypt; the result starts withHash $scrypt$) to store in a database instead of the password. The same text gives a different hash every time; check it withpasswordVerify. With a callback the hash goes to it.passwordChecks whether a password matches a hash fromVerify passwordHash. With a callback the result goes to it.refReturns a number under which a value (e.g. an element) is stored, so you can pass it on as a number.derefturns it back. The same value always gets the same number.removeDetaches a function added withDebug Hook addDebugHook.resetRestores the default fog distance (100).Fog Distance resetRestores the default moon size (3).Moon Size resetRestores the default rain level (0).Rain Level setSets the maximum flight height of planes and helicopters (0-10000). The value is stored for compatibility with existing scripts (Aircraft Max Height getAircraftMaxHeight) but does not change the in-game limit yet.setSets the maximum plane speed (0-100, 1.5 by default). The value is stored for compatibility with existing scripts (Aircraft Max Velocity getAircraftMaxVelocity) but does not change the in-game limit yet.setTurns clouds on or off. The value is stored for compatibility with existing scripts (Clouds Enabled getCloudsEnabled) but does not change the in-game sky yet.setPuts a weapon the ped already has into its hand (weapon number, e.g. 31 = M4; 0 = fists). Another name:Current Weapon setPedWeaponSlot.setSets the fog distance (-1000 to 1000). The value is stored for compatibility with existing scripts (Fog Distance getFogDistance), but Trilogy Hub does not change the in-game fog yet.setSets the frames per second limit (0-32767). The value is stored for compatibility with existing scripts (FPSLimit getFPSLimit) but does not cap the in-game frames yet; the player sets the limit in the game options.setChanges the game speed for every player:Game Speed 1is normal,0.5slow motion,2twice as fast (at most 10). It affects movement, animations and physics.setTurns interior sounds (music and chatter in buildings) on or off. The value is stored for compatibility with existing scripts (Interior Sounds Enabled getInteriorSoundsEnabled) but does not change the in-game sound yet.setSets how high you can fly with a jetpack. The value is stored for compatibility with existing scripts (Jetpack Max Height getJetpackMaxHeight) but does not change the in-game limit yet.setAssigns an object its simplified version seen from afar (LOD). In Trilogy Hub draw distances are computed by Unreal Engine, so the assignment is stored for compatibility with existing scripts (Low LODElement getLowLODElement) but does not change the in-game look.setEnables or disables the ESC map for the whole server. For a single player useMap Enabled setPlayerMapEnabled.setSets the moon size 0-100. The value is stored for compatibility with existing scripts (Moon Size getMoonSize) but does not change the in-game sky yet.setChanges the radar area colour, e.g. when another gang takes over the turf.Radar Area Color setTurns radar area flashing on or off (e.g. during a turf war).Radar Area Flashing setChanges the radar area size.Radar Area Size setSets the rain level 0-10. The value is stored for compatibility with existing scripts (Rain Level getRainLevel) but does not change the in-game rain; rain comes from the weather (setWeather).showAnother name forPlayer Hud Component setPlayerHudComponentVisible: shows or hides a game HUD component for a player (e.g."radar","money","health","all").warnA standard Lua 5.4 function: emits a warning made of its arguments. Lua warnings are off by default (warn("@on")turns them on) and go to the server process error output. For messages to script authors useoutputDebugString.
Client functions 15
areChecks whether the built-in nametags above heads are on for the local player.Nametags Enabled downloadDownloads a resource file marked inFile meta.xmlas<file src="..." download="false"/>only when it is needed (e.g. a large music file). The result arrives in theonClientFileDownloadCompleteevent, always asynchronously, also when the file was already downloaded.":resource/file"downloads another resource's file.getTurns a screen point (e.g. the cursor) into a pixel of a browser page drawn in the world withBrowser Position From Screen dxDrawMaterialLine3DordxDrawMaterialPrimitive3D. This lets you click on screens and billboards with a browser standing in the world.getReturns the cursor position as a fraction of the screen 0-1 (x, y). Works only while the cursor is shown. The next three results (a world point) are zeros for now;Cursor Position getWorldFromScreenPositiongives the world point under the cursor.getReturns the cursor position in screen pixels (while the cursor is shown).Cursor Position Absolute getReturns the current look of the built-in nametags for the local player (a table with fields as inNametag Style setNametagStyle).getTurns a world point into a screen point (pixels). ReturnsScreen From World Position falsewhen the point is behind the camera or off screen. The third result is the distance from the camera. Useful for text above heads.getReturns the game screen size in pixels. The same asScreen Size guiGetScreenSize.isChecks whether the player is typing in chat right now.Chat Box Input Active isChecks whether the game console is open.Console Active isChecks whether the game menu (pause) is open.Main Menu Active isChecks whether the client is downloading resource files right now (a resource start orTransfer Box Active downloadFile).setMoves the cursor to a spot in the game window (pixels). ReturnsCursor Position falsewhen the game window is not active or is minimised.setTurns the built-in nametags above other players' heads on or off for the local player. A shortcut forNametags Enabled setNametagStyle({ enabled = ... }); useful when a resource draws its own nametags.setSets the look of the built-in nametags above other players' heads for the local player. Fields as inNametag Style setPlayerNametagStyle:enabled,distance,showDistance,scale,color,background; pass only the ones to change.
Shared functions 53
attachAttaches an element (e.g. an object) to a ped's bone, with an offset and rotation. The element moves with the bone, e.g. a hat with the head or a weapon in a hand. Bone numbers are the same as inElement To Bone getBoneIDs(e.g. 1 pelvis, 8 head, 25 right hand, 35 left hand).base64Decodes base64 text back into data.Decode base64Encodes text or binary data in base64 (e.g. an image to send as text).Encode createCreates an explosion at a spot. On the server every player sees it and it hurts like in the game; on the client the explosion is only in that game (it triggersExplosion onClientExplosion, which can cancel it). Types 0-12: 0 grenade, 1 molotov, 2 rocket, 3 weak rocket, 4 car, 5 quick car explosion, 6 boat, 7 helicopter, 8 mine, 9 object, 10 tank shell, 11 small, 12 tiny.decodeDecrypts, decodes or unpacks data fromString encodeString, also data made on another server. Withaes128you pass the key and theiv, withrsathe private key; withzlibthe format can be left out: gzip, zlib and raw are recognised by their header. Characters outside thebase64andbase32alphabets are skipped. Works on the server and on the client.detachDetaches an element attached to a bone withElement From Bone attachElementToBone. The element goes back to its own position (the one fromsetElementPosition), so if it should stay where the hand was, set its position before detaching.encodeEncrypts, encodes or compresses text. Works on the server and on the client. Algorithms:String tea(raw TEA bytes, no base64),aes128(the key must be exactly 16 characters; it also returns a randomivneeded to decrypt),rsa(a public key fromgenerateKeyPair),base64(varianturl),base32(the Crypto++ alphabet, varianthex= RFC 4648 base32hex),zlib(formatgzip,zliborraw, level 0-9, strategy). Withbase64,base32andzlibthe options table can be left out. With a callback the result goes to it in the next frame and the function returnstrue.fromReads JSON text and returns a Lua value. A top-level array (the wayJSON toJSONwrites) unpacks into several results. Broken JSON givesniland a warning with the error position.generateCreates an RSA key pair: private (PKCS#8) and public (X.509), both as binary DER data. To store them in a file or a database turn them into text, e.g. withKey Pair base64Encode.encodeString/decodeStringalso accept PEM keys. Size 512-8192 bits (default 2048; on the client a multiple of 64). With a callback the keys go to it.getReturns the height stored withAircraft Max Height setAircraftMaxHeight(800 by default).getReturns the speed stored withAircraft Max Velocity setAircraftMaxVelocity(1.5 by default).getReturns all of an element's data set withAll Element Data setElementDataas a key -> value table.getReturns the English name of a body part by its damage number (3-9):Body Part Name Torso,Ass,Left Arm,Right Arm,Left Leg,Right Leg,Head.getReturns the setting fromClouds Enabled setCloudsEnabled(trueby default).getComputes the distance between two points on a plane (without height).Distance Between Points2 D getComputes the distance between two points in space.Distance Between Points3 D getReturns the value of an easing curve for progress 0-1:Easing Value Linear,InQuad,OutQuad,InOutQuad,OutInQuad,InElastic,OutElastic,InOutElastic,OutInElastic,InBack,OutBack,InOutBack,OutInBack,InBounce,OutBounce,InOutBounce,OutInBounce,SineCurve,CosineCurve. Useful for smooth interface animations.getReturns the draw distance stored withFar Clip Distance setFarClipDistance(800 by default).getReturns the fog distance stored withFog Distance setFogDistance(100 by default).getReturns the limit stored withFPSLimit setFPSLimit(36 by default).getReturns the game speed set withGame Speed setGameSpeed(1 by default).getReturns the setting fromInterior Sounds Enabled setInteriorSoundsEnabled(trueby default).getReturns the height stored withJetpack Max Height setJetpackMaxHeight(100 by default).getReturns the game clock minute length in milliseconds.Minute Duration getReturns the moon size stored withMoon Size setMoonSize(3 by default).getReturns the setting fromOcclusions Enabled setOcclusionsEnabled(trueby default).getReturns the rain level stored withRain Level setRainLevel(0 by default). Works on the server and the client.getReturns the real date and time of the server (or the player's computer) as a table:Real Time second,minute,hour,monthday,month(0-11),year(years since 1900),weekday(0 = Sunday),yearday,isdstandtimestamp. With an argument it breaks down the given timestamp.getReturns the root of the element tree: every server element is its child. The same as theRoot Element rootvariable. Events attached to it come from every element.getReturns the number of milliseconds since start (a clock that does not go back when the system time changes). For measuring intervals, subtract two values.Tick Count gettokReturns one part of the text (counted from 1), split the same way as insplit.hashComputes the hash of text with a chosen algorithm:md5,sha1,sha224,sha256,sha384orsha512. The result is hexadecimal.inspectTurns any value into readable text: tables are expanded, cycles are detected and elements are shown aselement:type[id]. Useful when hunting bugs.interpolateSmoothly moves from one set of three numbers to another (e.g. a position or a colour) by progress 0-1 and a curve like inBetween getEasingValue. It also accepts twoVector3vectors.iprintPrints values throughinspectto the debug console. Several arguments are separated with spaces.isChecks whether the cursor is shown. On the client: by any resource. On the server: whether the server showed it to the player withCursor Showing showCursor.isChecks whether the ESC map is available (the server sets it).Map Enabled isChecks whether slow motion of a kind is on (Slow Motion Enabled "all"= both).md5Computes the MD5 hash of text (32 hex characters, upper case). Do not use it for passwords; usepasswordHashfor them.resetRestores the default draw distance (800).Far Clip Distance restoreRestores every building and world object hidden withAll World Models removeWorldModel. On the server it affects every player, on the client only what this client hid.setSets the world draw distance. For compatibility with existing scripts the value is stored and returned byFar Clip Distance getFarClipDistance, but Trilogy Hub does not change the in-game distance yet.setSets how many milliseconds one game clock minute lasts (1000 by default, so a game day lasts 24 minutes). A higher value = a slower day.Minute Duration setTurns the game's occlusion zones on or off. In Trilogy Hub what is hidden is computed by Unreal Engine, so the value is only stored (Occlusions Enabled getOcclusionsEnabled) so that existing scripts run without errors.setTurns the game's slow motion on or off: at the weapon wheel (Slow Motion Enabled "wheel") and during stunt jumps ("stunt"). Both are off by default, because in multiplayer slowing down one player breaks the game. On the server the setting applies to every player, on the client only to that game.sha256Computes the SHA-256 hash of text (64 hex characters, upper case).showShows or hides the mouse cursor. The cursor stays visible while at least one resource wants it, so hiding it in one resource does not close another's cursor. By default, while the cursor is shown, the ped controls are blocked.Cursor splitSplits text into parts by a separator and returns a table. The separator is a string (each of its characters splits the text) or a character code, e.g.32for a space. Empty parts are skipped.teaDecrypts text fromDecode teaEncode(also from other servers) with the same key. A wrong key gives no error, just different bytes.teaEncrypts text with the TEA cipher and returns base64, compatible with the standard TEA used by existing scripts, so previously encrypted text can be read here. Only the first 16 bytes of the key count. TEA is not a strong cipher; useEncode encodeStringwithaes128for serious data.tocolorPacks a colour from four components into one ARGB number used by thedxfunctions.toTurns a Lua value (a number, a string, a table, an element) into JSON text, e.g. to store in a file, a database or account data. The format is the same: the result is always a JSON array, and elements are written so thatJSON fromJSONcan read them back. A table that appears a second time (including a table that contains itself) is written as a"^T^n"reference, andfromJSONrestores it as the same table.utf8Another name forLen utfLen: counts the characters in UTF-8 text (accented letters count as one character, not two bytes).