0% found this document useful (0 votes)
51 views8 pages

Script Mods

The document provides an overview of script mods in M0rtal Engine, detailing their purpose as a customizable system for managing game actions without duplicating code. It explains the structure for creating script files in JSON format, the various actions available, and how scripts can be triggered through different game events. Additionally, it outlines the use of hooks and custom timers to enhance gameplay personalization.

Uploaded by

ethansonicblue
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
51 views8 pages

Script Mods

The document provides an overview of script mods in M0rtal Engine, detailing their purpose as a customizable system for managing game actions without duplicating code. It explains the structure for creating script files in JSON format, the various actions available, and how scripts can be triggered through different game events. Additionally, it outlines the use of hooks and custom timers to enhance gameplay personalization.

Uploaded by

ethansonicblue
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

Script Mods

M0rtal Engine
UPDATED SINCE V1.1

-​ What is?
Script mods ( or scripts ) are basically a custom timer-like system with additional actions for
shared logic without the need to copy-paste for each entity.

However, scripts doesn't have a timer with it, but the lines can be controlled with the line
action, end_session for update loops, and break_session to end the script instantly, not
triggering any next actions.

Scripts were made separately from custom timer to not affect custom enemies, since scripts
focus on way more personalization for custom systems, events, etc.
It comes with a bunch of exclusive actions, to assist the creator for a better personalized
game/mappack.
- FILE CREATION AND PROPER USE
All the files read by the game are located in the “scripts” folder located in the mappack. If the
mappack was not created in M0rtal Engine, the folder can be created manually in the
mappack folder.

The files use JSON as extension, and inside the file can be putten many scripts the creator
would like.

The file is equal to the file name specified, and ID is the script inside the file.

Example :

custom_script.json :

{
​ “delete”:[
​ [[“set”,”instantdelete”],true]
​ ],

​ “freeze”:[
​ [[“set”,”frozen”],true],
​ [[“set”,”static”],true]
​ ],

If there is :
[0,[“scriptmod”,”custom_script”],”freeze”],

It will trigger the script “freeze” from the file “custom_script.json”

If either the script or file do not exist, the game will just ignore and print in the console that
the specified value does not exist.

M0RTAL-ENGINE-260219 : The game no longer crashes if the script not exist


M0RTAL-ENGINE-260219 : The game no longer crashes if the script file not exist
-​ Structure
Like custom timers, scripts follow this structure :

[action,parameter],argument]

Example :

[[“set”,”active”],false]

However, depending on the action, the structure can also change, for example :

[[“soundcategory”,”sounds”,”setvolume”],30],

The structure change applies to any action that requires more values than default.
The script runs from top to bottom, which means the top action is priority for the next action.

Structure example :

[[“if”,”runtime”,”>”,0],[“line”,”add”],3],
[[“set”,”frozen”],true],
[[“set”,”active”],false],
[[“set”,”static”],true],

* The first line checks if the value “runtime” is greater than 0. If so, 3 lines will be skipped

* Second to fourth line is what happens if the first line comparison does not pass, which in
this case is a simple freezing behavior.
List of actions :
line;controls the script execution line;set;add;subtract
[[“line”,action],value]

settarget;sets the target for next actions from the script


[[“settarget”,property or self]]

datawrite;writes a specific information in the save file


[[“datawrite”,parameter],argument]

dataload;stores a specific information from the save file into the local entity
[[“dataload”,parameter],local property target]

setglobalvalue;sets a global value into a safe space


[[“setglobalvalue”,parameter],argument]

getglobalvalue;gets and stores a global value;safe for access safe space values
[[“getglobalvalue”,parameter,”safe”(optional)],local property]

soundcategory;controls a sound category;setvolume;pause;resume;stop


[[“soundcategory”,category,action],argument]

soundsettings;controls a specific sound;setvolume;setpitch;setloop;play;pause;resume;stop


[[“soundsettings”,sound,action],argument]

openlink;opens a link from trusted links


[[“openlink”,trusted link id],argument]

List of trusted links :


youtube;discord;instagram;twitter;bluesky;neocities;stabyourself
yt;dc;insta;x;bsky;stys

Note : don't type the full link, just what's after the default link address, for example :
“[Link] will be “@oewertom” in the argument

setcamera;sets the camera;x,y;clear


[[“setcamera”,action],argument]

spawnenemy;spawns a new enemy


[[“spawnenemy”,name”]]

playsound;plays a sound
[[“playsound”,sound]]
Note : both spawnenemy and playsound only works if the target has the function. If not, the
game will crash for trying to call a function that doesn’t exist.

quitmappack;quits from the mappack


[[“quitmappack”]]

quitgame;quits from the game


[[“quitgame”]]

scriptmod;triggers a script based on the specified target


[[“scriptmod”,file],id]

scriptmodupdate;adds the script to the update list


[[“scriptmodupdate,file],id]

getmouse;returns the mouse information as a table


[[“getmouse”,target property]]
Table values : x;y;leftclick;rightclick;middleclick

getjoysticks;returns all available controllers as a table value


[[“getjoysticks”,local property]]
Table values :
leftx;lefty;rightx;righty;triggerleft;triggerright;hatup;hatdown;hatleft;hatright;hatraw

end_session;removes the script from update list but still runs the full script before removing
[[“end_session”]]

break_session;interrupts the script, cancelling any next actions


[[“break_session”]]

