Advanced Scripting

Work in Progress!

I would suggest before proceeding that you read How to Make a Quest for a general breakdown of scripting to familiarize yourself with the basics

This guide is a look into some of the more advanced and uncommon elements of scripting. Here you will find help with how to use all of the currently available functions, as well as how to combine functions for useful (and often interesting!) results.

Function Breakdown

A reference of all of the luautils functions available for use in scripting at the time of this writing. Additional "convenience" functions created in global scripts will not be covered here, and should be explored at your leisure. Basic familiarity with LUA syntax is assumed. For further information, you can reference src/map/lua/luautils.cpp and its accompanying header file.

Getting Entity References

GetNPCByID

Requires you to look up an NPC's ID and returns a reference that can be used to manipulate that NPC. How to use this will be covered more in the next section.

GetMobByID

Similar to the above, except it is used for Mobs. Will also be covered more in the next section.

GetPlayerByName

Mainly useful for GM commands, it returns a reference for a player that can be manipulated with additional functions. Names given to it are case-sensitive, so the first letter must be capitalized with the remaining lower-case.

Getting Information About the World

GetRegionOwner

Retrieves a numerical value for the country that owns the region. These numerical values can be referenced with the aliases SANDORIA BASTOK WINDURST BEASTMEN or OTHER defined in scripts/globals/conquest.lua

VanadielTOTD

Returns the Time of the Day as a number. The values to reference are stored in src/map/vana_time.h and should be put into a global script if you plan to use this.

VanadielHour

Returns the current hour in the game-world. There are 24 hours in a day.

VanadielMinute

Returns the current minute in the game-world. There are 60 minutes in an hour.

VanadielDayOfTheYear

Returns the current day of the year (similar to a Julian calendar) in the game-world. There are 12 months or 360 days in a Year.

VanadielDayOfTheMonth

Returns the current day of the month (as on a typical calendar) in the game-world. There are 30 days in a month.

VanadielDayElement

Returns the current day of the week in the game world. There are 8 days in a week. Aliases for the return values can be found in scripts/globals/magic.lua

GetServerVariable

Retrieve a variable that affects the entire game world, rather than a specific character.

Getting Information About an Entity

GetMobAction

Returns the current action of a mob entity as a number. This is usually checked against zero to see if a mob is currently taking no special action (general wandering).

Manipulating the World

SetVanadielTimeOffset

Changes the offset from the universal Vana'Diel time. This should ONLY be used for testing, as there is a configuration option for the map server should you wish to offset your server permanently.

RunElevator

Starts a specific elevator in the game world. Unfortunately, there is no reference to assist you with this.

SetServerVariable

Sets a variable that affects the entire game world, rather than a specific character.

Manipulating an Entity

SpawnMob

Used to create an instance of a specific mob in the game world. It cannot be used to spawn an arbitrary monster at a particular location. It can only produce mobs that are defined in the mob_spawn_points table.

DespawnMob

Opposite of above. You should not attempt to use this on any sort of timer.

Miscellaneous

SendUncnown0x39Packet

This is basically a method that is only used to propel characters up the cliff in the geyser spots at Dangruf Wadi.

BitwiseAnd

Simply an abstraction of the C method for Bitwise AND

Conditionals Breakdown

This is a list of conditions in which the core checks scripts. It should make some sense if you are already familiar with the ones used in the quest-writing tutorial.

Advanced Scripting Techniques

A compendium of useful combinations of functions and techniques to help with scripting in tricky situations. If you don't understand how to execute something here properly, feel free to ask in Discord.

See Also

Other scripting situations not covered here: BCNM Scripting