Zugg Software :: zs Object

The "zs" object is the core part of the integration between CMUD and Lua. It is short for "zscript" and is used to reference various items with the zscript system, such as your normal CMUD variables, aliases, triggers, etc.

As with any Lua object, the "zs" object has many different methods and properties. They are documented in the list on the left.

Technically, the "zs" object returns a "CMUD Window Object" for the currently active window. You can retrieve the window object for another window using the "windows" table. For example, if you have a window named "test", you can do:
testwin = windows["test"]
testwin.echo("in test window")
and then use the "testwin" variable just as you would with the default "zs" object.

zScript Commands and Functions

By default, you can access any CMUD zScript command or function directly from the "zs" window variable. For example:

zs.echo("hello world")

will display the test "hello world" in the current window (same as the Lua print command would).

However, there is a lot more going on behind the scenes here. When you called "echo", Lua actually checks to see if there is a zScript command with the same name. If a command isn't found, then Lua will check for a zScript function with the same name. And if the function isn't found, Lua will finally search for a Predefined Variable with the matching name.

So, for accessing most zScript commands and functions, you don't have to do anything special. For example, this would call the #MESSAGE command and display the current %time:

zs.message( "The time is: " .. zs.time())

Note that to call a zScript function, you still need to put () even if you don't have any arguments to pass. Also note that we are concatenating two Lua strings using .. just like you normally would. All of the zScript commands and functions work just like normal Lua commands and functions would.

If you run into a case where a command and function have the same name, you can force Lua to pick one or the other using the "cmd" or "func" methods. For example, zs.cmd.additem will call the #ADDITEM command, while zs.func.additem() will call the %additem function. To access a predefined variable with a given name, use the "sys" method. For example, zs.sys.module will return the current module name just like the %module pre-defined variable in zScript.

Accessing CMUD variables

Accessing a zScript variable is very easy in Lua using the "var" method. Simply add the name of the variable after the "zs.var." For example, assuming you have a zScript variable called "myvar", you could access it's value within Lua using the syntax: zs.var.myvar

This is a normal Lua variable. You can assign a value to it and it will change the value stored in the main zScript variable (and save it to your session file). This is an important distinction: Normal Lua variables are not saved between sessions. Only zScript variables are saved between sessions.

: Thu Dec 13, 2007 12:32 am

Quick question that might be useful
If you have a trigger that would normally do
#TR {test (%d)} {#SAY %1}

How would you access %1 from Lua? Is it zs.var.1?

: Thu Dec 13, 2007 1:53 am

If I remember right, Zugg said it was not available and we should use the pattern syntax to put the capture directly into a variable.

You could try zs.sys.1, although if I understand Lua correctly you can do print(zs.sys) and get a full list of supported items displayed on the screen and find out.

: Thu Dec 13, 2007 11:35 am

Hmm, print(zs.sys) just causes a crash (access violation). I'll not post that separately until 2.17 is released what with Zugg's Lua fixes

: Thu Dec 13, 2007 1:06 pm

I love you

: Thu Dec 13, 2007 1:12 pm

Hm, finding it tough to get anything working, zs.param(x) seems to always return 0. Anyway, I'll be patient and wait for 2.17 this evening ;)

: Thu Dec 13, 2007 5:58 pm

Both zs.param and zs.pat are broken for triggers in v2.16 so you need to wait for 2.17. Then either one will work within a trigger.

: Thu Dec 13, 2007 11:46 pm

Fixed some typos.