animationnumber;changes a value from animation numbers


[[“animationnumber”,name,operator(optional)],value]

getanimationnumber;gets and stores the animation number into the local entity
[[“getanimationnumber”,local property],name]

deltatime;stores the delta time to a local property inside the entity


[[“deltatime”,local property]]

getpi;stores the Pi ( π ) value to a local property inside the entity


[[“getpi”,local property]]
-​ Hooks and triggers
Hooks are a way to define a custom behavior based on default actions from the entity.

There are several ways a script can be triggered in game, which include load, update,
collision and via custom timer.

Script hooks have a default pattern, which includes the file name, and the ID in the file.

[file,id] | EX : [“examplescript”,”jump”]
or
“onleftcollide”:[“examplescript”,”jump”]

Collision hooks :

onleftcollide, onrightcollide, onceilcollide, onfloorcollide, onpassivecollide, onglobalcollide

When any of these are triggered, the script can access two values, “collidername” and
“colliderdata”. The values are removed right after the script is completed or interrupted.

Behavior hooks :

onstomp;when the enemy is stomped

Game hooks :

onload;when the enemy loads


onupdate;when the game updates
onkeyboard;when a keyboard key is pressed or
released;keyboardtype;keyboard;keyboardraw
keyboard = the key code + if it’s pressed or released
example : space_press, a_release
keyboardraw = the raw ID of the key
“space” would be “ “
keyboardtype;press;release = if the key is pressed or release
-​ Custom Timer
Scripts can also be triggered via custom timer, and with the possibility of defining the target
property ( if empty, will be self ).

[0,[“scriptmod”,file,target],id]
©RoundaCliff Studios
2025-2026

Common questions

Powered by AI

If a script mod in M0rtal Engine attempts to execute a function that is not present in the target, it can lead to a game crash since the game tries to call a non-existent function. This highlights the importance of ensuring that any functions the scripts attempt to use are properly defined and available, necessitating thorough testing and validation in the development process to prevent such stability issues .

Script mods in M0rtal Engine can interface with input devices through functions like 'getmouse' and 'getjoysticks', which return information on mouse position and clicks as well as joystick movements. Additionally, script hooks can capture keyboard inputs using the 'onkeyboard' hook, differentiated by key code and press/release events. These capabilities allow for dynamic interaction with the game environment, enabling real-time responses to user inputs .

The 'settarget' action in M0rtal Engine scripts defines the target entity or property for subsequent actions, allowing scripts to dynamically adjust their execution context. For example, using [["settarget",property or self]] sets the focus of upcoming actions to a specific entity or property within the game, facilitating personalized interactions and modifications within the script logic. Proper use of 'settarget' ensures that scripts effectively interact with intended targets, thus enhancing script modularity and flexibility .

The command to set a sound category's volume follows the structure [["soundcategory",category,"setvolume"],argument]. This command adjusts the volume of an entire sound category rather than individual sounds, enabling broad audio management. For individual sounds, a different action is used, namely 'soundsettings', which can control specific properties like volume, pitch, and loop for individual sound files .

'Openlink' commands in M0rtal Engine follow the structure [["openlink",trusted link id],argument], where the argument should only include the part of the URL that comes after the main site address. This implementation requires the use of predefined trusted domains like YouTube or Twitter to mitigate security risks associated with opening external resources. Developers need to ensure they utilize only the allowed domains and correctly format the link argument to prevent errors or security vulnerabilities in their applications .

Hooks in M0rtal Engine scripts enhance functionality by serving as triggers for scripts based on specific events or actions, enabling scripts to execute in response to game events without explicit calls. Examples include collision hooks like 'onleftcollide' that activate when an entity collides from the left, behavior hooks such as 'onstomp' for when an enemy is stomped, and game hooks including 'onload' or 'onupdate', capturing loading or update events respectively. These hooks allow for dynamic and context-specific script execution, providing a responsive game environment .

The run order of scripts in M0rtal Engine is critical as the scripts execute top to bottom, affecting sequence-sensitive actions. Developers can manage priority using commands such as 'line', which allows skipping or modifying the execution flow based on specific conditions or outcomes. This gives developers control over which actions take precedence, thus organizing script logic efficiently to ensure cohesive interaction within the game environment. Proper management of run order prevents conflicts and ensures the intended sequence of game behaviors .

Script mods in M0rtal Engine manage execution flow by processing actions from top to bottom, allowing for controlled execution using actions like 'line', 'end_session', and 'break_session'. 'End_session' removes the script from the update list after running, whereas 'break_session' instantly interrupts the script, preventing further actions from being triggered. This level of control allows for precise timing and conditional logic to be implemented within scripts .

Data storage commands like 'datawrite' and 'dataload' within M0rtal Engine scripts offer robust mechanisms for managing game state by writing and retrieving data from a save file. These commands ensure persistence and consistency in player experience, allowing game progress, player preferences, or configurations to be stored and accessed across sessions. Efficient implementation and management of these commands facilitate seamless continuity in gameplay, enabling dynamic adaptations to player actions or preferences .

Separating script mods from custom timers allows for greater personalization and specificity in game development, as script mods enable more complex behaviors and actions tailored to custom systems without the constraints of timing mechanisms that custom timers manage. This separation ensures custom enemies aren't affected by the generic constraints of timers, facilitating more nuanced and varied gameplay experiences. It also avoids duplication of code, reducing redundancy and potential errors .

You might also like