Skip to content

Update Funkin Compiler article #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mikolka9144 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update Funkin Compiler article #63

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
210 changes: 111 additions & 99 deletions assets/content/cookbook/Community/03.FunkinCompiler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,76 +1,123 @@
[tags]: / "community,tool,hscript"


# Funkin Compiler (VSCode extension)

<div align="center">
<img src="https://raw.githubusercontent.com/FunkinCompiler/funkin-extension/refs/heads/main/assets/icon.png" alt="Logo" width="200" height="200"></img>
</div>


An extension for Visual Studio Code to provide better tools for making Friday Night Funkin' mods. Most notably, it allows you to use Haxe's Completion Server for type resolving, local code documentation, static code checking, etc.

While it is recommended to create new mods using the built-in command `Funkin compiler: Make new project`, it is possible to use it with existing mods (without the need for migration).
In addition, build-in debugger for the game will help you with quick iterations to your mod as well as debugging console with dynamically changing the properties of your mod and both PC and Android versions of the game.

## Setting up

Make sure you have both [Haxe](https://haxe.org/download/) and [Git](https://git-scm.com/) installed.
Make sure you have installed [Haxe](https://haxe.org/download/) since this extension makes heavy use of [Haxe](https://marketplace.visualstudio.com/items?itemName=nadako.vshaxe) extension for providing autocompletions and many other features.

Then, search for `Funkin Compiler` in the "Extensions" section of VS Code and install it.
Then, search for `Funkin Compiler` in the "Extensions" section of VS Code and install it. Now run the `Funkin FCPKG: Setup Haxelib` task (You can do so by bringing up the command palette with **Ctrl+Shift+P** and typing in the command).

Now run the `Funkin Compiler: Setup Funkin compiler` task (You can do so by bringing up the command palette with **Ctrl+Shift+P** and typing in the command). You will be asked for the installation directory for Haxe libraries. Either type it in, or use the folder picker to select an *empty* folder to use.
You will be asked which "fcpkg" package. We will come back to what that is later, but for now just select the version of the game you want to be modding (if unsure, select the latest "V-Slice" option).

Now you'll need to wait a couple of minutes for the installation. After it's done, you should see a notification in the bottom-right corner.
Now you'll need to wait a bit for the installation. After it's done, you should see a notification in the bottom-right corner. While not required, it is recommended to close VSCode and open it again to make sure everything loads up correctly (or run `Developer: Reload Window` command).

## Using Funkin Compiler

The extension can work in two "modes":
The extension primarily works with V-Slice mods, but can also be used inside the "assets" folder in the source code of the game.

- **"Mode 1" (recommended):** Uses the provided mod template to create a comfortable environment for developing mods. Most features included are designed with this mode in mind.
To start, create a new folder within the "mods" folder of the game (alternatively, you can copy existing mod to that folder or just open any of the mods already place there) and open it with VSCode.

- **"Mode 2":** Lets you open an existing Friday Night Funkin' mod to help with making small changes, or as an alternative to the provided template.
### Editing your Friday Night Funkin' mod

Opening a Funkin Compiler project will enable Mode 1; opening a Friday Night Funkin' mod folder will use Mode 2 instead.

## Using the built-in mod template (Mode 1)
Once you open the mod you want to edit, you might receive a confirmation to apply patches for the vshaxe extension. This patch allows you to edit `.hxc` files as regular Haxe files.

To start, use the `Funkin compiler: Make new project` command to create a new mod project. You will be asked to type in or select a folder for it.
If you want to edit any script files in your mod, make sure their name start with the upper-case letter (you'll receva a warning if it doesn't).

Now let's take a look at the newly opened project. There are a couple of interesting files and directories in it:
Due to a quirk with the Haxe Language Server, trying to edit `.hxc` directly will cause some features to stop working.

- `assets/mod_base`: This folder holds most of your mod's files. In structure, it's exactly the same as any other Friday Night Funkin' mod. However, some assets (like songs and scripts) have their own dedicated directories.
#### Available features

- `assets/fnfc_files`: Here you should put all the songs you want to include with your mod. Simply copy the `.fnfc` files of your songs, and the extension will automatically add them to your mod.
### Friday Night Funkin' debugger

- `source`: Here you can create script files for your mod. This doesn't differ much from writing `.hxc` scripts, but:
The `funkin-run-game` debugger is used to launch the game instance. Most notably, it supports soft-restarts (restarting will cause an in-game reload instead of re-opening the game's executable) and "Debug Console", which gives you access to the variables registered with `ModStore`.

- All scripts must have the `.hx` extension (instead of `.hxc`).
It can also be customized with additional configuration options. We'll look at the most important ones:

- Using [Package names](../Expert/02.ModPackages.md) is mandatory.
- `execName`: Name of the executable to launch.
- `attachDebugger`: If enabled, adds the "debug" mod to your instance before starting it.
- `cmd_prefix`: Prefix for the launch command. The only practical use for it is launching a Windows instance of the game using "wine" on Linux.

- `funk.cfg`: This file keeps the information about the paths to the directories we just mentioned. For instance, if you would like to move the song directory from `assets/fnfc_files` to `modSongs`, you would change the `mod_fnfc_folder` value in the config to `modSongs`.
To start, in `Run and Debug` click "create a launch.json file", from the menu select `Run the FNF: V-SLice instance`. Now you should have a basic configuration that will lauch FNF version native to your platform.

- `checkstyle.json` and `hxformat.json`: These can be used to tweak code formatting, but this article won't go further into that.
Here's how you can further customize your launch configuration:

Once you're ready to test your mod, press **F5** (or use the "Run and Debug" tab to select the run action) to both compile and launch your mod.
```jsonc
{
"version": "0.2.0",
"configurations": [
{
"type": "funkin-run-game", // Start FNF game
"request": "launch",
"name": "Compile & Run FNF mod on V-Slice engine (using wine)",
"cmd_prefix": "wine ", // Use wine to launch the game
"execName": "VSliceEngine.exe", // The exact executable name. (On mobile, it's the package name of the app)
"attachDebugger": false, // Don't add the "debug" mod
// Add these two lines if you want to test your mod on the connected Android phone
"isMobile": true,
"preLaunchTask": "Funk ADB: Copy this V-Slice mod to mobile",
},
],
}
```

If you haven't done so, you'll be asked to provide a directory with the Friday Night Funkin' instance you want to test your mod with. While it's recommended to use a fresh install of the game, nothing is stopping you from using your active instance.
You probably noticed the mention of "connected Android phone". Here by "connected" we mean "a device available in adb".

By default, this will create two mods (and remove their previous copies) in the selected instance: "workbench" and "debug". In addition, your mod will also be placed in the "export" directory of your mod project.
If you want to make use of this capability, install the [Android SDK Platform Tools](https://developer.android.com/tools/releases/platform-tools) (there are a couple of tutorials on how to install them) and enable "ADB debugging" in [Developer Options](https://developer.android.com/studio/debug/dev-options#enable).

## Editing a standard Friday Night Funkin' mod (Mode 2)
If everything works correctly, running `adb devices` should give you something like:

> Please note that this mode is still in development, and as such, not everything will work correctly.
```sh
[mikolka@AcerGo ~]$ adb devices
List of devices attached
29291FDH300EVG device
```

Once you open the mod you want to edit, you might receive a confirmation to apply patches for the vshaxe extension. This patch allows you to edit `.hxc` files as regular Haxe files.
Now, to launch the debugger on your phone, add a launch configuration like this:

If you want to edit any script files in your mod, change their extension to `.hx`, and after you're done, revert their extension back to `.hxc`.
```jsonc
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch current mod on mobile",
"type": "funkin-run-game",
"execName": "me.funkin.fnf",
//Default package name. Change this if you're using a V-Slice fork with different package name.

Due to a quirk with the Haxe Language Server, trying to edit `.hxc` directly will cause some features to stop working.
"isMobile": true,
"preLaunchTask": "Funk ADB: Copy this V-Slice mod to mobile",
"request": "launch",
},
],
}
```

## Features
If you want to use a application other than "me.funkin.fnf", you'll also need to create `.vscode/tasks.json` with the following contents:

> If a feature is exclusive to a specific mode, it will be noted in brackets.
```jsonc
{
"version": "2.0.0",
"tasks": [
{
"type": "funk-mobile",
"modName": "",
"packageName": "me.funkin.fnf",
//Default package name. Change this if you're using a V-Slice fork with different package name.
"problemMatcher": [],
"label": "Funk ADB: Copy this V-Slice mod to mobile",
},
],
}
```

### Hints in .json files

Expand All @@ -84,37 +131,6 @@ Many `.json` files in your mod will get additional type hints, letting you check

VS Code will be able to statically check the syntax of your code and detect any misspellings or other typing errors.

#### Object casting

Sometimes, you might know the exact type of a generic object (like the exact type of `ev.targetState`). In those scenarios, you can assume the type like so:

```haxe
package mikolka;

// Imports here

class ExampleModule extends Module
{
public function new()
{
super("test module", 1000);
}

override function onStateChangeEnd(ev:StateChangeScriptEvent)
{
//* Typical way to check if we're in a desired state
if (Std.isOfType(ev.targetState, OptionsState))
{
//* We know the state's type here
var setState:OptionsState = cast(ev.targetState, OptionsState);
//* so we can cast to it here

// Additional actions on the "setState" value
}
}
}
```

Here, we cast `ev.targetState` to `OptionsState` after confirming with `Std.isOfType` that it's actually the state we're looking for.

### Code autocompletion
Expand All @@ -129,55 +145,51 @@ When typing, you'll notice this autocompletion window appear from time to time.

The extension will also warn you when importing a known blacklisted class. In most scenarios, trying to import such a class will likely disable the faulty scripted class entirely. You should avoid doing that.

### .FNFC Integration (Mode 1)

As mentioned before, you can auto-integrate songs into your mod using the `fnfc_files` folder. This is useful if you want to keep them for easier editing using the in-game chart editor.

## Customizing the extension

In this section, we will look into technical additions that might be useful for further customization of Funkin Compiler:

### Additions for launch configuration

* `Funk: Compile current V-Slice mod` task (not command): Compiles the currently opened Funkin Compiler project to the FNF instance.
* `Funk: Export current V-Slice mod` task: Same as above, but doesn't copy the mod to the game.
* `Funkin compiler: Make new project` command: As mentioned previously, creates a new Funkin Compiler project.
- `Funk: Compile current V-Slice mod` task (not command): Compiles the currently opened Funkin Compiler project to the FNF instance.
- `Funk: Export current V-Slice mod` task: Same as above, but doesn't copy the mod to the game.
- `Funk ADB: Copy this V-Slice mod to mobile` task: Copies your mod to the connected device. You can customise it if you want to use it with FNF Engines based on V-Slice
- `Funkin compiler: Make new project` command: As mentioned previously, creates a new Funkin Compiler project.

### Friday Night Funkin' debugger
### Extension options

The `funkin-run-game` debugger is used to launch the game instance. Most notably, it supports soft-restarts (restarting will cause an in-game reload instead of re-opening the game's executable).
These options can be configured using the "Settings UI" under the `Extensions > Funkin Compiler` section:

It can also be customized with additional configuration options. We'll look at the most important ones:
- `funkinCompiler.modName`: The name of your mod in the game instance. By default, it's "workbench".
- `funkinCompiler.gamePath`: Path to the game folder. (If you remove this path, you'll be asked for it again when launching an FNF instance.)
- `funkinCompiler.haxelibPath`: Path to your haxelib folder. This should be set when running the `Funkin compiler: Setup Funkin compiler` command.

* `execName`: Name of the executable to launch.
* `attachDebugger`: If enabled, adds the "debug" mod to your instance before starting it.
* `cmd_prefix`: Prefix for the launch command. The only practical use for it is launching a Windows instance of the game using "wine" on Linux.
## Using the built-in mod template (Mode 1)

Here's how you can use them to customize your launch configuration:
> [!CAUTION]
> This feature does not support new mod format introduced in 0.9.0 version and as such will be removed in the next major update of this extension. Make sure to migrate by compiling your mod and using the output of it for further development.

```jsonc
{
"version": "0.2.0",
"configurations": [
{
"type": "funkin-run-game", // Start FNF game
"request": "launch",
"name": "Compile & Run FNF mod on V-Slice engine (using wine)",
"cmd_prefix": "wine ", // Use wine to launch the game
"execName": "VSliceEngine.exe", // The exact executable name
"attachDebugger": false, // Don't add the "debug" mod
"preLaunchTask": "Funk: Compile current V-Slice mod" // Compile and copy the mod to the game
}
]
}
```
To start, use the `Funkin compiler: Make new project` command to create a new mod project. You will be asked to type in or select a folder for it.

### Extension options
Now let's take a look at the newly opened project. There are a couple of interesting files and directories in it:

These options can be configured using the "Settings UI" under the `Extensions > Funkin Compiler` section:
- `assets/mod_base`: This folder holds most of your mod's files. In structure, it's exactly the same as any other Friday Night Funkin' mod. However, some assets (like songs and scripts) have their own dedicated directories.

- `assets/fnfc_files`: Here you should put all the songs you want to include with your mod. Simply copy the `.fnfc` files of your songs, and the extension will automatically add them to your mod.

- `source`: Here you can create script files for your mod. This doesn't differ much from writing `.hxc` scripts, but:
- All scripts must have the `.hx` extension (instead of `.hxc`).

- Using [Package names](../Expert/02.ModPackages.md) is mandatory.

- `funk.cfg`: This file keeps the information about the paths to the directories we just mentioned. For instance, if you would like to move the song directory from `assets/fnfc_files` to `modSongs`, you would change the `mod_fnfc_folder` value in the config to `modSongs`.

- `checkstyle.json` and `hxformat.json`: These can be used to tweak code formatting, but this article won't go further into that.

Once you're ready to test your mod, press **F5** (or use the "Run and Debug" tab to select the run action) to both compile and launch your mod.

* `funkinCompiler.modName`: The name of your mod in the game instance. By default, it's "workbench".
* `funkinCompiler.gamePath`: Path to the game folder. (If you remove this path, you'll be asked for it again when launching an FNF instance.)
* `funkinCompiler.haxelibPath`: Path to your haxelib folder. This should be set when running the `Funkin compiler: Setup Funkin compiler` command.
If you haven't done so, you'll be asked to provide a directory with the Friday Night Funkin' instance you want to test your mod with. While it's recommended to use a fresh install of the game, nothing is stopping you from using your active instance.

By default, this will create two mods (and remove their previous copies) in the selected instance: "workbench" and "debug". In addition, your mod will also be placed in the "export" directory of your mod project.

> Author: [Mikolka](https://github.com/mikolka9144)
> Author: [Mikolka](https://github.com/mikolka9144)
Loading