This is meant to be a supplement to the internal help. There is much that is not explained or is assumed that once learned is best documented to be shared. This document is structured based on how it all fell out of my head. There wasn't any real planning to it. If someone wants to come along and sort it out or expand on any of it, that would be wonderful.
Hardcode versus Lua
The built-in game commands are frequently referred to as hardcode, whereas any user-create commands or scripts are often referred to as softcode. MAGA uses Lua for softcode. You may find the two terms used interchangeably in this guide, or even referred to as the parser in some instances.
When running hardcode commands, you can invoke the Lua parser by enclosing code within square brackets:
. For example:
. There are a few things to note in that example. The first is that if you want any output from the parser, you need to invoke the
function, or another function that produces output. Another is the
object, this is a reference to the MAGA database object that is running the code, in this case you.
refers to the
is one of the special 'non-attribute attributes'. More on that in a moment.
There are several specific points of data belonging to an object that aren't stored in attributes. When using Lua, these can be retrieved as if they were attributes, even though they are not. For example, you could
when an objects name is in fact not stored in any attribute. Here is a list of the pseudo attributes:
|| Object's alias
|| Numeric portion of object's database ID
|| Numeric portion of object's location database ID
|| Object's name
|| Numeric portion of object's owner's database ID
|| Object type
You might notice that all of these start with a capital letter. That is to avoid conflict with any user-created attributes, which are suggested to start with lowercase letters. This brings another important point, all attribute names are case sensitive
. You can
@define FooBar /str on me
@define Foobar/str on me
and you will end up with two
attributes defined, one named
and one named
. You can use this to your advantage if you had an object that needed to store a string that represented a location of some sort, you could use an attribute named
without it conflicting with
, however it will probably just lead to confusion in the end.
The parser creates a couple of special Lua objects, such as
, which you've already seen mention of.
|| A reference to the database object that is currently running the Lua code
|| A reference to the database object of the location of the object that is currently running the Lua code
(Whew, that last one was a mouth-full)
If you want to retrieve a specific object, take a look at the thing()
It's not the wisest thing to turn a server full of players loose with access to every Lua function and library running under the same permissions as the server user. You'd invariable have someone invoking
and deleting something they shouldn't, or causing some other sort of mayhem you haven't thought of yet. As a result, a couple of security measures are in place. All of the Lua code runs in a per-user sandbox. One user's code cannot affect another's. In addition, only specific Lua functions and libraries have been exposed. At present the list of functions is not available from the built-in help, but I've managed to squeeze them out of TheFool76
, so here they are:
MAGA provides a player MySQL database for those with the SQL
power. It can be accessed either via the
command or the
function. It is not necessary to use a trailing semicolon (
) for single SQL statements.
Here are some (very) random examples pulled from some incomplete projects:
@sql SELECT * FROM coords_20
| objid | x | y |
| 5 | 10 | 0 |
@lua sql("UPDATE SolarSystems SET time=" .. os.time() .. " WHERE objid=2")
@lua myship = sql("SELECT * FROM SolarSystems WHERE objid=2") if myship ~= nil then print(myship.lon) end
function will always at least return an array with element 0. If there are no results to your query than element 0 will be nil. If there are results, there will be one or more numbered elements, starting at 0. Each will have named elements matching the MySQL column names. In the last example, I had a column named
(representing longitude in relation to the system's primary star). Because I had at least one result (only one in this case), element 0 (
) was not nil, and had an element named
Spreading things out
Code gets hard to manage in a hurry when it's all on one line. One way to deal with this is to spread it across multiple lines. Any
time the MAGA sees your input end in a single backslash (
), it will assume you intended to enter a newline in the current input without
terminating the input. For example, we could really make a mess of channels:
+public This is my first line\
and this is my second
[public] QBFreak: This is my first line
and this is my second
What you can't tell from this monochrome, frozen-in-time example is that the command didn't send until after I hit enter at the end of the second line.
In addition, both output lines are formatted with my colors for channel output, not just the first. The MAGA interpreted the
as a newline in the current command, not a request to execute the command as thus far entered. You can use this to your advantage when entering multiple lines of code:
if tonumber(os.date("%H")) < 12 then \
print("Good morning!") \
That was much easier to read than
@lua if tonumber(os.date("%H")) < 12 then print("Good morning!") end
, although a lot harder to go back and make a quick edit and run again. I make use of this MAGA feature in combination with my client's ability to send files as input. This way I can contain all of my code for a particular object or project in a single file and send it all at once. I can edit to my hearts content in an editor that's much friendlier than my client's input line. I can save a local copy which is really nice to have when you make a neat object and want it on multiple servers. Best of all, if I want to experiment and need to make sure I can undo it all, I just have to save a copy of the file before I start making my changes. The really neat thing about sending multi-line functions (or any other attribute value), is they are actually stored this way. If you
the object, you'll see your data, spread across as many lines as you choose to enter it. This is really nice if you need to quick check some code with
@set foobar/str on me to this\
Attribute defined and set.
Examining QBFreak (#5)
Advanced MAGA magic
function allows you to add MAGA commands to the command queue from Lua. This means you can run MAGA-specific commands (
for instance) from inside a Lua function. In addition to this, you can specify which object runs the command, how long to wait until it runs, and even a string to identify the command. This one function encompasses the functionality of several TinyMARE
commands. The help for
is a little light on details, but it will give you the syntax:
queue_cmd( <command>, [<#id>], [<wait_time>], [<timer_id>] )
The most basic usage is to immediately run a command:
@lua queue_cmd("@print Hello, World!")
The next is to make some other object run a command:
@lua queue_cmd("say Hello, World!",thing("w").Id)
West says, "Hello, World!"
This of course assumes that there is an exit aliased "w" in the same room as you, and that you own it (or otherwise have the power to make it run commands). If you don't own anything just replace
me.Id to make yourself do it.
Probably one of the most common uses of this function, is to run a command after a specific amount of time has elapsed:
@lua queue_cmd("say First command", me.Id, 3000)
say Second command
You say, "Second command"
You say, "First command"
It is important to note that
is in milliseconds. If you want seconds, you'll want to multiply your value by 1000. In my example above, I waited 3 seconds or 3000 milliseconds. This usage of
is quite useful for delaying responses in things like NPCs.
The last usage and probably the most powerful allows you to assign a
string to your command. If you do this, you can call
again before the timer has expired and change the timer or the command. Going into details of how
this is useful is beyond the scope of this document (there are in fact just too many ways), but I will give you an example of how it works:
@lua queue_cmd("say Whew, that was a long wait", me.Id, 10 * 60 * 1000, "mycommand")
@lua queue_cmd("say Well that wasn't so bad", me.Id, 10 * 1000, "mycommand")
You say, "Well that wasn't so bad"
The first command we queued would have waited 10 minutes (1000ms = 1 second * 60 = 1 minute * 10 = 10 minutes) before it ran. The second one, replaced the first in the command queue with not only a new command, but also a new wait time.
- 05 Apr 2017