DISCLAIMER: I am not an expert on UE4SS or lua modding. In fact, Palworld is the first game I've done any UE4SS modding. I self-taught myself from the UE4 docs, discord convos and brute force. I might not always do things the best way. But I have made a handful of mods and I think I have at least a decent understanding of the basics and overall process, and that's what I'm going to try and cover in this guide.

Prologue | Ground Rules

Hi, so I'm Teh, as some of you might know me from Nexus, or also im.null on Discord.

Lets set some ground rules so you don't complain about me wasting your time:

This is a Lua-only tutorial. I will not be covering BPs, BP interoperability, asset swapping or anything of the like. This will be pure, untainted Lua 😎. Some concepts will definitely transfer over, but if you want BP stuff, this aint it
I'm not going to cover Lua basics, like syntax or structures etc. There are many other tutorials for that, that will do it better than I could anyways.
This is mainly aimed at beginners who have little to no prior experience with UE4SS modding. It's not going to get into anything advanced and is just meant to get your toes wet.
I will give you hints, lead you through the process, and for the most part you can probably just read along if you want, but you need to realize that (at least at this point) nothing is going to be handed to you when you go to make your own mod. The more you can manage to figure out on yourself without using what I provide you, the better off you will be going forward.

If you're expecting docs to tell you everything, handy modding tools, a breakdown of useful functions, or anything of that sort, just do yourself a favor and come back in a couple months because we aren't there. You're getting yourself into hours of digging through live view and header files just so you can write 30 lines of code that doesn't work in two weeks because an update drops that changes the function you hooked.

If you're cool with that, then let's do this

Ch 1. | The Tools

If you already know the tools, you can skip ahead, but don't blame me if I reference something and you don't know what I'm talking about. The first Lua tutorial should've somewhat introduced some of these to you, but incase you need a more detailed look, let's dig in.

UE4SS

This is your bread and butter.

Installation

You technically should have this installed already from the basic Lua tutorial, but it's not exactly covered there, so I'll cover it here.

Grab the latest zDev Version from the releases tab
Extract Mods, dwmapi.dll, UE4SS.dll and UE4SS-settings.ini into your Palworld/Pal/Binaries/Win64 folder
Open UE4SS-settings.ini in your editor of choice, make sure you have the following settings:
- ConsoleEnabled = 0
- GuiConsoleEnabled = 1
- GuiConsoleVisible = 1
- EnableHotReloadSystem = 1 to enable reloading with Ctrl + R
- If you get a white screen when opening the game, change GraphicsAPI to dx11

Breakdown

UE4SS has 5 tabs, and you will make heavy use of two of them.

Console - This is the first heavily used tab, and it's self-explanatory. This is where everything you print() will show up. Not much else to say.

Live View - This lets you get a live view of stuff in memory, filtered by whatever you search. It is incredibly useful and will probably be your most used tool. I'll cover its use in more detail once we get further into things.

Watches - If there's a value you want to keep an eye on from Live View, you can right-click -> Watch to get it stickied in this tab. Honestly I don't use it much, but it can be useful when testing stuff if you want to keep an eye on specific values.

Dumpers - Important for the first use, untouched afterwards ime. Right now, before you do anything else, you should Dump CXX Headers and Generate Lua Types.

Dump CXX Headers gives you a CXXHeaderDump folder with all of the header files to dig through. It's more or less the same as the stuff in PalModdingKit/Source/Pal/Public, but a slightly different format. I prefer the CXX headers, but use whichever you prefer. What's the difference? The /Public folder has all the difference classes broken down into their own files. If you like your stuff separted all nice and neat, then use that. You grab the file for the class you want and everything relevant is in there. If you're a barbarian like me and prefer working with only one file, you can use the CXXHeaderDump, where pretty much everything we care about is stuffed into one file, Pal.hpp. They also have slightly different formatting. Up to you.
Generate Lua Types will create a types folder in your Mods/shared/ folder, which helps give intellisense autocomplete as long as you open Mods as your project folder.

BP Mods - idk what this is man, Lua or die 💀

FModel

Follow the installation stuff in the Asset Swapping tutorial.

