ZetaWorlds - Custom Script Functions

ZetaWorlds Custom Script Functions

Important Information

ZetaWorlds custom script functions are not always available as some functions are more dangerous when not used correctly they require special permissions to be granted before use.
Functions not available will throw an OSSL permissions error and require the script to be reset manually, keep this in mind.
To request a function please submit a ticket.

Preface LL-Delay

In the interest of maintaining overall performance and creating more predictable behavior all normal LSL functions, those starting with ll, are setup with specific delays to each function. This delay allows the function to run and complete without another function overlapping or calls being dropped when too much is executed at once. These limits were set a long time ago and since then a lot has changed and performance is now less an issue. We still maintain these delays however, as some functions can drop calls. In some cases reducing the delays can yield more flexibility when creating scripts, but some functions remain barely able to execute even with the delay intact. Changing or even removing a limit has been made possible by making all the hardcoded limits configurable and so can now be changed if required. With the strict advice that this creates uncharted territory and can have detrimental results, it is possible to change a functions delay upon request.

OSSL Sound Functions Linkset

OSSL features a set of functions not too different from the basic LSL sound functions, with the big difference that these new functions offer support for linksets aka multiple prims. This means it is possible to remotely start a sound in a different linked prim or stop all sounds in all prims at once.

Functions that support this are:

osLoopSound
osPlaySound
osStopSound
osLoopSoundMaster
osLoopSoundSlave
osTriggerSound
osTriggerSoundLimited
osPreloadSound
osAdjustSoundVolume
osSetSoundRadius

Usage of the constants LINK_SET, LINK_THIS, LINK_ALL_OTHERS as well as direct link numbers for the first parameter of these functions is now possible.

osDetectedGroup osGroupKey2Name

Similarly to llDetectedKey and llKey2Name these functions offer the ability to detect the group of an actor, prim or avatar, when events are called.
Resolving the returned group key or any group key back to its name.

osDetectedGroup(integer detected)
osGroupKey2Name(key group_key)

osGetAgentUserLevel

OpenSim has user levels that usually define certain admin powers. Level 200-250 is usually set for grid admins, while normal users are of level 0. With this function the user level of a user can be fetched.

osGetAgentUserLevel(key avatar_key)

osGetSimulatorCPUUsage

Functions for returning the memory usage of a given simulator already exist, but there was previously no function to return the other important metric, CPU usage. This function adds the ability to call for a count of CPU resources.
The function causes a point to be set internally after which the CPU usage is recorded. After a delay a second point is set and the recorded CPU usage is averaged. Recording multiple CPU resource points is required due to CPU usage being in flux constantly and any shorter timing would result in inaccurate results.
Note: Running this function takes 5000ms(5 seconds) to execute during which the script does not continue running!
Note: Due to the heavy nature of this function it is not enabled for everyone and can only be used by the owner of a simulator!

osGetSimulatorCPUUsage()

osLoadURL

Functionally the same as llLoadURL with the difference that no ownership check is performed allowing group owned objects to call this function.

osMakeScript

OSSL features a way to generate notecards inside prim inventory, but no function to create scripts. Using normal LSL scripts can be copied, moved across linksets and even started remotely, but creating scripts is not possible. With this function a script can be created from a string, it is placed inside the prim inventory, but not started. Start can be achieved as usual using Script Pin functionality.
Note: Due to this function causing a massive security risk and potential for asset data corruption it is disabled by default!

osMakeScript(string ScriptName, string ScriptContents)

osStringStartsWith osStringEndsWith

As the name suggests these functions can analyze a string through a substring either at the end of beginning of the provided string. Returns true or false depending on whether the string is found.

osStringStartsWith(string input, string startsWith)
osStringEndsWith(string input, string endsWith)

osDateTime

Allows conversion of a unix epoch(time since 1.1.1970 in seconds) to a date format(dd.MM.yyyy hh-mm-ss). Most date formatting should be available as this function directly uses the C# date library.

