Skip to content

Commit 0326409

Browse files
mikolka9144Kade-github
mikolka9144
authored and
Kade-github
committed
Funkin Compiler initial article
1 parent e432934 commit 0326409

File tree

1 file changed

+185
-0
lines changed

1 file changed

+185
-0
lines changed

‎assets/content/cookbook/Community/03.FunkinCompiler.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
[tags]: / "community,tool,hscript"
2+
3+
4+
# Funkin Compiler (VSCode extension)
5+
6+
<div align="center">
7+
<img src="https://raw.githubusercontent.com/FunkinCompiler/funkin-extension/refs/heads/main/assets/icon.png" alt="Logo" width="200" height="200">
8+
</div>
9+
10+
11+
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.
12+
13+
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).
14+
15+
## Setting up
16+
17+
Make sure you have both [Haxe](https://haxe.org/download/) and [Git](https://git-scm.com/) installed.
18+
19+
Then, search for `Funkin Compiler` in the "Extensions" section of VS Code and install it.
20+
21+
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.
22+
23+
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.
24+
25+
## Using Funkin Compiler
26+
27+
The extension can work in two "modes":
28+
29+
- **"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.
30+
31+
- **"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.
32+
33+
Opening a Funkin Compiler project will enable Mode 1; opening a Friday Night Funkin' mod folder will use Mode 2 instead.
34+
35+
## Using the built-in mod template (Mode 1)
36+
37+
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.
38+
39+
Now let's take a look at the newly opened project. There are a couple of interesting files and directories in it:
40+
41+
- `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.
42+
43+
- `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.
44+
45+
- `source`: Here you can create script files for your mod. This doesn't differ much from writing `.hxc` scripts, but:
46+
47+
- All scripts must have the `.hx` extension (instead of `.hxc`).
48+
49+
- Using [Package names](../Expert/02.ModPackages.md) is mandatory.
50+
51+
- `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`.
52+
53+
- `checkstyle.json` and `hxformat.json`: These can be used to tweak code formatting, but this article won't go further into that.
54+
55+
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.
56+
57+
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.
58+
59+
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.
60+
61+
## Editing a standard Friday Night Funkin' mod (Mode 2)
62+
63+
> Please note that this mode is still in development, and as such, not everything will work correctly.
64+
65+
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.
66+
67+
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`.
68+
69+
Due to a quirk with the Haxe Language Server, trying to edit `.hxc` directly will cause some features to stop working.
70+
71+
## Features
72+
73+
> If a feature is exclusive to a specific mode, it will be noted in brackets.
74+
75+
### Hints in .json files
76+
77+
<img width="600" alt="image" src="https://raw.githubusercontent.com/FunkinCompiler/funkin-extension/refs/heads/main/readme-images/jsonc.png" />
78+
79+
Many `.json` files in your mod will get additional type hints, letting you check the syntax and see what you can type into them. Many schemas are also covered by other articles like [Note Styles](../Intermediate/02.CustomNotestyles.md), [Albums](../Intermediate/04.CustomAlbums.md), etc.
80+
81+
### Static code checking
82+
83+
<img width="600" alt="image" src="https://raw.githubusercontent.com/FunkinCompiler/funkin-extension/refs/heads/main/readme-images/staticError.png" />
84+
85+
VS Code will be able to statically check the syntax of your code and detect any misspellings or other typing errors.
86+
87+
#### Object casting
88+
89+
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:
90+
91+
```hx
92+
package mikolka;
93+
94+
// Imports here
95+
96+
class ExampleModule extends Module
97+
{
98+
public function new()
99+
{
100+
super("test module", 1000);
101+
}
102+
103+
override function onStateChangeEnd(ev:StateChangeScriptEvent)
104+
{
105+
//* Typical way to check if we're in a desired state
106+
if (Std.isOfType(ev.targetState, OptionsState))
107+
{
108+
//* We know the state's type here
109+
var setState:OptionsState = cast(ev.targetState, OptionsState);
110+
//* so we can cast to it here
111+
112+
// Additional actions on the "setState" value
113+
}
114+
}
115+
}
116+
117+
```
118+
119+
Here, we cast `ev.targetState` to `OptionsState` after confirming with `Std.isOfType` that it's actually the state we're looking for.
120+
121+
### Code autocompletion
122+
123+
<img width="600" alt="image" src="https://raw.githubusercontent.com/FunkinCompiler/funkin-extension/refs/heads/main/readme-images/autocompletion.png" />
124+
125+
When typing, you'll notice this autocompletion window appear from time to time. Using the arrow keys, you can navigate through the different ways to complete the line. You can also continue typing and press "Enter" to complete the line.
126+
127+
### Blacklist detection
128+
129+
<img width="600" alt="image" src="https://raw.githubusercontent.com/FunkinCompiler/funkin-extension/refs/heads/main/readme-images/blacklist.png" />
130+
131+
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.
132+
133+
### .FNFC Integration (Mode 1)
134+
135+
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.
136+
137+
## Customizing the extension
138+
139+
In this section, we will look into technical additions that might be useful for further customization of Funkin Compiler:
140+
141+
### Additions for launch configuration
142+
143+
* `Funk: Compile current V-Slice mod` task (not command): Compiles the currently opened Funkin Compiler project to the FNF instance.
144+
* `Funk: Export current V-Slice mod` task: Same as above, but doesn't copy the mod to the game.
145+
* `Funkin compiler: Make new project` command: As mentioned previously, creates a new Funkin Compiler project.
146+
147+
### Friday Night Funkin' debugger
148+
149+
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).
150+
151+
It can also be customized with additional configuration options. We'll look at the most important ones:
152+
153+
* `execName`: Name of the executable to launch.
154+
* `attachDebugger`: If enabled, adds the "debug" mod to your instance before starting it.
155+
* `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.
156+
157+
Here's how you can use them to customize your launch configuration:
158+
159+
```jsonc
160+
{
161+
"version": "0.2.0",
162+
"configurations": [
163+
{
164+
"type": "funkin-run-game", // Start FNF game
165+
"request": "launch",
166+
"name": "Compile & Run FNF mod on V-Slice engine (using wine)",
167+
"cmd_prefix": "wine ", // Use wine to launch the game
168+
"execName": "VSliceEngine.exe", // The exact executable name
169+
"attachDebugger": false, // Don't add the "debug" mod
170+
"preLaunchTask": "Funk: Compile current V-Slice mod" // Compile and copy the mod to the game
171+
}
172+
]
173+
}
174+
175+
```
176+
177+
### Extension options
178+
179+
These options can be configured using the "Settings UI" under the `Extensions > Funkin Compiler` section:
180+
181+
* `funkinCompiler.modName`: The name of your mod in the game instance. By default, it's "workbench".
182+
* `funkinCompiler.gamePath`: Path to the game folder. (If you remove this path, you'll be asked for it again when launching an FNF instance.)
183+
* `funkinCompiler.haxelibPath`: Path to your haxelib folder. This should be set when running the `Funkin compiler: Setup Funkin compiler` command.
184+
185+
> Author: [Mikolka](https://github.com/mikolka9144)

0 commit comments

Comments
 (0)