For us on the lua side, this is mostly used to view the data table values in the game. Yes, you can look through BPs, but I think it's much easier to search through the header files. uasset files are just a pain in the ass to browse through imo. Maybe it's just my aversion to BP's speaking

For data tables, I recommend just saving them all as JSON so that you can just do Find in Files with VSCode. To do that, Pal -> Right-Click DataTable -> Save Folder's Packages Properties (.json). Then when you want to search through them, just search through the root DataTable folder.

VSCode

Or your editor of choice. I prefer VSCode with the Lua extension

Don't make me explain how to install it or I cry.

Once installed open up a new window, then File -> Add Folder to Workspace -> Navigate to your Binaries\Win64 folder and add both Mods and the CXXHeaderDump folder you generated earlier. You'll also want to add the DataTable folder you just dumped from FModel. All of your dev stuff will be in Mods/YOUR_MOD_FOLDER and you'll use CXXHeaderDump to search through the header files, and the DataTable folder if you want to search through those. We use Mods as the root folder for our mod because the library info for UE4SS and the generated lua types are in Mods/shared. Otherwise you have to copy that into every single one of your mods to get the intellisense.

Ch 2. | Let's Talk UE4SS Functions

If you did the other Lua tutorial, you should be somewhat versed in RegisterHook and NotifyOnNewObject. But you might not have a good grasp on them, so I'll cover them again for you.

RegisterHook

This hooks on to SomeFunction and fires after SomeFunction is executed.

For example, the thing on the first tutorial:

RegisterHook("/Script/Engine.PlayerController:ClientRestart", function (Context) 
    -- do something
end)

What's the function being hooked?

Hopefully you said ClientRestart, or we might have a long road ahead of us

Now, what is Context in this example?

If you said PlayerController, good job. I'm proud of you. The first parameter in the callback (function, in this example) is always the UObject calling the function. Aka, the context.

What's the point of this hook, why do so many scripts use it?

Well, what does it do? It executes --do something after the client restarts. It's a handy way to init shit. Why do most scripts use it? Well, not everything is available right away when the game launches, so sometimes you need to delay your logic until you know whatever you want will be accessible. A general rule of thumb is anything that starts with /Script/ should be available immediately. Anything else, you probably should put behind a hook like this.

But this hook also sucks because it doesn't work for dedicated servers. So I'mma teach you a better one:

RegisterHook("/Script/Engine.PlayerController:ServerAcknowledgePossession", function(Context)
    -- do something
end)