osDateTime(string format, integer epoch)

osSetBackgroundColor

Additional function for Dynamic Textures to set the image background color as part of the draw commands rather than extra params. Uses same colors as other color setting functions.

osSetBackgroundColor(string rgb) osSetBackgroundColor(string named_color)

osPrimParticleSystem osPrimLinkParticleSystem
osPrimLinkSetTextureAnim osPrimSetTextureAnim

Similar to their normal LSL counterparts with the addition of the first parameter allow entry of an object uuid as the target.

osPrimParticleSystem(key objectUUID, list rules)
osPrimLinkParticleSystem(key objectUUID, integer linknumber, list rules)
osPrimSetTextureAnim(key objectUUID, integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate)
osPrimLinkSetTextureAnim(key objectUUID, integer linknumber, integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate)

osGetRegionName

Using the absolute grid coordinate system which is the regions southwest position multiplied by 256 e.g. 7000,7000 => 1792000,1792000 this function will return the region name that is occupied by this coordinate. Any coordinate the region occupies should work.

osGetRegionName(integer regionGridX, integer regionGridY)

osGetRegionSize

Returns the size of any region if you know what it is called.

osGetRegionSize(string regionName)

osGetRegionCorner

Returns the lower left or southwest corner of a given region. This is the coordinate the region is registered at whether it be a normal region or a var region.

osGetRegionCorner(string regionName)

osTeleportAgent coordinates

Adding another option to osTeleportAgent to allow teleportation based on global grid coordinates rather than region coordinates. This means this function can now use the direct input from adding the local region corner for llGetRegionCorner and the returned vector from retrieving the inventory data of a landmark. Normally this function requires additional math to convert the global position to the actual coordinate the region is registered at, meaning the southwest corner of a var region for example. This math has been moved into the function itself thus input is easier to establish. It also does away with the need for the local position offset, which is normally a vector of the offset from the zero position on the region.

Example:

key tempkey;
default
{
    touch_start(integer touche)
    {
        llRequestInventoryData("Landmark name in inventory");
        tempkey = llDetectedKey(0);
    }
    dataserver(key id, string data)
    {
        vector newpos = (vector)data;
        vector curpos = llGetRegionCorner();
        integer nX = curpos.x + newpos.x;
        integer nY = curpos.y + newpos.y;
        integer nZ = curpos.z + newpos.z;
        osTeleportAgent(tempkey, nX, nY, nZ, <0,0,0>);
    }
}

It is also possible to add the vectors up directly and infer the positions using the vectors individual parts: e.g. combinedpos.X, combinedpos.Y ...

osTeleportAgent(key agent, integer regionGlobalX, integer regionGlobalY, integer regionGlobalZ, vector lookat)

NPC Module v2

NPCs used to be fairly mindless drones that would not really talk back to the script that spawned them. With the new NPC module this has changed. Making additions to the NPC module by making it aware of the existence of the ScriptEngine on the region as well as providing a link to finally get some information back from the NPC.

NPC Constants

OS_NPC_CAN_DIE
Previously an NPC that had lost all its health would simply be resurrected at the very spot it was standing at, which is obviously not ideal. Similarly to when avatars relieved of all their health points an NPC will be teleported back to the position it was originally spawned at. Unless the constant OS_NPC_CAN_DIE is supplied when creating the NPC, which causes the NPC to be entirely removed when all health is lost.

OS_NPC_RETURN_DATA
Previously an NPC would have no connection to the script that spawned it. With the changes to the module the NPC is now initially bound to the script that spawned it. Further will it create a new dataserver event containing the UUID of the Primitive the script is in as well as a unique Secret key. This secret key can be used to change the Primitive data is supposed to be sent to.

When a function returns data to the script it does so in list form. As the dataserver event only holds strings as return it is useful to either typecast or parse the return to list.
Currently the functions causing the NPC to return data are:
osNpcCreate, which returns the UUID of the Primitive it will send data to, equal to that of the Primitive that spawned the NPC, along with the secret key.
osNpcMoveToTarget, which returns data once the NPC has reached the target, along with the position it is at when doing so.
osNpcDelete, which will return whether the NPC has been deleted.
osCauseDamage, in conjunction with the functionality to delete NPCs which have been relieved of all their health will call an internal function to kill the NPC, which returns as such.

OS_NPC_ANNOUNCE
This new constant can be applied to the osNpcMoveToTarget and will cause the NPC to announce to region when it reached the target. This announcement can be intercepted with the llListen/listen event system. The announcement is broadcast across the whole region on the channel: -55365

NPC_CHANNEL
This constant contains the NPC announcement channel for convenience. It points simply to channel: -55365

NPC Functions

osNpcGetHome
osNpcSetHome
Part of changing the behavior of dead NPCs was adding a way to keep track of their spawn positions. This also enabled adding functions to change these after creating the NPC. With SetHome a new position to return to upon death can be defined and with GetHome retrieved.

osNpcSetHome(key npc_key, vector position)
osNpcGetHome(key npc_key)

osNpcGetReturnKey
osNpcSetReturnKey
Changing the Primitive that should receive the dataserver event requires knowing the secret key of the NPC in question so make sure to save the secret somewhere when creating the NPC. The current Primitive data is returned to can be fetched as well so long as the secret is known. Changing requires knowing the UUID of the new Primitive data is meant to be sent to, make sure to fetch the correct UUID of the Primitive and not the Script itself.

osNpcGetReturnKey(key npc_key, string secret)
osNpcSetReturnKey(key npc, key newhost, string secret)

osNpcGetRezzingObject
As Primitive save who rezzed them out NPCs now do so as well. With this function the UUID of the Primitive that spawned the NPC can be fetched.

osNpcGetRezzingObject(key npc)

Currently this enhanced module is available on our mainline regions. Due to requiring further testing and being in active development they are no available for the preconf line.

osSendAlertModal

Sends a modal to the specific avatar with a message and, depending on type, with either a button to dismiss(int type = 1) or automatic decay after a couple seconds(int type = 0).

osSendAlertModal(key avatar_key, string message, int type)

osVectorMultiply osVectorDivide osVectorPow osVectorModulo osRotationMultiply osRotationDivide osRotationPow osRotationModulo

About as self-explanatory as it gets. Multiplies, divides, exponentiate or modulo either vectors(3 floating point numbers) or rotations(4 floating point numbers) with one another. The result of this being a new vector or rotation with each floating point number being acted math on, meaning <2.0,3.0,2.0> * <4.0,3.0,1.0> = <8.0,9.0,2.0>. If you divide by zero that's on you by the way, no warranties and safety nets here.

osVectorMultiply(vector a, vector b)
osVectorDivide(vector a, vector b)
osVectorPow(vector a, vector b)
osVectorModulo(vector a, vector b)
osRotationMultiply(rotation a, rotation b)
osRotationDivide(rotation a, rotation b)
osRotationPow(rotation a, rotation b)
osRotationModulo(rotation a, rotation b)

osSetParcelDetails llGetParcelDetails

In order to provide some uniformity between the setting and getting functions regarding parcel details the constants have been expanded and some have changed to bring them both in line. This means the new constants for these follow the LSL specification and are expanded to include more data.

Changed are the PARCEL_DETAILS_ANY_AVATAR_SOUNDS and PARCEL_DETAILS_GROUP_SOUNDS from 7 and 8 to 68 and 69 respectively. Previously available, exclusive to osSetParcelDetails, constants PARCEL_DETAILS_CLAIMDATE, PARCEL_DETAILS_ALLOW_PUBLISH and PARCEL_FOR_SALE shifted from 10,11 and 12 to 65,66 and 67 respectively. These changes were made to bring them all in in line in a reasonable and logical manner. Scripts that use the constants rather than the integers they represent will continue to work just fine as both functions now reference them directly from the ScriptBaseClass.

All the available constants are as follows:

PARCEL_DETAILS_NAME = 0;
PARCEL_DETAILS_DESC = 1;
PARCEL_DETAILS_OWNER = 2;
PARCEL_DETAILS_GROUP = 3;
PARCEL_DETAILS_AREA = 4;
PARCEL_DETAILS_ID = 5;
PARCEL_DETAILS_SEE_AVATARS = 6;
PARCEL_DETAILS_PRIM_CAPACITY = 7;
PARCEL_DETAILS_PRIM_USED = 8;
PARCEL_DETAILS_LANDING_POINT = 9;
PARCEL_DETAILS_LANDING_LOOKAT = 10;
PARCEL_DETAILS_TP_ROUTING = 11;
PARCEL_DETAILS_FLAGS = 12;
PARCEL_DETAILS_SCRIPT_DANGER = 13;

PARCEL_DETAILS_DWELL = 64;

PARCEL_DETAILS_CLAIMDATE = 65;
PARCEL_DETAILS_ALLOW_PUBLISH = 66;
PARCEL_FOR_SALE = 67;
PARCEL_DETAILS_ANY_AVATAR_SOUNDS = 68;
PARCEL_DETAILS_GROUP_SOUNDS = 69;
PARCEL_DETAILS_SALEPRICE = 70;
PARCEL_DETAILS_GEOMETRICCENTER = 71;

osSet and osGet Functions for Inventory by key

Normal LSL Inventory functions rely on the inventory name as string for selecting the correct item. As multiple different types of inventory(scripts, textures, sounds...) can have the same name this creates issues when you want to do anything with a specific one. In difference to the normal functions these ones use the UUID of the specific item, which is unique.

A new function osGetInventoryNumber also returns a list of all the items specific to a category(scripts, textures, sounds...) directly as list of UUIDs.

The functions mostly operate in the same way as their normal LL versions.
Exceptions are:
osGetInventoryKey which has an additional category parameter as means to separate not only by name, but also the type of inventory item.
osGetInventoryName which simply uses the item UUID to fetch the name rather than the type and number.

osGetInventoryAcquireTime(key item_UUID) // Retuns a date as string
osGetInventoryCreator(key item_UUID) // Returns the UUID of the creator
osGetInventoryKey(string name, integer category) // Returns the key of the inventory item
osGetInventoryNumber(string name) // Returns number of items with that name
osGetInventoryPermMask(key item_UUID, integer category) // Returns the permission mask as integer
osGetInventoryType(key item_UUID) // Returns the type as integer

osSetInventoryPermMask(key item_UUID, integer category, integer value)
osGiveInventory(key destination, key inventory_UUID)

osGetInventoryList(integer category)

osSetAllowedPayers osGetAllowedPayers

By default any person can pay money to an object, which makes sense for tip-jars or vendor systems, but can be problematic for rental boxes. When a specific person is supposed to be the only one to give money to an object then others doing so requires issuing a refund, which can be a major headache given the extra permissions required and dealing with transaction fees. To rectify this issue these two functions handle an internal list of UUIDs that will be the only ones allowed to give money to the object. When another person makes a payment attempt it gets rejected and the money event never fires for the script.

As the event is ultimately fired by the viewer the first point of interception is the money module, which is Gloebit in this case, so changes were made to that as well.

osSetAllowedPayers([]); // Sets everyone allowed
osSetAllowedPayers(["avatar UUID"]); // Allows only avatar to pay the object

osGetAllowedPayers(); // Returns list of allowed avatars to pay the object, empty if everyone

osRequestLandmarkData

Similarly to requesting inventory data via llRequestInventoryData this function will attempt to fetch more information about a given landmark. It returns a dataserver event with the landmark data as list typecast to string.
Returned data includes the true position of the region the landmark is from and the region uuid. If present the gatekeeper url should also be returned. The relative position of the landmark is reported as the first parameter as usual.

