Skip to content

/ LuaPlugin-GTAV

forked from gallexme/LuaPlugin-GTAV

Overview

Jump to bottom
Jasen Samuels edited this page May 18, 2021 · 2 revisions

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 Guide

Installation Guide for v5 and above

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. Make sure you have ScriptHook
  2. Download JM36 GTAV LuaPlugin
  3. Place the contents of GameDir-GTAV into your GTAV Game Directory (where the gta5.exe is located)
  4. Place ONE of the LuaPlugin ASI files where ScriptHook is located

Installation Guide for v3 and older

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. Afterwards, the ScriptsDir-Lua directory we can place literally anywhere we want and name it anything/whatever we want; make a note of what you named it and where you placed it. Lastly, head back to the GTAV Game Directory and go into the underlying scripts directory; open the main.lua script/file with an editor of your choice and change/set the Scripts_Path variable (by the top, in the config section) to the location and name that you put the ScriptsDir-Lua as.

  1. Make sure you have ScriptHook
  2. Download JM36 GTAV LuaPlugin
  3. Place the contents of GameDir-GTAV into your GTAV Game Directory (where the gta5.exe is located)
  4. Place ONE of the LuaPlugin ASI files where ScriptHook is located
  5. Place the ScriptsDir-Lua directory anywhere (and optionally rename it to whatever you want it to be), making a note of that for the next step. 6: Head back to your GTAV Game Directory and go into the underlying scripts folder; open the main.lua file/script with an editor of your choice, and change/set the Scripts_Path variable (by the top in the config section) to the location and name that you chose for ScriptsDir-Lua

First Script

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

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

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.

Clone this wiki locally