This repository is a basic boilerplate for getting started with Angular in NUI. It contains several helpful utilities and was generated with the Angular CLI. The project is set up with SCSS as stylesheet format. It is for both browser and in-game based development workflows.
For in-game workflows, run npm run watch which will watch the files and build the application upon changes.
This version of the boilerplate is meant for the CfxLua runtime, but should work with other languages if you copy over the web folder and the required fxmanifest.lua entries.
This boilerplate was heavily inspired by the React boilerplate made by Project Error.
A basic understanding of the modern web development workflow. If you don't know this yet, Angular will not be for you. To get started with Angular go to https://angular.io/start.
First clone the repository or use the template option and place it within your resources folder
Install dependencies by navigating to the web folder within a terminal of your choice and type npm i.
This boilerplate comes with some utilities and examples to work off of.
SendAngularMessage
This is a small wrapper for dispatching NUI messages. This is designed to be used with the fromMessageAction, createWritableMessageActionSignal and createMessageActionSignal functions of the NuiService in Angular.
Signature
---@param action string The action you wish to target
---@param data any The data you wish to send along with this action
SendAngularMessage(action, data)Usage
SendAngularMessage("setVisible", true)debugPrint
A debug printing utility that is dependent on a convar, if the convar is set this will print out to the console.
The convar is dependent on the name given to the resource.
It follows this format YOUR_RESOURCE_NAME-debugMode
To turn on debugMode add setr YOUR_RESOURCE_NAME-debugMode 1 to
your server.cfg or use the setr console command instead.
Signature (Replicates print)
---@param ... any[] The arguments you wish to send
debugPrint(...)Usage
debugPrint("Is Angular better than React?", true, someOtherVar)Signatures are not included for these utilities as the type definitions are sufficient enough.
fromMessageAction
This function returns a subject which can be subscribed to to receive updates for a certain action. This is the primary way of creating passive listeners.
Note: You can register as many observers for the same action as you want.
Usage
export class MyComponent implements OnInit {
count: WritableSignal<number> = signal(0);
constructor(private nui: NuiService) {}
ngOnInit(): void {
// This listens for the "setCount" message
this.nui.fromMessageAction<number>("setCount").subscribe({
next: (value) => {
// Do whatever logic you want here
this.count.set(value);
}
});
}
}createMessageActionSignal
This function returns a signal which gets updated based on a certain NUI message action. This is the primary way of creating passive listeners.
Notes:
- You can create a signal for the same action as many times as you want, it will not create a new one but instead return the same one.
- When you create a signal for an event that was created before, the current value of the signal is available immediately.
- In order to "subscribe" to a signal the way you may do using events you should use the
effectmethod from Angular. - If a message is received but the value hasn't changed, the effects will not be triggered. This means you cannot use this if you update the state on the NUI side, like with setVisible. Take a look at
createWritableMessageActionStoreif you need this.
Usage
export class MyComponent {
constructor(private nui: NuiService) {
const visible = this.nui.createMessageActionSignal<boolean>("setVisible", false /* Optional initial value */);
}
}createWritableMessageActionSignal
This function returns a signal which gets updated based on a certain NUI message action. This is the primary way of creating passive listeners.
Notes:
- You can create a signal for the same action as many times as you want, it will not create a new one but instead return the same one.
- When you create a signal for an event that was created before, the current value of the signal is available immediately.
- In order to "subscribe" to a signal the way you may do using events you should use the
effectmethod from Angular. - If a message is received but the value hasn't changed, the effects will not be triggered. This means you cannot use this if you update the state on the NUI side, like with setVisible. Take a look at
createWritableMessageActionStoreif you need this.
Usage
export class MyComponent {
constructor(private nui: NuiService) {
const visible = this.nui.createWritableMessageActionSignal<boolean>("setVisible", false /* Optional initial value */);
effect(() => {
if (visible()) {
console.log("Hello!");
} else {
console.log("Goodbye!");
}
})
visible.set(true); // Will print "Hello!"
visible.set(false); // Will print "Goodbye!"
}
}Note: if you use a signal for the same event somewhere else in your application, it will also have the updated state regardless of whether you are using a writeable or readonly version of the signal. If you wish to do so, you can wrap this in a custom service including fetchNui to update the lua side of the resource right away.
fetchNui
This is a simple NUI focused wrapper around the standard fetch API. This is the main way to accomplish active NUI data fetching or to trigger NUI callbacks in the game scripts.
When using this, you should always at least callback using {} in the gamescripts.
This can be heavily customized to your use case
Usage
// First argument is the callback event name.
this.nui.fetchNui<ReturnData>("getClientData")
.then((retData) => {
console.log("Got return data from client scripts:");
console.dir(retData);
setClientData(retData);
})
.catch((e) => {
console.error("Setting mock data due to error", e);
setClientData({ x: 500, y: 300, z: 200 });
});dispatchDebugMessage
This is a function allowing for mocking dispatched game script actions in a browser environment. It will trigger fromMessageAction handlers as if they were dispatched by the game scripts. It will only fire if the current environment is a regular browser and not CEF
Usage
// This will target the fromMessageAction observers registered with `setVisible`
// and pass them the data of `true`
this.nui.dispatchDebugMessages([
{
action: "setVisible",
data: true
}
]);Misc Utils
These are small but useful included utilities.
this.nui.isEnvBrowser()- Will return a boolean indicating if the current environment is a regular browser. (Useful for logic in development)
This boilerplate was designed with development workflow in mind. It includes some helpful scripts to accomplish that.
Hot Builds In-Game
When developing in-game, it's best to use npm run watch. This is similar to ng serve, but it builds the application. Meaning all that is required is a resource restart to update the game script.
Usage
npm run watchProduction Builds
When you are done with development phase for your resource. You must create a production build that is optimized and minimized.
You can do this by running the following:
npm run buildIf you want to contact me or require help you could join my discord server, I can't guarantee that I will be able to help you.