osRequestLandmarkData(string landmarkname);

CHANGED_PRIM_INFO Constant

Changing name or description of an object fires a changed event with the constant CHANGED_PRIM_INFO Value = 65536 whenever the change is submitted.
This allows for detection of changes to names or descriptions without the use of heavy timers.

DATA_PAYINFO returns properly

According to the specific UserFlags an AgentData request with the parameter DATA_PAYINFO should return whether a specific user has payment info on file and if it has been used.
This has been adjusted to spec to return the appropriate values.

osGetAgentBorn and osGetAgentUserFlags

DISABLED BY DEFAULT
osGetAgentBorn returns a given avatars creation date in unixtime seconds from 01.01.1970, which makes calculations of this date easier as it returns an integer and not a date string.

osGetAgentUserFlags returns the specified avatars UserFlags, which can be used to check their account status and age verification.

By default these functions are disabled due to their heavy nature, you can ask for them to be enabled.

Note: You can only request data of avatars present in the region!

osGetAgentBorn(string/key avatar_UUID);
osGetAgentUserFlags(string/key avatar_UUID);

Custom Fonts

In order to broaden the appeal of osDynamicTexture functions we have added a custom font loader that loads 200+ fonts into the system to be used for textures.
A full list of all available fonts can be obtained via the osListCustomFonts() function, which returns a list of all the currently loaded fonts.

Note: There are slight differences in font rendering depending on the operating system, so some fonts do not fallback on Arial when characters are requested that do not existing within them.

osListCustomFonts();

A list of all the currently shipped fonts:

28-Segment LED Display, ATROX, Aegean, Aegris Outline, Aegris Stencil, AlbertaBackslant, Amanda, Apex Lake, Aquifer, Aspire, AwesomeFont, Badwolf, BallroomWaltz, Barbatrick, Bareona, Basalt, Bienetresocial, Bimasakti, Biting My Nails, Blackboard Ultra, Blur, Borg 9, Bowman, Bradley Gratis, Bravery, Break Curve, Broadband, Broken Glass, Brushpen Story, Bukhari Script Alternates, Bukhari Script, Byzantine Empire, Calculatrix 24, Calculatrix 7, Cambridge, Cartoon Riot, Castle of Dark, CheGuevara Barry Blue, CheGuevara Barry Brown, CheGuevara Barry German, CheGuevara Barry Orange, CheGuevara Barry Red, CheGuevara ChocolateFactory, CheGuevara Fancy, CheGuevara Golden Bold, CheGuevara Golden Serif, CheGuevara Golden Text, CheGuevara ONKA, CheGuevara Text Sans, CheGuevara Text Serif, CheGuevara Tittle, ChopinScript, Christmas Tree, Circo, Code Squared, Color Basic, Comicool, Cosmic Love, Crayonnette, Creative Thoughts, Deadender, Deluxe Ducks, Dendritic Voltage, Did you see that, Disco Bling, Domino Farm, Dosis, Dunstall, Eaglese Script, Earls Revenge, Edition, Edmunds, Eeri, El Messiri, Emilio 19, Emilio 20, Engineer Hand, Essai, Expectative, Falstin, FancyText, Feels Like Nostalgia, Ferrum, Filepile, Firecat, Fla Fla, Floppy Disk, Florets and Embellishments, Fonts Bomb Skipper, FreshToday, GORAN, Galiver Sans Obliques, Galiver Sans, Gamefly, Ganymede Takeover Regular, General Failure, Gingerbread Victorian, Golden Girdle, Graffiti Treat Back, Graffiti Treat Front, Graffiti Treat, Graphene, Gridstar, Groovtastic, HDRight, Half Empty, Hammermart, HeadlineNEWS, Heavy Equipment, Helltown, Helvetica-Condensed-Black-Se, Highnoon Saloon, Hood Ornament, Husky Stash, Hussar wa Yusha de Aru, Ignore Me, Item, Janitor, Joy Circuit, Kenia, Kitchen Sink Gold, Knewave, Kosova, LCD Solid, Lagunas, Lancaster, Lighting, Linestrider, Little things, Ludlow Borders and Ornaments, Lunais 1, Lunais 2, Lunasol Aurora, Lunasol Eclipse, Lunasol Sequence, Lunasol, Lyons, Madhouse, Magiera, Malache Crunch, Maximum Hoedown, Migrator, Moja, Monospac821 BT, Monsters, Movellan, MuchaFrenchCapitals, Nebulous, Newtown, Numberpile, NumberpileReversed, Open Sans, Organics, Overhaul, Pacifico, Passager, Phenomenologist, Play Sign, Playoffs, Poem Letters Serif, Pyrite, QDBetterComicSans, Queens Park, Radios in Motion Hard, Radios in Motion, Raleway Black, Raleway ExtraBold, Raleway ExtraLight, Raleway Light, Raleway Medium, Raleway SemiBold, Raleway Thin, Raleway, Rebel Bones bold, Reckless Brush, Rede Rounded F24, Rede Rounded F31, Rede Rounded F48, Rede Rounded F99, Rochester, Rok-A-Zine, Romantique Initials, Rykros, S-PHANITH FONTER ZOUL, Safety Third, Sahuagin Black, Sahuagin, Samys Bookified Tuffy, Satella, Saturn, Sayso Chic, Scanah, Scratched Letters, Sever Sans Black, Sever Sans, Sigilian, Silly Hand Script, Sloe Gin Rickey, Smallfoot, Space Marine, Space Wham, Speedway, Spiderling Inverse, Spiderling, Sportsball, Squealer Embossed, Squealer, Squib, TRS Million, Tamworth Gothic, Teleindicadores 1, Thanks For Giving, Thin Pencil Handwriting, Thunaedy, Toronto 1 pixie 2 LCD, Ubuntu Mono, Ubuntu, Unai Lines, Unai Native, Unai Regular, Unifont, Univox, VCR EAS, Varicka, VarickaLC, Viafont, Vortexian, WarioWareMPG, Welfare Brat, Weretiger, Yadou, Your Quota, Zikketica, Zoia Stencil, lazysnell, ledfont-sharp, treasurehunt

