Plug-in scripting tutorial

UNDER CONSTRUCTION WARNING

This document is a work-in-progress draft. It has not been finalized or reviewed. Please treat it as such.

INTRODUCTION

This tutorial is designed for anyone new to writing Vendetta plug-ins that wants to jump in and get started. The format of the tutorial will be to introduce a couple of new ideas and then use those ideas in an example creating a small plug-in for the purposes of demonstration.

Hopefully, this approach will allow beginners to progress with careful study, but at the same time will not bore experienced programmers to tears.

VENDETTA AND THE LUA SCRIPTING LANGUAGE

Many games today allow player created plug-ins and mods. Most games do this in the same basic way. First the core of the game (both server and client code) is written in a language such as C or C++, which is very efficient but takes a lot of experience and care to avoid subtle mistakes. The language is chosen to achieve the best possible performance at the cost of slower development time or more complicated code.

Then, to allow programmers to build upon this core rapidly, a second programming language is used. This second language is known as a scripting language. The principle benefit of a scripting language is that scripts are isolated from many low level, complex, details of the game core. This allow code written in scripts to be comparatively simple and easy to read (once you get the hang of it). As a result, development times using scripts can be very fast. As an added bonus, anyone, whether they are a member of the game development team, or regular a player, can use the scripting language to build upon the core game in creative new ways.

In Vendetta, that scripting language is Lua. All of the Vendetta Plug-in code you write will be written in Lua. Lua is a widely used language with free documentation and interpreters available on-line. So, the time you spend learning Lua while writing Vendetta plug-ins is a good investment, because you are free install Lua on your machine at any time and use the language however you see fit.

This tutorial will not spend much time covering the features of Lua itself, but will focus on using Lua in combination with Vendetta plug-ins. If you are new to Lua, you may benefit from spending an hour or two with some of the excellent Lua tutorials available on-line.

• The Programming Language Lua[1]
• Lua Tutorial Directory [2]

GETTING STARTED WITH THE COMMAND CONSOLE

Getting started with Lua scripting in Vendetta is so easy, you don't even have to leave the game. That is because Lua is available to us via the in game command console.

First we'll open the command console. The default method of opening the command console is with the ` key (left of the '1' key). The command console can also be opened by typing /ConsoleToggle into any chat channel.

Then, we can access the Lua scripting language by starting the line with the command /lua. The output form Lua commands will appear in your message window. Let's do a couple of examples to get started.

<source lang="text"> /lua print("hello."); </source>

One of the handy features you can start using right away is Lua's built in support for basic arithmetic. Suppose the station I'm docked at sells Synthetic Hydrocarbons at a price of 27c each. If I want to know the price for buying 117 Synthetic Hydrocarbons, the total cost can be quickly calculated in Lua.

<source lang="text"> /lua print(27 * 117); </source>

The answer: 3159

For our last example of Lua in the Command Console, we'll use an API call to find out something about the state of the game. We'll get the id of the active chat channel.

<source lang="text"> /lua print(GetActiveChatChannel()); </source>

As you can see, lua script executed via the command console run immediately when you press ENTER. However, if you want to run the same command again in the future, you must retype it completely. As your scripts become more complex, you'll need to store the scripts in files so they can be executed again and again with minimal typing.

We do this by creating a plug-in, which is the topic of the next section.

APPENDIX A: LINKS AND RESOURCES

• The Programming Language Lua[3]
• Lua Tutorial Directory [4]
• Vendetta Lua Interface Documentation Wiki [5]
• Available Plug-ins [6]