This should get called whenever a client connects to the server.
^{_{Sometimes it doesn't work and I don't know why but we don't talk about that and just claim ignorance and blame the person running the server for setting up something wrong, idk.}}
It also works for local games. I use it in most my scripts.

I said before the first parameter of the callback function is the UObject, but you can also get the params from the invoked function. The callback function of this is always
function(UObject self, UFunctionParams)
So if I have StupidFunction(bool isTrue, int Id, string Message) I can do

RegisterHook("/Script/Example.SomeObject:StupidFunction", function(Context, isTrue, Id, Message)
    print("This message is: " .. Message:get())
    print("The bool is: " .. isTrue:get())
    print("The id is: " .. id:get())
)

What's up with the :get()?

Some of the params we get from hooks are actually these weird things called RemoteUnrealParam, for some reason that is above my level of understanding, so to get the _actual_ value of them, we need to call :get()

Of course it's never that easy because UE never uses easy to work with parameters, but you get the idea.

NotifyOnNewObject

This is magic sauce #2 which allows us to watch for particular objects to be created. Wanna know every time some goes to build an Electric Heater?

NotifyOnNewObject("/Game/Pal/Blueprint/MapObject/BuildObject/BP_BuildObject_HeaterElectric.BP_BuildObject_HeaterElectric_C", function(Context)
    -- woah its a heater
end)

But Teh! How do you know the long address string thing? Baby steps. That's the next section. Just learn about the functions and how to use them for now, I promise I'll get to it.

If you were to run this code above as is, it may or may not work. Why? Remember what I said about things not always being available? Notice this isn't a /Script/. This might not exist yet when you're trying to create the notify. So to be sure, you wrap it in a RegisterHook with SAP or CR. And even that might not be enough...SAP sometimes fires too early, so we might need to wrap it with a delay too...but we'll get to that later. For now, we'll just handwave it and say its magic.

RegisterHook("/Script/Engine.PlayerController:ServerAcknowledgePossession", function(Context)
    ExecuteWithDelay(5000,function()
        NotifyOnNewObject("/Game/Pal/Blueprint/MapObject/BuildObject/BP_BuildObject_HeaterElectric_BP_BuildObject_HeaterElectric_C", function(Context)
            print("woah its a heater")
        end)
    end)
end)

But if you do that you're stupid. Because now every time that hook fires, you're creating a new notification. Two more players just joined your game. Now you have 3 NotifyOnNewObject. Remember, these execute whatever is in it every time they fire. So don't be stupid, and wrap it up.

local not_hooked = true
RegisterHook("/Script/Engine.PlayerController:ServerAcknowledgePossession", function(Context)
    if not_hooked then
        ExecuteWithDelay(5000,function()
            NotifyOnNewObject("/Game/Pal/Blueprint/MapObject/BuildObject/BP_BuildObject_HeaterElectric_BP_BuildObject_HeaterElectric_C", function(Context)
                print("woah its a heater")
            end)
        end)
        not_hooked = false
    end
end)

Now we're cooking with fire.

Those two are going to be your bread and butter, but lets touch on a couple more useful UE4SS functions.

StaticFindObject

Sometimes you just want the default class object. A good example is PalUtility. This bad boy has a lot of great commands in it. But you can't just do PalUtility:AwesomeFunction in your code, you need the default class to call it. In comes StaticFindObject

local PalUtil = StaticFindObject("/Script/Pal.Default__PalUtility")
PalUtil:AwesomeFunction()

Find Functions

These are for locating objects. There are a bunch. You probably will use FindFirstOf and FindAllOf the most but there's also FindObject and FindObjects.

The first two can use short names, which is nice because we can be a bit lazier than normal and just do something like

local player = FindFirstOf("PalPlayerCharacter")

LoopAsync and ExecuteWithDelay

These are both useful at times in their own right and you might use them occasionally. Sometimes you want to make sure something happens a bit later and in that case you can do

ExecuteWithDelay(later_in_ms, function()
    --something
end)

Other times you want something to happen every so often, in which case you can do

LoopAsync(every_so_often, function()
    --something
end)

FName + FText

FName and FText are special string based shit that UE uses for some reason idk why I'm not a UE guy I just know they're annoying on the Lua side. If you ever need to turn a string into FName or FText you can do that with these functions:

local fname = FName(some_fname)
local ftext = FText(some_text)

You can also do the reverse in case some function hands you the nasty stuff:

RegisterHook("/idk/some:function", function(fname_param, ftext_param)
    local cool_string = fname_param:ToString()
    local also_cool_string = ftext_param:ToString()
    print(cool_string .. also_cool_string)
end)

Callback Functions

Just to clarify...

RegisterHook("/idk/some:function", function(self)
    --some complicated logic
end)

Can also be written as

local function complicatedFunction(self)
    --some complicated logic
end

RegisterHook("/idk/some:function", complicatedFunction)

In simple mods, people often just chose to nest the callback function because it can be a bit more clear at first glance, but as you get more and more complex code, it can be worth breaking these callbacks out into their own functions, else you be working with callbacks in callbacks in callbacks.

More functions

There's a lot more functions available from the UE4SS API and I almost certainly underuse them and probably missed some useful ones, but these are personally the ones I have made the most use out of so far. For more info on that, base types, and other UE4SS api stuff, you can view their docs directly instead of me trying to explain shit I don't actually understand: https://docs.ue4ss.com/dev/lua-api.html

Ch. 3 | Digging 101

Alright so at this point you maybe sorta understand some of the base functions available to you in UE4SS, but I know most of you are probably stuck on how to figure out what functions to actually hook onto or call to do whatever you actually want to do.

Well, welcome to Digging 101 📖

Let's start class by getting hands-on. Hop onto a fresh game world and keep the UE4SS console ready. The first task here is going to be something a lot of people are interested in: hook the function that gets called when a chat message is sent and print that message to console.

But we don't know anything about what function fires or where to even look. So let's dig into Live View.

Note:
Live View might not actually be the best for this, since we're looking for a function, but I want you to start learning it and how you can switch back and forth between it and the header files.

In the Live View search bar start seaching for something chat message related. I recommend to keep your searches as simple as possible while still being relevant, until you have a better idea of what you're searching for. We're looking for a function here, because we want to hook into it, so don't bother looking through classes or objects, just check out functions. Once you've done a little searching and think you might have a function to try, or if you get stuck, come back check out the spoiler tags.

Hint: If you can't think of something to start searching for..

Try starting with just "chat" and see what you can find on that. We want to keep it simple after all

Think I found something!

Alright so if you searched for something along the lines of "chat" you probably wound up with some functions to sift through. Hopefully you picked up on `BroadcastChatMessage`. If you did, great job, that definitely looks promising.

For demonstration purposes, lets try to hook that function and see if it actually fires when we say something in chat. Take this opportunity to use what you learned about functions before to write up a script that:

Hooks that function
Prints something when the function is executed

Hint: But where do I get the function name/address thingie to hook?

The function name for the hook is the full function path that you see in Live View, /Script/Pal.PalGameStateInGame:BroadcastChatMessage.

Sanity check code

-- if you did something along these lines, you're good
-- Technically you can wrap this in the SAP hook, but since it's a /Script/, we don't need to do that
RegisterHook("/Script/Pal.PalGameStateInGame:BroadcastChatMessage", function()
    print("enter chat fired")
end)

Now lets leave the world, reload our mod script and type something in chat. If you code is all good, you should see your hook get fired and something get printed to chat!

Nice! That means we actually managed to hook the right function. But we want to know more about this function now. What does it return? What parameters can we hook into? Can we get the message out of it?

In comes header files.

Let's swap over to VSCode for a sec. Right-click on the CXXHeaderDump folder in the workspace and click Find in Folder. This will open a search dialogue with the ./CXXHeaderDump already filled in for the files to include. This lets us search for something in all files of that folder. In the first box we put whatever we're looking for, in this case we want to find more info on BroadcastChatMessage so search for that. Since we already know what function we were looking for of course we get a hit and it's in Pal.hpp. We can click on that search result to automatically open to it.

Note:
We also could have started off like this. Since we knew we were looking for something chat related, we could have just searched header files for "chat" and dug through what came up until we found something that looked promising. But that would've been too easy.

Header File Tip:
If you're using the CXXHeaderDump most of the stuff we care about for Lua is going to be found in Pal.hpp.

When we open to that spot, we can see that we get one parameter with that function

const FPalChatMessage& ChatMessage

So that's neat, we can just pass that straight to our hook. Before we dig deeper, let's give that a try and see what happens. Try to alter your hook to grab the ChatMessage parameter, and try to print that to see what happens. I'll warn you that it won't work, but this is the learning process.

Sanity check code

-- I expect you'll come up with something like this
RegisterHook("/Script/Pal.PalGameStateInGame:BroadcastChatMessage", function(self, ChatMessage)
    print(ChatMessage:get())
end)

Comprehension check! What's the self parameter of this hook?

PalGameStateInGame is the self UObject of this function

If you did it correctly, you should get some error along the lines of:

Parameter #1 must be of type 'string'. Was of type 'userdata'.

print() expects a string to be given to it, and we know from the function header, ChatMessage is of type FPalChatMessage. So of course it's going to be angry.

Let's go back to the function in Pal.hpp and check out what exactly FPalChatMessage is, so we can break it down in the Lua. In VSCode, Ctrl + Left-Click on the type to chase down it's definition.

It should hop directly to the Struct definition of FPalChatMessage, pretty neat.

It looks something like this:

struct FPalChatMessage
{
    EPalChatCategory Category;
    FString Sender;
    FGuid SenderPlayerUId;
    FString Message;
    FGuid ReceiverPlayerUId;
};

So it's a struct that has a couple different components we could play with. For now, let's just try getting the actual FString Message component, since we want to print the message to console.

In order to access this property, we need to deconstruct the struct we get into its parts. So now that you know the parts of the ChatMessage try to alter your hook to:

Get ChatMessage
Access the Message property
Print the Message property to console

Hint: Was of type `userdata` error

Take note of what type this is returning and remember what I told you before...UE never returns you simple strings. Take a look at the UE4SS and see if you can find any useful methods for the Message type.

Sanity check code

-- Something like this should do the trick
RegisterHook("/Script/Pal.PalGameStateInGame:BroadcastChatMessage", function(self, ChatMessage)
    local chat_message = ChatMessage:get()
    local message = chat_message.Message:ToString() -- Take note of the :ToString()! FString is not the same as a string!
    print(message)
end)

Nice work! Now we can log chat messages or whatever else you'd like. Let's move on to something else a bit more hands on.

Ch 4. | Dig it uh oh oh, dig it

Alright Caveman, here's your task:

Find out how to increase the palbox build area and do it with a script. Technically you can do this with PalGameSettings but I'm not talking about that, I'm talking about changing it in memory after the box has been placed.

I'll give you some slight guidance:

Get in a world, place down a palbox, start searching through live view for relevant classes. Remember, we want the box itself, so that's going to be an object, which is going to be an instance of a class.
Once you think you might have an idea, right-click the search box and check Instances only. Make sure your search is narrowed down, and then try placing a palbox down while watching the object list. If you're on the right track, you'll see some new objects appear as they get created in game.
Once you think you've found the relevant objects, I want you to create a script that uses NotifyOnNewObject to print "found a base" when a new base object is created.

If you want to try and work it out on your own, you can start digging and come back if you get stuck. I'll leave a few hints here to help you get there without completely giving it away, but again, the more you can figure out on your own, the better off you'll be for your own mods!

Hint 1: I'm lost on what I should search for

This is your first taste of "not everything is named in a logical way". But we're looking for the palbox, so why not just try searching for that and seeing what comes up? You won't find exactly what you're looking for, but by looking at some of the results, you might get ideas for other things to search...

Hint 2: Give me a little more please

Alright so if you noticed PalBoxBase that might have given you the idea to search for Base. If you did, great! You were on the right track. If not, give that a shot and see what pops up. The next thing is to search through the Base results and see if there's anything relevant...

Hint 3: Just tell me already..

The particular object we want to search for is PalBaseCampModel

Hint 4: I think I know the class, but I'm stuck on how to write the script

Alright so lets pull up the class of whatever we want to notify on in Live View so we can get the path... It should be something along the lines of /Script/Pal.<some_class>. That's what we're going to notify on. Since this one is a Script, we can do this without a RegisterHook initializer. Something like:

NotifyOnNewObject("/Script/Pal.<some_class>", function()
    -- do your stuff here
end)

Sanity check code

Alright, hopefully you were able to find PalBaseCampModel and come up with something similar to the following code:

NotifyOnNewObject("/Script/Pal.PalBaseCampModel", function()
    print("found a base")
end)

By this point you should have a basic script that prints found a base for any base, both existing bases on login, and anytime you place a new base. If you made it here, great job! This is the power of NotifyOnNewObject.

Now that we can detect the placement of new bases, lets dig into the parameters of the base model and try changing them. We'll start by sanity-testing in Live View and then move to the Lua implementation afterwards.

In Live View turn on Instances only and search for your PalBaseCampModel. Assuming you have one placed, you should find an object that is PalBaseCampModel_<numbers>. This is the actual instance of the base camp you placed!

Click on that and you should see a bunch of parameters pop up in the bottom. This lets you view the realtime params of the model, as well as edit them. This is great for testing what exactly does what before you go through the trouble of doing it all programmatically. Normally you'd have to search through all the params to find what you want, but in this case I'll just tell you we want the AreaRange (its pretty obvious anyways).

If you right-click that value in live view, you can click Edit Value. This lets you edit the actual param in memory. Lets try expanding our base to 5000.0. Click apply and go out to the blue ring. You'll notice the ring hasn't actually changed ^{_{(don't get me started on this, that's a lesson for another day)}} but if you go outside of it, the base info is still there, and you can still build base stuff!

Now, lets try to do that with a script so that we can change the range of all bases. Try and do that on your own, and come back when you get stuck. Note the italics. Double-check your work by inspecting the object in LiveView...not everything is always as straightforward as you expect. Make sure to check the sanity check code before you move on!

Hint 1: Not sure how to get the base object..

The first parameter of the callback is the UObject itself. Grab that from the params like you would a RegisterHook and then try changing the value

Hint 2: Pretty sure I have the right code, but the AreaRange isn't actually changing

You're experiencing the joy of working during runtime. NotifyOnNewObject triggers when the object is created...there's a good chance you are writing the value before it's properly initialized, resulting in it getting overwritten by the default value. Add a ExecuteWithDelay(10000, ...) to delay things a bit before you go changing values.

Sanity check code

NotifyOnNewObject("/Script/Pal.PalBaseCampModel", function(base_model)
    print("found a base model, waiting for it to finish initializing")
    ExecuteWithDelay(10000, function()
        base_model.AreaRange = 6000.0
        print("changed a bases range")
    end)
end)

Why no :get() here?
With NotifyOnNewObject, we're getting the object itself, not a parameter. No :get() needed!

If everything is set up right, you should be able to place a new base and it'll automatically update to the new setting. Nice job!

Note:
Remember to untick Instances only when you're done looking at object instances!

Ch 5. | Config files

Now that you have a working base area mod, you could technically just release that as is and have people change the value in the main file. But that's lame and it's nice to provide a config file for better user experience. So here's a real brief lesson on that.

We can real simply add a config.lua file to our /Scripts, and then call that in our main.lua file, like so:

config.lua

local _my_mod_config = {
    -- You can add comments with default values and such
    -- Usually some explanation of what it does etc
    area_range = 3500.0
}
return _my_mod_config

main.lua

local config = require "config"

NotifyOnNewObject("/Script/Pal.PalBaseCampModel", function(base_model)
    print("found a base model, waiting for it to finish initializing")
    ExecuteWithDelay(10000, function()
        base_model.AreaRange = config.area_range
        print("changed a bases range")
    end)
end)

That's it!

Ch 6. | Data Tables

_{^{(honestly i was lazy with this section cuz i was starting to get sick while writing it but it'll work for now)}}
DataTables's hold all the juicy bits of info on stuff. Occasionally you want to search through them or see exactly what stuff is stored there, so you need to know how to look through them. The general idea is just find whatever string you want to search for and search that folder in VSCode like you would header files.

For a really brief example, the way I managed to stop pals from interacting with Electric Heaters in my Electric Appliances mod was by changing the AssignDefineDataId property to one that can't be assigned to. How did I figure out which to assign them to in order to do that?

I did a super quick search in DataTables for the original id, ElectricHeater_0. Which led me to DT_MapObjectAssignData, which has a list of all of the assignable id's. Then I just looked for one that can't be assigned to and luckily enough found PalStorage_0 which has EPalWorkSuitability::None. By changing the AssignDefineDataId of a heater's work task to PalStorage_0, pals can no longer work or be assigned to it.

That's just a short and sweet example of how you can use DT's, maybe if I get more time I'll come up with a better follow-along example of it.

Epilogue | Closing remarks

If you got this far, congrats!

You should now have a decent foundation to start working on whatever Lua mod you fancy. Obviously these are very simple examples of mods, and you got help through a lot of the digging/discovery process, but the basic premise is there. Modding gets a lot more complex and there are a lot of things I didn't cover in this, but that will all come with time, this is mostly meant to get brand new modders on their feet, hopefully you were able to get some use out of it!

If you want more examples, you can always dig into other Lua script mods on Nexus or CurseForge.

If you have any questions please join the Palworld Modding Discord, there are plenty of people there who are more than happy to help out

I might change/improve this guide as I learn more things myself _{^{(and when im not dying from a sinus cold)}}

Good luck out there and make some cool shit!

xrandox/palworldlua.md

Prologue | Ground Rules

Ch 1. | The Tools

UE4SS

Installation

Breakdown

FModel

VSCode

Ch 2. | Let's Talk UE4SS Functions

RegisterHook

NotifyOnNewObject

StaticFindObject

Find Functions

LoopAsync and ExecuteWithDelay

FName + FText

Callback Functions

More functions

Ch. 3 | Digging 101

Ch 4. | Dig it uh oh oh, dig it

Ch 5. | Config files

Ch 6. | Data Tables

Epilogue | Closing remarks

steezeburger commented Feb 18, 2024