osRand

Similarly to llFrand returns a random number of given magnitude. In this case returns an integer rather than a float.

osRand(integer magnitude);

osGetAgentPos

Returns a vector of the position of an avatar via its key. Has to be in the same region as the script.

osGetAgentPos(key avatar);

osRezObject

Working similarly to llRezObject with the difference that it returns the key of the rezzed object. If the object is a linkset the key of its root prim will be returned. For coalesced objects the last rezzed prim or linkset root prim key will be returned(Suggest not rezzing coalesced objects with this function).

Note: The internal function to add the object to the region does not fail silently and permission or other restrictions preventing object rez might cause script errors.

osRezObject(string inventory, vector pos, vector vel, rotation rot, integer param);

osLinkTargetOmega

Working similarly to llTargetOmega with an additional parameter for the link or linkset.

osLinkTargetOmega(integer link, vector omega, float spinrate, float gain);

CHANGED_REGION_STOP Constant

Scripts may lose their runtime variables on restarts due to various factors and so it is a good idea to store data from time to time or specifically when the region is going down for a restart. The constant CHANGED_REGION_STOP Value = 131072 will be fired in a changed event when a proper shutdown is commanded.
Writing relevant variables to the object description or a notecard when this is trigger will ensure data isn't lost and can be used again after the region is back online.

Note: Event triggers are somewhat async and may not fire reliably, especially on regions with a lot of objects.

LINK_RANDOM Constant

As the name suggests this constant used in functions taking a link parameter will insert a random link number. Using LINK_RANDOM Value = -9 uses internal random for generating an integer within the size of the linkset, removing the need to do it in the script each time.