Overview - JayMontana36/LuaPlugin-GTAV GitHub Wiki

Welcome to the JM36-GTAV-LuaPlugin wiki!

Getting Started - The JM36 GTAV LuaPlugin + Lua Scripting Language

Background

Just like with the prior installments, Grand Theft Auto V requires people to spend time going through code, figuring out ways to add or modify game content, in this case, a way to set a "hook" or an entry/access point, allowing any other code to also run in game. Developers who're skilled enough generally search through decompiled code and/or runtime memory for game native functions and, once found/known and tested, release a scripthook allowing for scripts compiled into .asi files and placed within the game's directory to load and run in game.

 ---------------
[    SCRIPTS    ]
 ---------------
[  SCRIPT HOOK  ]
 ---------------
[     GTA V     ]
 ---------------

This of course requires a ton of examination and experimentation, especially earlier on when the game natives are just being discovered and documented. After some time, lots of game natives (functions which are built "native"ly into either the game or it's engine, which are used by Rockstar Developers and various scripts within the game) were documented, and having access to these functions (names, descriptions, arguments) is extremely useful when it comes to creating or writing your own scripts/modifications for the game.

Lists of game native functions can be found in several places across the web, including (however not limited to) the following (recommended) sites:

1: https://docs.fivem.net/natives

1.Note: Do note that any "native" function within the "CFX" namespace will not work and cannot be used here, as they are specific to FiveM. As for any other possible discrepancies however, check other sites like the one(s) below.

2: http://www.dev-c.com/nativedb

Lua

Typically, to write a custom game script utilizing scripthook, you would need to write it in some C language (C# or C++) which for me (JayMontana36) at least is a very painful hassle, an arm and a leg if you will, a lot more than I really care for or desire, and a complete waste of time with the likes of Lua being in existence as a more than just viable/awesome alternative and solution (especially more so when in the hands of a skillful, knowledgeable, and competent person/developer who knows/understands the language well); C is just a pain overall in general.

This getting started guide is for everyone, anyone who knows (or wants to know/learn and/)or can understand the basics of Lua or scripting/programming/coding; rather than go the painful route which is not very friendly, we will instead pave the way for our much easier and more friendly route and get things/work done much faster using Lua, a relatively simple and declarative language which makes things very straight forward, like you speaking or writing with your native or most proficient language.

Using Lua, we now have:

 ---------------
[    SCRIPTS    ]
 ---------------
[   LUAPLUGIN   ]
 ---------------
[  SCRIPT HOOK  ]
 ---------------
[     GTA V     ]
 ---------------

History

Lua has an interesting history as a language, it was born from limitations imposed on engineers in Brazil; import laws did not allow them to use intellectual property from other countries. To expand past C (which they already had), they would have to develop their own higher level languages themselves. Lua came from this effort; as a scripting language over C, Lua is very easy to work with. It feels more like Python, than say Java or C itself and has no dependencies. This makes setting up and working with Lua in GTA V (or pretty much in general) very easy and a great choice for someone wanting to get their feet wet with minimal invested time and learning curve.

For the geek, Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode for a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal for configuration, scripting, and rapid prototyping.

Along with the history (if that hasn't won you over yet), the name Lua, also has a rich story as it is stated on the official page:

"Lua" (pronounced LOO-ah) means "Moon" in Portuguese. As such, it is neither an acronym nor an abbreviation, but a noun. More specifically, "Lua" is a name, the name of the Earth's moon and the name of the language. Like most names, it should be written in lower case with an initial capital, that is, "Lua". Please do not write it as "LUA", which is both ugly and confusing, because then it becomes an acronym with different meanings for different people. So, please, write "Lua" right!

From Wikipedia [1]:

Lua 1.0 was designed in such a way that its object constructors, being then slightly different from the current light and flexible style, incorporated the data-description syntax of SOL (hence the name Lua – sol is Portuguese for sun; Lua is moon). Lua syntax for control structures was mostly borrowed from Modula (if, while, repeat/until), but also had taken influence from CLU (multiple assignments and multiple returns from function calls, as a simpler alternative to reference parameters or explicit pointers), C++ ("neat idea of allowing a local variable to be declared only where we need it"[3]), SNOBOL and AWK (associative arrays). In an article published in Dr. Dobb's Journal, Lua's creators also state that LISP and Scheme with their single, ubiquitous data structure mechanism (the list) were a major influence on their decision to develop the table as the primary data structure of Lua.[5]

Official site: http://www.lua.org/

Installation Guides

Installing original legacy Lua Plugin scripts (backward compatibility)

You have two options here:

  1. Anything that you are/were told to place into "addins", you instead place into "Modules"

OR

  1. Install the script exactly just like you are/were told (or would've with/in the original), and the automatic migrator should handle the rest for you

Installing "ForUsers"/"ForUsrs" and "ForDevelopers"/"ForDevs" specific releases zips

A few easy steps to get up and running; firstly, we make sure we have ScriptHook. Then, we grab LuaPlugin, extracting everything directly into your GTAV Game Directory (where the gta5.exe is located, placing/merging the scripts folder there, and placing the LuaPlugin_ForUsers.asi OR LuaPlugin_ForDevelopers.asi files there).

  1. Ensure you have Visual C++ Redistributable Packages for Visual Studio 2013 installed.
  2. Make sure you have ScriptHookV installed.
  3. Download JM36 GTAV LuaPlugin.
  4. Place the contents of the downloaded ("ForUsers"/"ForUsrs" or "ForDevelopers"/"ForDevs") release zip directly into your GTAV Game Directory (where the gta5.exe is located).

Installing "Source code" zips

A few easy steps to get up and running; firstly, we make sure we have ScriptHook. Then, we grab LuaPlugin, placing the files/folder from the GameDir-GTAV directory into your GTAV Game Directory (where the gta5.exe is located). Following that, we take either the LuaPlugin_ForDevelopers.asi OR LuaPlugin_ForUsers.asi files (NOT BOTH | ONLY ONE) and place it where our ScriptHook is located.

  1. Ensure you have Visual C++ Redistributable Packages for Visual Studio 2013 installed.
  2. Make sure you have ScriptHookV installed.
  3. Download JM36 GTAV LuaPlugin.
  4. Place the contents of GameDir-GTAV into your GTAV Game Directory (where the gta5.exe is located).
  5. Place ONE of the LuaPlugin ASI files either into your GTAV Game Directory (where the gta5.exe is located) or where ScriptHookV is located.

First Script

Please see [NEW] The Basics Getting Started Scripting Examples and/or the included "Example" scripts which are located within the "Modules" folder for newer/better/modern scripting samples and examples than what is below in this section on this page.

Post-installation, remember where you put your ScriptsDir-Lua directory (and what you named it); that is where all your Lua scripts reside.

Here's an extremely simple "Hello World" example/test script; it does not do anything (at all) in game, it simply just prints to console (assuming you chose to go with the LuaPlugin_ForDevelopers.asi version), and is a good test to ensure that things were done correctly during installation.

local print = print -- Localize the print function for faster access (optional)
return {
    loop =  function()
                print("Hello World!")
            end
}

You may copy this code and save it as test.lua under your ScriptsDir-Lua directory; launch the game, and once loaded in you should see "Hello World!" being printed in console.

The loop() function is what's run on every game frame; careful of what you put here, you can potentially freeze or crash your game but such is life - trial and error, live and learn. You can actually be(come) quite creative here, skipping a few frames if you don't want or need your code to be run on every frame, by utilizing a counting/number variable and an if statement for example.

The init() function is what's run on script initialization/startup (alongside any other things you have outside this of course), which for doing certain things/stuff with some game natives may be better for you to use; it's kept mainly for maintaining compatibility with other older LuaPlugin scripts and is also actually kind of a nice touch for neatness I suppose.

The stop() function is what's run on script termination, which should be used for cleaning up of your script and/or it's doings in the game (such as removing any entities that your script spawned and has track of, or reverting some change made, etc.)

Keys (depreciated)

Keys.lua (depreciated) contains mapping of common keyboard keys; use this for reference or require it in your scripts (depreciated), used with IsKeyPressed function (depreciated, use IsControlPressed function and IsUsingKeyboard function instead).

Have Fun!

  1. https://en.wikipedia.org/wiki/Lua_(programming_language)

  2. Ierusalimschy, R.; Figueiredo, L. H.; Celes, W. (2007). "The evolution of Lua" (PDF). Proc. of ACM HOPL III. pp. 2–1–2–26. doi:10.1145/1238844.1238846. ISBN 978-1-59593-766-7.

  3. Figueiredo, L. H.; Ierusalimschy, R.; Celes, W. (December 1996). "Lua: an Extensible Embedded Language. A few metamechanisms replace a host of features". Dr. Dobb's Journal 21 (12). pp. 26–33.