Melonity Docs

Creating your first script ​

This page shows how to turn the template repository into your first working Melonity script.

Start with the example project ​

The easiest way to begin is to use the example already included in the template:

It already demonstrates several important parts of the API:

  • script registration
  • menu options
  • callbacks
  • simple rendering

TIP

Do not try to build a large script immediately. First, make sure that the example project compiles and is loaded correctly in Melonity.

Minimal script structure ​

A Melonity script usually starts with a ScriptDescription object and a call to RegisterScript:

ts
let MyScript: ScriptDescription = {};

namespace myScript {
	MyScript.OnScriptLoad = () => {
		console.log('My first script loaded');
	};

	MyScript.OnScriptUnload = () => {
		console.log('My first script unloaded');
	};

	RegisterScript(MyScript, 'My first script');
}

This is the minimum required structure for a very simple script:

  • ScriptDescription contains the callbacks used by Melonity
  • OnScriptLoad runs when the script is loaded
  • OnScriptUnload runs when the script is unloaded
  • RegisterScript registers the script in the system

IMPORTANT

Without RegisterScript, some parts of the script may still appear to work, for example menu options. However, callbacks will not work until the script is registered.

Add a simple menu option ​

In the template example, a toggle is added through Menu.AddToggle. This is a good first step because it lets you enable or disable your logic without editing the code every time.

ts
const PATH = ['Tab name', 'Nav section', 'Block name'];

let enabled = Menu.AddToggle(PATH, 'Enable', false)
	.OnChange(state => {
		enabled = state.newValue;
	})
	.GetValue();

The PATH array controls where the option appears in the Melonity menu.

Add simple script logic ​

After the script is registered, you can use callbacks such as OnUpdate and OnDraw.

Example:

ts
MyScript.OnUpdate = () => {
	if (!enabled) {
		return;
	}

	console.log('Script is running');
};

If you want to draw something on the screen, you can also use OnDraw:

ts
MyScript.OnDraw = () => {
	if (!enabled) {
		return;
	}

	Renderer.SetDrawColor(Color.YELLOW);
	Renderer.DrawFilledRect(300, 200, 120, 120, 8, Enum.RoundCorners.All);
};

IMPORTANT

OnDraw is called every frame. This means the callback runs more often at higher FPS, so heavy logic inside OnDraw can hurt performance.

Check that the script works ​

Your first script is working correctly if:

  • npm run watch recompiles the project without errors
  • the generated .js file is written to the correct scripts folder
  • the script appears in the local scripts list in Melonity
  • the script is enabled in that list
  • Melonity loads the script
  • OnScriptLoad is triggered
  • your menu option appears in the menu
  • the script reacts when you enable or disable it

TIP

If you add a new file to the scripts folder and it does not appear in the list immediately, press F7 to reload scripts.

Where to go next ​

Once the first script works, the most useful next pages are: