My Workflow: How to Approach GrandMA3 Software Updates as a Lua User

Hey lighting folks! The following is the transcript from my YouTube video, My Workflow: How to Approach MA3 Updates as a Lua User

If you're interested in Lua programming for MA3, I think you'll also enjoy my Lua for GrandMA3 Tutorial series. Please check out my channel, From Dark To Light, on YouTube, and you can find the code to go along with my tutorials here on GitHub.

Hello, lighting people. Welcome back to my YouTube channel, or welcome to it if you're new!

Today I'm just going to make a quick video to talk about what to do when updating MA3 as a Lua user. Of course, it's not really that complicated, but to help eliminate confusion, I'm going to walk you through the process I use when updating MA3.

To start off with, I think it would be useful to talk a little bit about the workflow of how I use MA3 in general and Lua with it. I work part-time for a smaller campus at a large church and I run lights frequently, but I also have volunteers run lights as often as they're available. They don't have time or interest in learning the software as I do, nor are they typically available to prep lighting for services before rehearsal, so to make life easier on all of us, I program sequences for each song and store them in a database, just basically a section of sequences that is dedicated for that purpose.

We just copy these songs and some other basic sequences and use the copies and edit those for a given service and then update the database if we're wanting to keep those changes. I also let volunteers program sequences for the database if they're available, but typically I'm the only one doing it. It's helpful to have the plugin so anyone can do the setup even without knowing how to do the steps, but it also makes it like 10 times faster and more consistent even if I'm the one doing it.

Some of what I do with Lua probably would be possible via macro, but there is more flexibility with Lua. It runs faster than a macro and there are some parts that you can't do with a macro. It really brings a lot more flexibility and beauty to the user interaction part of it, which is a really big deal for me. Lua just gives more options and it can look a lot more professional and elegant, which is a big deal to me.

I've also made a checklist for each type of service we do that you can check off as you do different steps in the prep and it will remind you at different times to complete this checklist if it hasn't already been completed. Another cool tool is a reminder plugin where you can set reminders for yourself if you're in the middle of a rehearsal or service and you need to remember to do something later.

Basically my point is, the way I use Lua, I write these plug-ins and then I’m using them on an almost daily basis. If they break, of course I can function without them, but if I'm out for some reason other people may struggle and if I'm short on time I'm going to struggle myself even to just get everything done and it's tedious and boring to copy and relabel things and so on even if I do have the time.

I've been using Lua since version 1.9 and when I updated to 2.0 it didn't really occur to me right off the bat that my plugins might stop working. Spoiler, they did. I don't remember what all the issues were, nor do I remember actually how I discovered them.

I did read the release notes and I'm pretty sure I changed the commands that were changed by the syntax updates before trying to run the plugins, but I know I did run into more issues after that and I was still really new to Lua so it was a very difficult thing for me to keep up with and figure out all the changes. When I updated to 2.1 I started by updating the console on a day we didn't have any services and then I immediately tested all my plugins first thing. In that case they all worked. I was a little confused a few days later when I noticed that my message box with multiple inputs wasn't working the way it had been. This is because originally pressing please or enter would always close the message box. Since version 2.1 there's a setting. The default value is false and with this setting if you set it to true it closes the message box when you press please or enter, but if it's set to false like the default it is not going to close unless you press please or enter with a button highlighted or click a button.

Instead, if you press please or enter it goes to the next input box or the next thing, which is really helpful.

Turns out this change was in the release notes, I just hadn't understood it very well.

Recently I updated to version 2.2.5.0 and I actually feel like I was ready for this update and handled it well so I'm going to talk about the process I used.

Actually, before version 2.2.5.0 came out I read the release notes for 2.2.1.1. Let's look at them for just a second.

Remember when I was looking at this version 2.2.5 didn't exist so I'm going to stick to this part. Let's see here… We have “other enhancements;” that could include something, so I'm going to check here.

I'm just scanning right now. Obviously if I'm planning to update I'll read the whole thing but right now I'm just scanning for Lua-related things… I'm not seeing anything yet…

Here we go. Improved Lua. So they expanded the property info function and it has some information about that. Changes with a loaded queue field can be retrieved using this. That's cool.

There's these changes. The version function has been improved and it shows how that works.

That's it for changes. The next thing I want to check on is enhancements. This is enhancements. Let's check changes and just see if there's anything. There's new GrandMA3 Lua functions. Acquire, CloseMessageQueue, CopyFile, GetTextScreenLine, OpenMessageQueue, SampleOutput, SendLuaMessage.

I'll go back to the top and check on deprecated. This tells me the Lua function Aquire is deprecated and it was replaced with a different spelling of Acquire. That makes sense. And it also has a link to the changes page right here.

Obviously, I did read through the entire release notes when I was planning to update but we're just talking about Lua today. That's all I'm talking about for now.

So, I read all these things, and there didn't seem to be any changes that looked like they would affect me. However, I was smart enough not to trust it.

My next step was just to go into Visual Studio Code, pull up some of my plugins, change the GrandMA3 API extension version to 2.2, and just see if it highlighted anything orange.

In this case, it did not on anything here. That is also what I found when I was working with my plugins that I do for the church.

I do want to make the comment that sometimes the extension has errors so don't trust it 100%, but it is a useful tool to quickly highlight if there's anything that might need to be changed. I didn't see anything there so I went ahead and downloaded 2.2.1.1 on my laptop and just ran all of my plugins in a test copy of my show file to see if they worked properly.

And I ran into an issue. This is not in the release notes. Remember my video talking about handles for MA3 objects? If you don't know what I'm talking about, you might want to pause and go watch that real quick.

I'm going to open up the file from that video and show you some addresses. See this “Showdata.Datapools” part of this named address here?

I talked about how you can use it as a numbered string substituting 13 for Showdata as well as 13 for DataPools. But that actually changed in version 2.2. The number is now 14 for both.

Why? I don't know. I don't understand that deep level of how the system works, but it did change and my plugins that used that were not working. Now how did I figure out that the number changed to 14?

I used a handle with the Addr() function to get a numbered string returned and the numbered string showed the number 14.

That's just an example of how you have to think to work through finding why something won't work when you have no idea what's changed.

Now at this point, I had a choice to make. I could go through all my plugins and update all the from address functions to the new or I could change them to named strings.

Or actually there's a function called DataPool() that returns the address for the selected data pool. You can use that in conjunction with the “Sequences.number” or whatever you need to come after the data pool part of your string. I already had some instances of the FromAddr() function using that method and I decided it would be the most reliable to not be likely to change again in future versions. So that's what I ended up doing and that was helpful because then I could still use the current versions of my plugin in version 2.1, which I was still using at that moment.

I finished testing all my plugins and I didn't find any more errors, so when I was ready I read the release notes for version 2.2.5.0 and updated the church's lighting system, and then I again tested my most important plugins just to be sure that they really worked.

Another important thing to keep in mind is that, if they make command syntax changes like they did in version 2.0 and you're sending commands through your Lua scripts, which I do a ton, you're going to have to go update those commands in your code or you're definitely going to have problems.

At any rate, I know this was a lot about me and how I do things, but I really hope you can find some good value in it for yourself and maybe understand a little better the world I'm coming from and how I approach Lua. Not to mention a good strategy for approaching updates.

I'll also repeat, as I've mentioned in Discord before, that all of my videos contain the version of MA3 I'm using in the description so you can always verify if you're using the same version I made the video with or not and if that's a potential cause for errors. I have covered all of the changes I noticed with this update. The change to the address string was the only one that I've run into, but if you have seen anything on your own please comment below and we can help each other with finding those things rather than everyone having to find it for themselves. That would be super helpful.

Anyways, remember to never trust release notes and I'll see you in another video next week. Till we meet again, happy programming!