Lua/First Script - Revision history

Grimmys: Add LUA tutorial category

2024-03-11T21:31:50Z

Add LUA tutorial category

← Older revision		Revision as of 17:31, 11 March 2024
Line 217:		Line 217:
	== Learnin' Info ==		== Learnin' Info ==
	We've got something good going on, with information being spat out from the game telling us who we're playing as after the game has "begun" proper. This might seem like we've barely done anything, but this is the starting block that every game-altering script needs. We're off to a great start!		We've got something good going on, with information being spat out from the game telling us who we're playing as after the game has "begun" proper. This might seem like we've barely done anything, but this is the starting block that every game-altering script needs. We're off to a great start!

			[[Category:Lua Tutorials]]

Vandy at 22:51, 11 June 2023

2023-06-11T22:51:30Z

← Older revision		Revision as of 18:51, 11 June 2023
Line 214:		Line 214:
	cm:add_first_tick_callback(init)		cm:add_first_tick_callback(init)
	</syntaxhighlight>		</syntaxhighlight>

			== Learnin' Info ==
			We've got something good going on, with information being spat out from the game telling us who we're playing as after the game has "begun" proper. This might seem like we've barely done anything, but this is the starting block that every game-altering script needs. We're off to a great start!

Vandy at 18:44, 10 June 2023

2023-06-10T18:44:39Z

← Older revision		Revision as of 14:44, 10 June 2023
Line 194:		Line 194:
	Thankfully, what we want isn't too far away:		Thankfully, what we want isn't too far away:
	[[File:First script 13.png\|none\|thumb\|946x946px\|The autofill will show us the description of this method, and what it returns - in this case, it returns a "string", as we see after the -> line.]]		[[File:First script 13.png\|none\|thumb\|946x946px\|The autofill will show us the description of this method, and what it returns - in this case, it returns a "string", as we see after the -> line.]]
	Whenever we call a function, if the function gives us something back, we have to assign it to a variable or it will go away and vanish into the ether, with no memory on your PC being used to "hold" onto it. Do that with something simple:		Whenever we call a function, if the function gives us something back, we have to assign it to a variable or it will go away and vanish into the ether, with no memory on your PC being used to "hold" onto it. Do that with something simple:<syntaxhighlight lang="lua">
	local name = player_faction:name()		local name = player_faction:name()
	I'll keep harping on it, but you can change `local name` to whatever you want - `local key`, `local bits`, `local ostrich_on_fire`, whatever.		</syntaxhighlight>I'll keep harping on it, but you can change `local name` to whatever you want - `local key`, `local bits`, `local ostrich_on_fire`, whatever.

	'''''NOTE:''''' ''It keeps saying name, but its actually referring to the faction's "key" as we'll see in a second - the "code name" is has in factions_tables.''		'''''NOTE:''''' ''It keeps saying name, but its actually referring to the faction's "key" as we'll see in a second - the "code name" is has in factions_tables.''

	Now that we have the information in our code, we can put it all together and print that out to the log file:		Now that we have the information in our code, we can put it all together and print that out to the log file:<syntaxhighlight lang="lua" line="1">
			out( "Hello World!" )

	~~<code>~~out("~~Hello World~~!")~~</code>~~		local function init()
			out("New game triggered!")

	~~out~~( ~~"Hello World!"~~ )		local player_faction = cm:get_local_faction()
			local key = player_faction:name()

			out("Playing as " .. key)
			end

	~~local function init()~~		cm:add_first_tick_callback(init)
			</syntaxhighlight>
	~~out("New game triggered!")~~



	~~local player_faction = cm:get_local_faction()~~

	~~local key = player_faction:name()~~



	~~out("Playing as " .. key)~~

	~~end~~



	cm:add_first_tick_callback(init)

Vandy at 18:43, 10 June 2023

2023-06-10T18:43:16Z

