Monster Modules
From Monster Wiki
This is a list of modules that are built into Monster. The built-in modules cover a broad set of commonly used functions, and also provides a basic interface to the Monster VM itself. Common for all the modules is that they have very small implementations and thus add very little to the size of the library. Larger modules are purposely kept outside the library to avoid bloating it.
All the modules are optional - it is up to the application designer to select which modules to load and make available. To load all the modules (the default behavior), use the initAllModules() API call.
Contents |
Using modules
The contents of a module can be imported like this:
import io; writeln("hello world!"); // 'writeln' is part of the 'io' module
You can also access the members of a module without importing, like this:
io.writeln("hello again!");
module frames
The frames module provides information about the current rendering frame:
module frames; float time; // Time since last frame float totalTime; // Time since rendering started ulong counter; // Number of frames since program startup // Sleep a given number of frames idle fsleep(int frameNum);
The time, totalTime and counter variables are updated automatically by the system each frame (at the beginning of the vm.frame() API call.) The module is mostly useful in games and other applications that are built around a main rendering loop, and which call vm.frame() once each frame. For other applications the values will likely be pretty useless.
The idle function fsleep works exactly like timer.sleep (see below) except that it sleeps a number of rendering frames instead of seconds.
module io
The io module is used to write text to console (stdout):
module io; // Write to console, with or without a newline native write(char[][] args...); native writeln(char[][] args...); // Automatically inserts spaces between arguments native writes(char[][] args...); native writelns(char[][] args...); // Identical to writelns native print(char[][] args...);
The output functions can take any number of arguments. Example usage:
write("It's "); write('a'); writeln(" line!"); writeln(); writeln(1,2,3,4); writelns(1,2,3,4);
Result:
It's a line! 1234 1 2 3 4
module math
The math module contains various commonly used math functions and constants:
module math; double E = 2.7182818284590452354; double PI = 3.141592653589793238; double DEGTORAD = 3.141592653590/180; double RADTODEG = 180/3.141592653590; native double sin(double x); native double cos(double x); native double tan(double x); native double asin(double x); native double acos(double x); native double atan(double x); native double atan2(double y, double x); // = atan(y/x) native double sinh(double x); native double cosh(double x); native double tanh(double x); native double asinh(double x); native double acosh(double x); native double atanh(double x); native double sqrt(double x); native double exp(double x); // e^x native double exp2(double x); // 2^x native double log(double x); // base e native double log10(double x);// base 10 native double log2(double x); // base 2 native double pow(double x, double y); // x^y native double ipow(double x, int n); // x^n (faster than pow) native int abs(int x); native double fabs(double x); native double ceil(double x); native double floor(double x); native double round(double x); // rounds to nearest integer native double trunc(double x); native double hypot(double x, double y); // = sqrt(x*x+y*y) native double cbrt(double x); // cube root // Calculates polynomial a0 + x*a1 + x^2*a2 + x^3*a3 + ... native double poly(double x, float[] A);
Example usage:
writeln(sin(30*DEGTORAD)); // sine of 30 degrees = 0.5 writeln(exp2(10)); // 2^10 = 1024 writeln(poly(2, [3.0, -2, 1])); // x^2-2x+3 for x=2 gives 3
module random
This module provides simple random number generation.
module random; native uint rand(); // Return a number between 0 and uint.max, inclusive native float frand(); // Return a number between 0 and 1, inclusive // Return a random number between a and b, inclusive. Allows negative // numbers, and works with a>b, a<b and a==b native int randInt(int a, int b);
Since it's intended for game development, the number generator implementation focuses mainly on speed and simplicity over flexibility and quality. If you need non-uniform distributions or high-quality random numbers for encryption and scientific purposes, you will have to provide your own generator and interface.
module thread
The thread module (which is technically a singleton, not a module) is the main interface for manipulating the Monster VM virtual thread system. The virtual threads have nothing to do with real (aka. system) threads. Virtual threads are instead a crucial part of the Monsters cooperative multithreading system. (I will write an article explaining this later.)
Note: In most cases you do not need the thread module in order to use the virtual threading system. All idle function calls (such as to sleep, see below) use the system automatically behind the scenes, and they take care of everything for you.
singleton thread; // Used to kill or pause our own or other threads. idle kill(); idle pause(); // Get status information about a thread native bool isScheduled(); native bool isPaused(); native bool isIdle(); native bool isDead(); bool isAlive() { return !isDead(); } // Create a new (paused) thread for a given function native thread create(char[] name); // Schedule a (paused) thread to run the next frame native restart(); // Call a (paused) thread directly - returns when the thread exits or // calls an idle function. idle resume(); // Wait for a thread to finish. Will not return until the thread is // dead. idle wait(); // Call a function as a thread thread call(char[] name) { var t = create(name); t.resume(); return t; } // Start a function as a thread in the background thread start(char[] name) { var t = create(name); t.restart(); return t; }
TODO: Notice that create() et al. takes a function name as argument. This is just a temporary (and ugly!) hack until real function references are implemented. The function is looked up in the caller's class.
module timer
singleton timer; // Sleep the given number of seconds idle sleep(float secs);
The 'sleep' function suspends execution for the given number of seconds (may be a fraction). As an idle function, sleep() only suspends the current virtual thread - the rest of the program (including the rendering loop and any other running Monster scripts) are not affected. A sleeping thread has very little overhead - you may easily have hundreds (or thousands) of sleeping threads simultaneously with very little impact on performance. (To be written: an article about idle functions and virtual threading.)