← Older revision		Revision as of 14:43, 10 June 2023
Line 172:		Line 172:

	=== Getting Our Info ===		=== Getting Our Info ===
			With our first tick callback loading up properly, let's hop in and try to get some information about our played faction!

			In the beginning of our init() function, we need to define a fresh new <u>variable</u> which will allow us to hold the faction "object" in memory. A variable is a piece of memory that your computer is going to set aside to hold some data for us - a variable can be a number, text, a function, or game objects like the faction.

			We'll get it using the get_local_player() function, which we can find in the scripting documentation: https://chadvandy.github.io/tw_modding_resources/WH3/campaign/campaign_manager.html#function:campaign_manager:get_local_faction

			We'll be learning a lot about how to use and read the script documentation going forward.

			In our init() function, we need to add the following line of code:
			local player_faction = cm:get_local_faction()
			Where player_faction is the name of our new variable. It can be anything you want, much like init(), but it should '''make sense''' and '''be clear to read'''. It needs to be all one contiguous word, with only text, underscores, and non-leading numbers allowed (ie. my_faction_1 is allowed, 1_my_faction is not).

			Visual Studio Code should automate it for you, but make sure that it's after the init() keyword, is one line after the out() call, is before the `end` keyword, and is one tab over. I like to space my code out thought-by-thought, so this will be a bit lower than my out() code.
			[[File:First script 12.png\|none\|thumb]]
			The way we get information about this game object will be to ask it questions, using functions, or in this case '''methods'''.

			The first thing we want to ask is, hey, what's the faction's name please?

			To ask the game object questions, we need to use the variable name followed by the : sign. Our VSCode plugin will then, thankfully, list us with a great deal of suggestions that we can use. We can also reference [https://chadvandy.github.io/tw_modding_resources/WH3/scripting_doc.html#FACTION_SCRIPT_INTERFACE the scripting documentation for game objects].

			Thankfully, what we want isn't too far away:
			[[File:First script 13.png\|none\|thumb\|946x946px\|The autofill will show us the description of this method, and what it returns - in this case, it returns a "string", as we see after the -> line.]]
			Whenever we call a function, if the function gives us something back, we have to assign it to a variable or it will go away and vanish into the ether, with no memory on your PC being used to "hold" onto it. Do that with something simple:
			local name = player_faction:name()
			I'll keep harping on it, but you can change `local name` to whatever you want - `local key`, `local bits`, `local ostrich_on_fire`, whatever.

			'''''NOTE:''''' ''It keeps saying name, but its actually referring to the faction's "key" as we'll see in a second - the "code name" is has in factions_tables.''

			Now that we have the information in our code, we can put it all together and print that out to the log file:

			<code>out("Hello World!")</code>

			out( "Hello World!" )



			local function init()

			out("New game triggered!")



			local player_faction = cm:get_local_faction()

			local key = player_faction:name()



			out("Playing as " .. key)

			end



			cm:add_first_tick_callback(init)

Vandy at 18:16, 10 June 2023

2023-06-10T18:16:51Z

← Older revision		Revision as of 14:16, 10 June 2023
Line 139:		Line 139:

	Bye!		Bye!

			== Timin' 'n Stuff ==
			You'll probably maybe notice, this text is triggered very, very early on. While it's maybe ~1000 lines of text in, it's only 1.8s seconds (at least, for me, with no other mods enabled) after the script log is created. This is earlier than it might sound. At this time, the game is still going through its loading procedures - this text was triggered before the loading bar even got to 20%!
			Because of how early this is, the game '''is not ready to be accessed yet'''. The game doesn't yet know what factions own what regions, what turn it is, who the player is controlling, or anything like that. The game doesn't have a map object, you can't trigger a new battle, nothin'.

			What we need to do for our next step is '''learn how to listen''' and '''wait'''. Some of the most valuable things we can do in programming are listening and waiting for the right time.

			=== Events ===
			'''''NOTE:''''' ''Not to be confused with the "Events" in-game, the messages and such that hang out with missions.''

			The game has a great deal of "events" that can be triggered. Events are a way for scripts to learn some information about things happening in the game - there are events that will inform us when a new turn has started, when a region has been destroyed, when a battle has ended, when a ritual has been completed, when a mission has been failed, among many many many more. We can even define our own - more on that later!

			The first event we care about is one of the most important - FirstTickAfterWorldCreated. This event is triggered immediately after the game is ready to access - about 80% of the way through the loading bar before the game is interactable for the user.

			Once this event happens, we can do things like ask the game what factions exist, what turn it is, where we are, who we are, etc. Before the world is created, we can only do a bare minimum of setting things up in advance.

			=== Flying the Time ===
			To achieve our first goal - spitting out some information about our player faction - we're going to use a first tick callback and trigger our very own function!

			A first tick callback is a way to '''ask the game to run code on FirstTickAfterWorldCreated'''. Most of your mods will probably involve a first-tick-callback. We use them in the following format:
			cm:add_first_tick_callback(function_to_call)
			But first, we have to create our own function. To do that, we use the following:
			local function my_function_name()
			-- do stuff
			end
			where "my_function_name" can be anything you want. In this situation, I'm going to call the function "init", short for "initialization", because this is the startpoint of my entire script. Some people also prefer "main". Whatever you want really, just make it clear for yourself and anyone else.

			''Eagle-eyed readers will notice that the two dashes they wrote in VSCode will be greyed out; these are called "comments". These are incredibly useful to leave notes to ourselves and other people reading our scripts, to inform yourself and others of what's going on and how things work in our code.''

			To safely confirm that we're calling our new function at the right time, we're going to run our function, trigger another call to out(), and see if it works!
			[[File:First script 11.png\|thumb\|418x418px]]

			=== Getting Our Info ===

Vandy at 17:38, 10 June 2023

2023-06-10T17:38:10Z

@@ Line 74: / Line 74: @@
 === Start It ===
 With our newly created file, our VSC layout will change ever so slightly. In "Open Editors", we'll see our fresh new baby script created; and in the central window, we'll see a new tab that's named the same as our new file, and an empty text file in the center with just the number "1" in it.
-[[File:First script 6.png|none|thumb|1141x1141px|Notice the lil' moon symbol next to our file? That's because Lua is Portuguese for moon!]]
+[[File:First script 6.png|none|thumb|894x894px|Notice the lil' moon symbol next to our file? That's because Lua is Portuguese for moon!]]
 We'll kick off our script with the first piece of the puzzle, outputting some text to a file so we can read and interface with our scripts.

Vandy: starting progress so I don't lose it all to a power outage

2023-06-10T16:34:35Z

starting progress so I don't lose it all to a power outage

New page

In this first step tutorial, we're going to learn:

* How to load & run a custom Lua script
* How timing works, at a large level, with scripts
* How to print out game information to interrogate the state of the game
* How simple variables work

Let's create our first script together!

== Setup ==
First thing's first, let's crack open RPFM to create our new Mod. In RPFM, I'm going to use MyMod -> New MyMod, to create a new easy-to-use mod system. If you haven't already, follow the setup guides in [[RPFM]] for setting up preferences and paths.

[[File:First Script 01.png|frameless|712x712px]]

RPFM will then open up our new MyMod. Within it, use MyMod -> Export, which will unload the contents of the newly created (almost entirely empty) MyMod into your specified MyMods folder. I have this folder pinned to my quick access, but you can also get there with MyMod -> Open MyMod Folder, and navigating down to the newly created MyMod.

Now we can right click this folder and use the newly added "Open with Code" button, which will take the targeted mod folder and open it within Visual Studio Code!

== Visual Studio Code Navigation ==
When we open up in Visual Studio Code, we'll see something that looks a little bit like this - it might differ slightly, that's totally okay!
[[File:First script 2.png|none|thumb|1061x1061px|It might seem like quite a lot at first, but we'll get used to it! Just make sure to set the settings to dark mode if you're not insane.]]

Before we get too far, let's break down some of the parts of what we're looking at here, and set up our windows so we have everything we need.

=== Primary Bar ===
On the very left, we have what VSCode calls the "Primary Bar". It has a few things here - the top has the two files stacked on each other, a search button below that, three buttons we don't have to worry too much about yet, and a Bookmark button. The bottom has our Account and Manage button. '''If you haven't already''', click into the Manage button and set our Profile to the correct one. I have mine saved as "TW Lua".

The part of the primary bar we care most about is the top button, the "Explorer". Think of this as your file navigation - it's effectively the same as navigating the Windows File Explorer, but it has some extra goodies that will be nice for us.
[[File:First script 3.png|left|thumb|578x578px]]
At the top of the Explorer, we have "Open Editors". This will show us all of our actively opened files - we'll see this shortly!

Below that, we have a tab for the currently opened folder. My folder is named babys_first_script, so that's what shows as the name here. Inside are all of the folders AND files that exist within my folder on my PC. We can open, create, rename, and delete any file within to our heart's content, and edit as long as Visual Studio Code can edit it. VSCode can edit essentially any text file, which is what all code files are, effectively. Based on the type of text file, VSCode will handle it differently - it knows the difference between a .lua and a .json file, and will react accordingly to the specifications of either language.

Below that, we had "TODOs: Tree", which is an extension preloaded with our Profile. This is one of my favorite tabs, because I can leave notes for myself to do stuff later and they will be displayed in this window.

Below that are Outline and Timeline, which I rarely use but can sometimes be nice. Outline will show us the layout of our code, and Timeline will show us previous local history for saving/editing these files, and more details if we're using GitHub or another version control software.

The Search button is also incredibly useful, for reasons that may be obvious.

=== Menu Bar ===
On the very top, we have our conveniently named Top Bar, or Menu Bar. You've seen these a billion times before. There's a LOT of stuff up here, but in my five years of using this program for TW Lua I've only really cared about a couple buttons within.

"File" is going to be our best friend, for opening new windows, saving, and creating new files. Edit/Selection/View have a load of commands in them, and they may be good to reference often early on to see shortcuts for saving and other helpful code shortcuts, like duplicating text or renaming stuff.

For now, what we should do is click View -> Problems, which will open up a new bottom bar for us. We only care about the "Problems" tab that shows up.

=== Customizabilitization ===
Let's introduce the idea here that VSCode is '''super duper''' flexible with its layout. Anything on your screen right now can be put somewhere else, including individual tabs, buttons, anything. We can move Problems as a button to the Primary Bar, the Explorer as a tab on the bottom, and TODOs on the right all alone.
[[File:First script 4.png|thumb|824x824px]]
It's a bit clunky and not exactly what I need, but it's as good time as any to show you how flexible it can get.

For now, I'm going to plop Search and TODOs on my new right sidebar stacked on one another, I'm going to right click one of the tabs at the bottom and deselect "Terminal", "Output", and "Debug Console", and keep my left Primary Bar as is otherwise and open back up the Explorer.

== Script Creation ==
Okay, enough preamble. Let's get it started.

=== The Plan ===
Our standard first step for creating a new script is the first step we should do whenever making a new mod or system: having a plan, something we want. For this one, our goal is going to be simple. I want the following:

* When the game starts, I want to output a message to a text file that tells me the game started, and tells me where my starting faction leader and capital region are.
* On every turn after that, I want to give my faction some extra gold.
* If I'm playing as Karl Franz, I want to give my faction another two armies.
* I swear it's balanced.

=== Make It ===
[[File:First script 5.png|left|thumb|Second button from the left!]]
In VSC, go to the Explorer, and hover over the currently-opened-folder tab. You can either right click within the white space and press "New Folder", or press the New Folder button on the tab for the currently opened folder.

Name the empty folder that's created `script`. All scripts we write will be in this main folder. With this folder selected, create a new folder again, and call this one "campaign". Do it again, calling the third "mod", making our full path script/campaign/mod.<blockquote>'''NOTE:''' This folder path is one of several that is specified by Creative Assembly in more recent games, for modders to add scripts to which get automatically loaded. This behavior exists in Warhammer II, Warhammer III, Three Kingdoms, and Troy. It may continue for future games, but any game before Warhammer II needs a different way to load scripts.

For more information, check out [[Lua/Loading Scripts]].</blockquote>Within script/campaign/mod, now either right click the folder and press "New Text File", or use the first button on the tab to create a new file. I'm going to name mine "totally_not_cheats.lua". '''The .lua extension is required, don't skip it!'''

=== Start It ===
With our newly created file, our VSC layout will change ever so slightly. In "Open Editors", we'll see our fresh new baby script created; and in the central window, we'll see a new tab that's named the same as our new file, and an empty text file in the center with just the number "1" in it.
[[File:First script 6.png|none|thumb|1141x1141px|Notice the lil' moon symbol next to our file? That's because Lua is Portuguese for moon!]]
We'll kick off our script with the first piece of the puzzle, outputting some text to a file so we can read and interface with our scripts.