mirrors/Pixel-Composer
1
0
Fork 0
mirror of https://github.com/Ttanasart-pt/Pixel-Composer.git synced 2024-12-27 07:26:33 +01:00
Code Issues Projects Releases Packages Wiki Activity
Pixel-Composer/datafiles/ApolloHelp.html

989 lines
71 KiB
HTML
Raw Normal View History

globalvar
2023-03-08 07:35:51 +01:00
<html><head>
<meta charset="UTF-8">
<title>Apollo cheat sheet</title>
<meta name="viewport" content="width=device-width" />
<meta name="livenode" content="#doc" />
<meta property="theme-color" content="#FFF037" />
<meta property="og:type" content="article" />
<meta property="og:locale" content="en_us" />
<meta property="og:site_name" content="YellowAfterlife" />
<meta property="og:title" content="Apollo cheat sheet" />
<meta property="og:url" content="<!--%[url]-->" />
<meta property="og:description" content="<!--%[desc]-->" />
<script type="text/javascript">
if (document.location.host == "yal.cc" && location.protocol == "http:") {
document.location.protocol = "https:";
}
</script>
<style type="text/css">
body, #doc tt {
font: 15px 'Open Sans', sans-serif;
line-height: 1.35;
}
body {
margin: 0;
}
.main {
width: 100%;
min-height: 100%;
min-height: 100vh;
background-color: #f9f9f9;
}
.page {
max-width: 656px;
background: #ffffff;
margin: 0 auto;
padding: 8px;
box-shadow: 0 0 0 2px #eee;
min-height: 100%;
min-height: 100vh;
box-sizing: border-box;
}
.page > p:first-child {
margin-top: 0;
}
#doc, #doc ul, #doc ol {
padding-left: 0;
margin: 0;
}
#doc div ul, #doc div ol {
padding-left: 20px;
}
#doc div ul li {
list-style: disc;
list-style-image: url('data:image/svg+xml;base256,<?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" width="20px" height="1em" viewBox="0 0 20px 1em"><circle cx="17px" cy="0.675em" r="2px"/></svg>');
}
#doc .header {
display: block;
outline: none;
text-decoration: none;
margin: 0;
font-weight: 700;
font-size: 100%;
color: #458;
border-left: 2px solid #f3f3f3;/* #f9f9f9*/
padding-left: 4px;
padding-top: 1px;
padding-bottom: 1px;
cursor: pointer;
}
#doc .header::before {
display: inline-block;
content: "+";
font: 12px monospace;
border: 1px solid #458;
line-height: 11px;
height: 11px;
width: 11px;
text-align: center;
border-radius: 50%;
margin-right: 4px;
vertical-align: middle;
position: relative;
top: -1px;
}
#doc .item.open > .header::before {
content: "-";
}
#doc .item.empty > .header::before {
content: /*"·"*/" ";
}
#doc .header:hover {
border-left-color: #f3f3f3;
background: #f3f3f3;
}
#doc .header .ret-arrow {
font-weight: normal;
margin: 0 0.1em;
}
#doc a.broken {
color: red;
}
#doc p {
margin: 0;
}
#doc p + p, #doc p.pad {
margin-top: 0.5em;
}
#doc img {
max-width: 100%;
}
#doc h3 {
margin: 0.25em 0;
font-size: 125%;
font-weight: normal;
border-bottom: 1px solid #ccc;
}
#doc .content, #doc ul {
padding-left: 20px;
border-left: 2px solid #f3f3f3;
}
#doc tt {
font-weight: bold;
}
#doc pre {
font-family: Consolas, Dejavu Sans Mono, Segoe UI Mono, Ubuntu Mono, Lucida Console, monospace;
font-size: 9pt;
line-height: 1.25;
background: white;
padding: 4px 2px 4px 10px;
margin: 0;
tab-size: 4;
overflow-x: auto;
white-space: pre-wrap;
word-break: break-all;
}
#doc pre a {
text-decoration: none;
}
#doc pre a.uf {
background-color: #f7f0ff;
}
#doc pre a.kw {
background-color: #f0f7ff;
}
#doc pre a.sf, #doc pre a.sv {
background-color: #fff3f0;
}
#doc pre a:hover {
text-decoration: underline;
}
#doc abbr[title] {
text-decoration: underline;
text-decoration-color: #bbb;
text-decoration-style: double;
}
/* delay display until load */
#doc[ready] .item:not(.open) > .content {
display: none;
}
</style>
<style type="text/css" id="md_gml">
/* GameMakerLanguage */
pre.gmlmd .md { color: #7A81A9 } /* #define */
pre.gmlmd .kw { color: #008; font-weight: bold } /* keyword */
pre.gmlmd .co { color: #080 } /* comment */
pre.gmlmd .nu { color: #00f } /* number */
pre.gmlmd .nx { color: #00f } /* hex */
pre.gmlmd .st { color: #00f } /* string */
pre.gmlmd .ts { color: #00f } /* template string */
pre.gmlmd .op { color: #000 } /* operator */
pre.gmlmd .cb { color: #008; font-weight: bold } /* curly brace */
pre.gmlmd .sv { color: #800 } /* std func */
pre.gmlmd .sf { color: #800 } /* std var */
pre.gmlmd .ri { color: #0078aa } /* assets */
pre.gmlmd .uf { color: #808 } /* user func */
pre.gmlmd .uv { color: #000 } /* user var */
pre.gmlmd .lv { color: #648 } /* local var */
pre.gmlmd .fd { color: #804 } /* field */
</style>
<style type="text/css" id="night_css">
#night { display: none }
label[for="night"] {
color: blue;
text-decoration: underline;
cursor: pointer;
}
#night:checked + .main {
background-color: #405070;
}
#night:checked + .main .page {
background-color: #1A202D;
box-shadow: 0 0 0 2px #9bccff63;
color: white;
}
#night:checked + .main a,
#night:checked + .main a:visited,
#night:checked + .main #doc .header,
#night:checked + .main label[for="night"] {
color: #9DEC76;
}
#night:checked + .main #doc .header:before,
#night:checked + .main #doc h3 {
border-color: #9DEC76
}
#night:checked + .main #doc .header,
#night:checked + .main #doc .header:hover,
#night:checked + .main #doc .content,
#night:checked + .main #doc ul {
border-left-color: rgba(205,225,255,0.1);
}
#night:checked + .main #doc .header:hover,
#night:checked + .main #doc .asset:hover {
background: rgba(205,225,255,0.1);
}
#night:checked + .main div ul li {
list-style-image: url('data:image/svg+xml;base256,<?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" width="20px" height="1em" viewBox="0 0 20px 1em"><circle cx="17px" cy="0.675em" r="2px" fill="white"/></svg>');
}
#night:checked + .main pre {
color: #cccccc;
background: #000000;
border: 1px solid #3E4757;
}
#night:checked + .main pre.gmlmd .op { color: #CCCCCC }
#night:checked + .main pre.gmlmd .co { color: #5B995B }
#night:checked + .main pre.gmlmd .kw { color: #FFB871 }
#night:checked + .main pre.gmlmd .md { color: #FFB871 }
#night:checked + .main pre.gmlmd .cb { color: #FFB871 }
#night:checked + .main pre.gmlmd .sf { color: #FFB871 }
#night:checked + .main pre.gmlmd .uf { color: #FFB871 }
#night:checked + .main pre.gmlmd .nu { color: #FF8080 }
#night:checked + .main pre.gmlmd .st { color: #FCF320 }
#night:checked + .main pre.gmlmd .ts { color: #FF8080 }
#night:checked + .main pre.gmlmd .sv { color: #FF8080 }
#night:checked + .main pre.gmlmd .gv { color: #FF80FF }
#night:checked + .main pre.gmlmd .ri { color: #FF8080 }
#night:checked + .main pre.gmlmd .lv { color: #FFF899 }
#night:checked + .main pre.gmlmd .uv { color: #B2B1FF }
#night:checked + .main pre.gmlmd .fd { color: #B2B1FF }
#night:checked + .main pre.gmlmd a.uf {
background-color: #431;
}
#night:checked + .main pre.gmlmd a.kw {
background-color: #431;
}
#night:checked + .main pre.gmlmd a.sf,
#night:checked + .main pre.gmlmd a.sv {
background-color: #431;
}
</style>
<style>
.main.boxtt #doc tt {
display: inline-block;
background: #FFFBE4;
font-family: Consolas, Ubuntu Mono, Dejavu Sans Mono, Lucida Console, monospace;
font-weight: normal;
font-size: 12px;
line-height: 16px;
padding: 0 2px;
border: 1px solid #E6E0C4;
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
max-width: 100%;
word-break: break-word;
}
#night:checked + .main.boxtt #doc tt {
background-color: #000;
border-color: #5b7c9f;
color: white;
}
</style>
<noscript><style>
#doc .header::before {
display: none;
}
#doc .header:hover {
border-left-color: #f3f3f3;
background: inherit;
}
#doc { display: inherit }
#doc .item:not(.open) > .content {
display: inherit;
}
</style></noscript>
</head><body>
<input type="checkbox" id="night" checked/>
<div class="main boxtt">
<script type="text/javascript">
(function() {
var night = document.getElementById("night");
var path = "docmd night mode";
var ls = window.localStorage;
if (ls) {
night.checked = ls.getItem(path) == "true";
night.onchange = function(_) {
ls.setItem(path, "" + night.checked);
};
}
})();
</script>
<div class="page">
<p>This is a function "cheat sheet" for Apollo extension by YellowAfterlife.
The extension can be acquired from <a href="https://marketplace.yoyogames.com/assets/5192/_">GM:Marketplace</a> or <a href="https://yellowafterlife.itch.io/gamemaker-lua">itch.io</a>.
For questions/support, use forums (<a href="https://yellowafterlife.itch.io/gamemaker-lua/community">itch.io</a>, <a href="https://forum.yoyogames.com/index.php?threads/27984/">GM forums</a>), or <a href="mailto://yellowafterlife@hotmail.com">send me an email</a>.
A most up-to-date version of the manual is always <a href="https://yal.cc/r/17/lua/">available online</a>.
The extension is currently available for Windows, Linux, and Mac (experimental).</p><p>
Click on sections to expand/collapse them.<br>
Quick display controls: <a href="#" onclick="opt_none(); return false">Categories</a>
&middot; <a href="#" onclick="opt_list(); return false">Sections</a>
&middot; <a href="#" onclick="opt_all(); return false">Everything</a>
&middot; <label for="night">Toggle night mode</label><br/>
</p><div id="doc">
<!--<doc--> <style>textarea {
font: 85% monospace;
border: 1px solid #ccc;
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
margin: 0;
width: 100%;
padding: 4px;
box-sizing: border-box;
resize: vertical;
overflow-y: scroll;
word-wrap: normal;
white-space: pre;
}
pre.lua .kw1 { color: #0d8bca; font-weight: bold; }
pre.lua .co1, .lua .coMULTI { color: #888; font-weight: normal; }
pre.lua .nu0 { color: red; }
pre.lua .sy0 { color: #555; }
pre.lua .st0 { color: #008000; }
pre.lua .br0 { color: #555; }
pre.lua .op { color: #008; font-weight: bold }
#night:checked + .main pre.lua .op { color: #c0c0c0; }
#night:checked + .main pre.lua .nu0 { color: #FF8080; }
#night:checked + .main pre.lua .st0 { color: #FCF320; }
#night:checked + .main pre.lua .kw1 { color: #9DEC76; }
#night:checked + .main pre.lua .co1 { color: #5B995B; }
#night:checked + .main textarea {
color: #cccccc;
background: #000000;
border: 1px solid #3E4757;
}
.main {
background-image: url('data:image/png;base64,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');
background-position: top 20px right 20px;
background-repeat: no-repeat;
background-attachment: fixed;
}
#night:checked + .main {
background-image: url('data:image/png;base64,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
}
</style><p><div class="item"><a class="header" id="general" href="#general" title="(permalink)">General</a><div class="content"><p>
<div class="item"><a class="header" id="lua_error_handler" href="#lua_error_handler" title="(permalink)">lua_error_handler : script(text, state_id)</a><div class="content"><p>
If you assign a script into this global variable, it will be called whenever an error occurs in Lua code.
</p><p>
So you could, for instance, make a script that displays a message box with error text,
</p><pre class="gmlmd">
<span class="co">/// scr_handle_lua_error(msg, state)</span>
<span class="kw">var</span> <span class="lv">state</span> <span class="op">=</span> <span class="sv">argument1</span><span class="op">;</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="st">"A Lua error occurred: "</span> <span class="op">+</span> <span class="sv">argument0</span><span class="op">)</span><span class="op">;</span>
</pre><p>and then link it up on game start:
</p><pre class="gmlmd">
<span class="sv">lua_error_handler</span> <span class="op">=</span> <span class="uf">scr_handle_lua_error</span><span class="op">;</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_get_cwd" href="#lua_get_cwd" title="(permalink)">lua_get_cwd()<span class="ret-arrow">&#10140;</span>path</a><div class="content"><p>
Returns the current working directory (<tt>_wgetcwd</tt> on Windows, <tt>getcwd</tt> otherwise).
</p></div></div>
<div class="item"><a class="header" id="lua_set_cwd" href="#lua_set_cwd" title="(permalink)">lua_set_cwd(path)</a><div class="content"><p>
Previously <tt>lua_chdir</tt>.
</p><p>
Changes the current working directory (<tt>_wchdir</tt> on WIndows, <tt>chdir</tt> otherwise).
</p><p>
This affects where the Lua code would be reading/writing files from by default.
</p></div></div>
</p></div></div>
<div class="item"><a class="header" id="lua_state" href="#lua_state" title="(permalink)">Lua states</a><div class="content"><p>
<div class="item"><a class="header" id="lua_state_intro" href="#lua_state_intro" title="(permalink)">Introduction to states</a><div class="content"><p>
A state is a subject to most of the Apollo's functions.
</p><p>
To put it simply, a state is the Lua program along with it's variables and current execution stack.
</p></div></div>
<div class="item"><a class="header" id="lua_state_create" href="#lua_state_create" title="(permalink)">lua_state_create()<span class="ret-arrow">&#10140;</span>state_id</a><div class="content"><p>
Creates a new Lua state and returns it's ID.
</p><pre class="gmlmd">
<span class="uv">state</span> <span class="op">=</span> <span class="sf">lua_state_create</span><span class="op">(</span><span class="op">)</span><span class="op">;</span>
</pre><p>Lua' <a href="https://www.lua.org/manual/5.3/manual.html#6">standard libraries</a> are included by default.
</p><p>
If you don't want to expose certain API functions to the user, you can use <tt>lua_global_set</tt> to remove those entries:
</p><pre class="gmlmd">
<a class="sf" href="#lua_global_set">lua_global_set</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"io"</span><span class="op">,</span> <span class="sv">undefined</span><span class="op">)</span><span class="op">;</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_state_destroy" href="#lua_state_destroy" title="(permalink)">lua_state_destroy(state_id)</a><div class="content"><p>
Destroys the given state, freeing up any resources used by it.
</p><pre class="gmlmd">
<span class="sf">lua_state_destroy</span><span class="op">(</span><span class="uv">state</span><span class="op">)</span><span class="op">;</span>
</pre><p>It is generally recommended that you clean up your states once they are no longer needed to avoid memory leaks.
</p></div></div>
<div class="item"><a class="header" id="lua_thread_create" href="#lua_thread_create" title="(permalink)">lua_thread_create(state_id)<span class="ret-arrow">&#10140;</span>thread_state_id</a><div class="content"><p>
Creates a Lua "thread"-state attached to the given state.
</p><p>
Not to be confused with OS-level threads,
Lua "threads" are separate execution states sharing the data from a parent state,
coroutine-style.
</p><p>
These share indexes with states.
</p></div></div>
<div class="item"><a class="header" id="lua_thread_destroy" href="#lua_thread_destroy" title="(permalink)">lua_thread_destroy(state_id)</a><div class="content"><p>
Destroys a previously created Lua "thread"-state.
</p><p>
Technically an alias for <a href="#lua_state_destroy">lua_state_destroy</a> due to shared index space.
</p></div></div>
<div class="item"><a class="header" id="lua_state_exists" href="#lua_state_exists" title="(permalink)">lua_state_exists(state_id)</a><div class="content"><p>
Returns whether there's a state/thread with the given ID.
</p></div></div>
<div class="item"><a class="header" id="lua_reset" href="#lua_reset" title="(permalink)">lua_reset()</a><div class="content"><p>
Destroys all existing Lua states and threads.
</p><p>
This also causes newly made states to have IDs start at 0 again.
</p></div></div>
<div class="item"><span class="header">lua_state_reuse_indexes()<span class="ret-arrow">&#10140;</span>count</span><div class="content"><p>
Here's the deal: As you might know, reusing indexes can cause some really mysterious bugs
if your code accidentally continues to use an index (which is now taken up by something else).
</p><p>
So, by default, Apollo will not do that. Which, in turn, means that after states are destroyed,
4 bytes worth of data (which were onece the state's address) will continue to be reserved per state.
</p><p>
While it would take about 500 000 states to run out of memory this way,
you might prefer not to have that anyway.
</p><p>
So, calling this function will mark that memory as available again, causing Apollo to reuse the
destroyed indexes for newly created states. This will only affect indexes of states that are
destroyed as of calling the function.
</p><p>
In other words, while developing your project, you would not call this at all
(so that if you use a destroyed state, you get an obvious error), and for final release
version you would call it once in a while (such as during room transitions - to further
reduce the odds of anything going strange).
</p><p>
The function returns the number of indexes that will be reused as result.
</p></div></div>
</p></div></div>
<div class="item"><a class="header" id="lua_add" href="#lua_add" title="(permalink)">Adding Lua code</a><div class="content"><p>
<div class="item"><a class="header" id="lua_add_code" href="#lua_add_code" title="(permalink)">lua_add_code(state_id, lua_code)</a><div class="content"><p>
Attempts to compile the given snippet of Lua code, add it to given Lua state, and execute it.
Returns whether all steps succeeded.
</p><pre class="gmlmd">
<span class="sf">lua_add_code</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"print('Hello!')"</span><span class="op">)</span><span class="op">;</span>
</pre><p>Same as with other things, compilation/runtime errors are forwarded to <tt>lua_error_handler</tt> if it is defined.
</p></div></div>
<div class="item"><a class="header" id="lua_add_file" href="#lua_add_file" title="(permalink)">lua_add_file(state_id, path, chdir = true)</a><div class="content"><p>
Attempts to load and run a snippet of Lua code from the file at the given path.
</p><p>
The function mimics GMS' file handling rules, preferring files in game's save directory over the files in game's installation directory.
</p><p>
It will, however, also accept absolute paths, bypassing sandbox restrictions.
</p><p>
So, if you added an included file called "some.lua", you could then load it with
</p><pre class="gmlmd">
<span class="sf">lua_add_file</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"some.lua"</span><span class="op">)</span><span class="op">;</span>
</pre><p>If <tt>chdir</tt> is left at <tt>true</tt>, the function will automatically call <a href="#lua_chdir">lua_chdir</a> when given a relative path so that the Lua code would work with files in that directory.
</p></div></div>
</p></div></div>
<div class="item"><a class="header" id="lua_global" href="#lua_global" title="(permalink)">Using Lua variables</a><div class="content"><p>
<div class="item"><a class="header" id="lua_global_get" href="#lua_global_get" title="(permalink)">lua_global_get(state_id, name)<span class="ret-arrow">&#10140;</span>value</a><div class="content"><p>
Returns the value of the state's given global variable.
</p><p>
Note that this returns <tt>undefined</tt> for unsupported types.
</p><pre class="gmlmd">
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"test = 'Hello!'"</span><span class="op">)</span><span class="op">;</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="sf">lua_global_get</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"test"</span><span class="op">)</span><span class="op">)</span><span class="op">;</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_global_set" href="#lua_global_set" title="(permalink)">lua_global_set(state_id, name, value)</a><div class="content"><p>
Changes the value of the state's given global variable.
</p><pre class="gmlmd">
<span class="sf">lua_global_set</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"test"</span><span class="op">,</span> <span class="st">"Hello!"</span><span class="op">)</span><span class="op">;</span>
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"print(test)"</span><span class="op">)</span><span class="op">;</span> <span class="co">// 'Hello!'</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_global_type" href="#lua_global_type" title="(permalink)">lua_global_type(state_id, name)<span class="ret-arrow">&#10140;</span>lua_type</a><div class="content"><p>
Returns the type of a state's global variable as a constant.
</p><p>
Possible values are as following: </p><ul>
<li> <tt>lua_type_none</tt>: placeholder for type ID 0
</li><li> <tt>lua_type_nil</tt>: an equivalent of GML's <tt>undefined</tt>. Not-yet-set values are <tt>nil</tt>.
</li><li> <tt>lua_type_bool</tt>: a boolean value (true or false).
</li><li> <tt>lua_type_number</tt>: a numeric type, same as GML's real.
</li><li> <tt>lua_type_string</tt>: same as GML's string type.
</li><li> <tt>lua_type_table</tt>: a Lua <a href="https://www.lua.org/manual/5.3/manual.html#2.1">table</a> (array or dictionary).
</li><li> <tt>lua_type_function</tt>: a Lua function (that can be called via <a href="#lua_call">lua_call</a> group).
</li><li> <tt>lua_type_thread</tt>: a Lua "thread"/coroutine.
</li><li> <tt>lua_type_userdata</tt>: an external reference (see Lua doc).
</li><li> <tt>lua_type_lightuserdata</tt>: an external struct (see Lua doc).
</li><li> <tt>lua_type_unknown</tt>: unrecognized type (never returns with normal Lua library)
</li></ul><p>
If the state does not exist, an error is thrown.
</p><pre class="gmlmd">
<span class="kw">if</span> <span class="op">(</span><span class="sf">lua_global_type</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"test"</span><span class="op">)</span> <span class="op">==</span> <span class="uv">lua_type_function</span><span class="op">)</span> <span class="cb">{</span>
<a class="sf" href="#lua_call">lua_call</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"test"</span><span class="op">)</span><span class="op">;</span>
<span class="cb">}</span> <span class="kw">else</span> <span class="sf">show_debug_message</span><span class="op">(</span><span class="st">"The state does not have a function called `test`!"</span><span class="op">)</span><span class="op">;</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_global_typeof" href="#lua_global_typeof" title="(permalink)">lua_global_typeof(state_id, name)<span class="ret-arrow">&#10140;</span>type_name</a><div class="content"><p>
Returns the type of a state's global variable as a string.
</p><p>
Outside of debugging, you should prefer to use <a href="#lua_global_type">lua_global_type</a>, as numeric comparisons are much faster than string comparisons.
</p><p>
The usual returned values are as following:
</p><ul>
<li> <tt>"nil"</tt>: an equivalent of GML's <tt>undefined</tt>. Not-yet-set values are <tt>nil</tt>.
</li><li> <tt>"boolean"</tt>: a boolean value (true or false).
</li><li> <tt>"number"</tt>: a numeric type, same as GML's real.
</li><li> <tt>"string"</tt>: same as GML' string type.
</li><li> <tt>"table"</tt>: a Lua <a href="https://www.lua.org/manual/5.3/manual.html#2.1">table</a>. You currently can't do much with these from GML side.
</li><li> <tt>"function"</tt>: a Lua function - as such, a thing that could be called via <tt>lua_call</tt>.
</li><li> <tt>"thread"</tt>: a Lua "thread"/coroutine (more on these later).
</li></ul><p>
So you could use a snippet like this to check if a state has a function named "test":
</p><pre class="gmlmd">
<span class="kw">if</span> <span class="op">(</span><span class="sf">lua_global_typeof</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"test"</span><span class="op">)</span> <span class="op">==</span> <span class="st">"function"</span><span class="op">)</span> <span class="cb">{</span>
<a class="sf" href="#lua_call">lua_call</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"test"</span><span class="op">)</span><span class="op">;</span>
<span class="cb">}</span> <span class="kw">else</span> <span class="sf">show_debug_message</span><span class="op">(</span><span class="st">"The state does not have a function called `test`!"</span><span class="op">)</span><span class="op">;</span>
</pre></div></div>
</p></div></div>
<div class="item"><a class="header" id="lua_call" href="#lua_call" title="(permalink)">Calling Lua code</a><div class="content"><p>
<div class="item"><a class="header" id="lua_call" href="#lua_call" title="(permalink)">lua_call(state_id, name, ...arguments)</a><div class="content"><p>
Attempts to call a Lua function stored in the given global variable of the state.
</p><p>
Returns the first of the function's returned values.
</p><p>
If an error occurs, calls <tt>lua_error_handler</tt> and returns <tt>undefined</tt>.
</p><pre class="gmlmd">
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"function greet(s) return 'Hello, ' .. s end"</span><span class="op">)</span><span class="op">;</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="sf">lua_call</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"greet"</span><span class="op">,</span> <span class="st">"GameMaker"</span><span class="op">)</span><span class="op">)</span><span class="op">;</span>
</pre><p>If the function returns multiple values, the first one returned (use <a href="#lua_call_m">lua_call_m</a> / <a href="#lua_call_xm">lua_call_xm</a> / <a href="#lua_call_wm">lua_call_wm</a> / <a href="#lua_call_wxm">lua_call_wxm</a> to support multiple returned values).
</p><p>
If the function returns no values, you get an <tt>undefined</tt>.
</p></div></div>
<div class="item"><a class="header" id="lua_call_w" href="#lua_call_w" title="(permalink)">lua_call_w(state_id, name, argument_array)</a><div class="content"><p>
Like <a href="#lua_call">lua_call</a>, but allows to pass in the arguments as an array.
</p><pre class="gmlmd">
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"function add(a, b) return a + b end"</span><span class="op">)</span><span class="op">;</span>
<span class="kw">var</span> <span class="lv">args</span> <span class="op">=</span> <span class="sf">array_create</span><span class="op">(</span><span class="nu">2</span><span class="op">,</span> <span class="nu">7</span><span class="op">)</span><span class="op">;</span> <span class="co">// [7, 7]</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="sf">lua_call_w</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"add"</span><span class="op">,</span> <span class="lv">args</span><span class="op">)</span><span class="op">)</span><span class="op">;</span> <span class="co">// 14</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_call_m" href="#lua_call_m" title="(permalink)">lua_call_m(state_id, name, ...arguments)<span class="ret-arrow">&#10140;</span>results_array</a><div class="content"><p>
Like <a href="#lua_call">lua_call</a>, but packs returned value(s) into an array.
</p><pre class="gmlmd">
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"function multi(v) return v, 1, 2 end"</span><span class="op">)</span><span class="op">;</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="sf">lua_call_m</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"multi"</span><span class="op">,</span> <span class="st">"test"</span><span class="op">)</span><span class="op">)</span><span class="op">;</span> <span class="co">// ["test", 1, 2]</span>
</pre><p>Returns the array with value(s) or an empty array if the function returned nothing.
</p></div></div>
<div class="item"><a class="header" id="lua_call_xm" href="#lua_call_xm" title="(permalink)">lua_call_xm(state_id, name, results_array, ...arguments)<span class="ret-arrow">&#10140;</span>results_count</a><div class="content"><p>
Like <a href="#lua_call_m">lua_call_m</a>, but instead writes returned value(s) into the specified array.
</p><p>
This allows to reuse the same array for frequently performed operations.
</p><p>
Returns the number of values written to the array.
</p><pre class="gmlmd">
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"function multi(v) return v, 1, 2 end"</span><span class="op">)</span><span class="op">;</span>
<span class="kw">var</span> <span class="lv">arr</span> <span class="op">=</span> <span class="sf">array_create</span><span class="op">(</span><span class="nu">5</span><span class="op">)</span><span class="op">;</span>
<span class="kw">var</span> <span class="lv">n</span> <span class="op">=</span> <span class="sf">lua_call_xm</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"multi"</span><span class="op">,</span> <span class="lv">arr</span><span class="op">,</span> <span class="st">"test"</span><span class="op">)</span><span class="op">;</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="lv">arr</span><span class="op">)</span><span class="op">;</span> <span class="co">// ["test", 1, 2, 0, 0]</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="lv">n</span><span class="op">)</span><span class="op">;</span> <span class="co">// 3</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_call_wm" href="#lua_call_wm" title="(permalink)">lua_call_wm(state_id, name, argument_array)<span class="ret-arrow">&#10140;</span>results_array</a><div class="content"><p>
A combination of <a href="#lua_call_w">lua_call_w</a> and <a href="#lua_call_m">lua_call_m</a> - takes arguments as an array and returns a new array with returned values.
</p></div></div>
<div class="item"><a class="header" id="lua_call_wxm" href="#lua_call_wxm" title="(permalink)">lua_call_wxm(state_id, name, argument_array, results_array)<span class="ret-arrow">&#10140;</span>results_count</a><div class="content"><p>
A combination of <a href="#lua_call_w">lua_call_w</a> and <a href="#lua_call_xm">lua_call_xm</a> - takes arguments as an array, writes results to another array, and returns the number of results written.
</p></div></div>
</p></div></div>
<div class="item"><a class="header" id="Exposing-GML-to-Lua" href="#Exposing-GML-to-Lua" title="(permalink)">Exposing GML to Lua</a><div class="content"><p>
<div class="item"><a class="header" id="lua_add_function" href="#lua_add_function" title="(permalink)">lua_add_function(state_id, name, script_id)</a><div class="content"><p>
Exposes the given GM script to a Lua state as a global function.
</p><p>
For example, if you have some
</p><pre class="gmlmd">
<span class="co">/// scr_alert(text)</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="sv">argument0</span><span class="op">)</span><span class="op">;</span>
</pre><p>you could expose it to Lua via
</p><pre class="gmlmd">
<span class="sf">lua_add_function</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"alert"</span><span class="op">,</span> <span class="uf">scr_alert</span><span class="op">)</span><span class="op">;</span>
</pre><p>If you want to organize your functions in Lua-like modules, you can use lua_add_code for that:
</p><pre class="gmlmd">
<span class="sf">lua_add_function</span><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"game_alert"</span><span class="op">,</span> <span class="uf">scr_alert</span><span class="op">)</span><span class="op">;</span>
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">'
game = { alert: game_alert }
'</span><span class="op">)</span><span class="op">;</span>
</pre><p>which would then allow you to do
</p> <pre class="lua"><span class="kw1">game</span>.<span class="kw1">alert</span><span class="op">(</span><span class="st0">"Hello!"</span><span class="op">)</span></pre><p>on Lua side of things.
</p></div></div>
<div class="item"><a class="header" id="lua_return" href="#lua_return" title="(permalink)">lua_return(...values)</a><div class="content"><p>
Lua <a href="https://www.lua.org/manual/5.3/manual.html#3.3.4">allows to</a> return multiple values from a function call at once.
</p><p>
This function helps to do that in scripts exposed to Lua via <tt>lua_add_function</tt>.
</p><p>
So, you could have
</p><pre class="gmlmd">
<span class="co">/// lengthdir_xy(len, dir)</span>
<span class="kw">var</span> <span class="lv">len</span> <span class="op">=</span> <span class="sv">argument0</span><span class="op">,</span> <span class="lv">dir</span> <span class="op">=</span> <span class="sv">argument1</span><span class="op">;</span>
<span class="kw">return</span> <span class="sf">lua_return</span><span class="op">(</span><span class="sf">lengthdir_x</span><span class="op">(</span><span class="lv">len</span><span class="op">,</span> <span class="lv">dir</span><span class="op">)</span><span class="op">,</span> <span class="sf">lengthdir_y</span><span class="op">(</span><span class="lv">len</span><span class="op">,</span> <span class="lv">dir</span><span class="op">)</span><span class="op">)</span><span class="op">;</span>
</pre><p>expose it via
</p><pre class="gmlmd">
<a class="sf" href="#lua_add_function">lua_add_function</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"lengthdir_xy"</span><span class="op">,</span> <span class="uv">lengthdir_xy</span><span class="op">)</span><span class="op">;</span>
</pre><p>and use it from Lua side like
</p>
<pre class="lua"><span class="kw1">local</span> x<span class="op">,</span> y <span class="op">=</span> <span class="kw1">lengthdir_xy</span><span class="op">(</span><span class="nu0">30</span><span class="op">,</span> <span class="nu0">45</span><span class="op">)</span>
<span class="kw1">print</span><span class="op">(</span>x<span class="op">,</span> y<span class="op">)</span> <span class="co1">-- 21.21, -21.21</span></pre>
</div></div>
<div class="item"><a class="header" id="lua_return_w" href="#lua_return_w" title="(permalink)">lua_return_w(values:array)</a><div class="content"><p>
Same as aforementioned <tt>lua_return</tt>, but returns the contents of an array as a value list instead.
Note this will not work for nested arrays, however.
</p></div></div>
<div class="item"><a class="header" id="lua_return_add" href="#lua_return_add" title="(permalink)">lua_return_add(...values)</a><div class="content"><p>
Add zero or more values to the list of returned values.
</p><p>
This is particularly handy for any GML operations that are done in a loop, e.g.
</p><pre class="gmlmd">
<span class="co">/// instance_find_all(obj)</span>
<span class="kw">with</span> <span class="op">(</span><span class="sv">argument0</span><span class="op">)</span> <span class="sf">lua_return_add</span><span class="op">(</span><span class="sv">id</span><span class="op">)</span><span class="op">;</span>
<span class="kw">return</span> <span class="sf">lua_return_add</span><span class="op">(</span><span class="op">)</span><span class="op">;</span>
</pre><p>The last line with an empty <tt>lua_return_add</tt> is needed to return 0 values if loop matches no instances (as runtime would otherwise assume that you are going to return something with a regular <tt>return</tt>).
</p></div></div>
<div class="item"><a class="header" id="lua_bool" href="#lua_bool" title="(permalink)">lua_bool(value)</a><div class="content"><p>
While Lua has a separate boolean type, GameMaker uses <tt>1</tt> as true-value and <tt>0</tt> as false-value.
This makes it hard to tell whether you were meaning to send <tt>1</tt> or <tt>true</tt>.
</p><p>
So there's this function, which returns either a <tt>lua_true</tt> or a <tt>lua_false</tt> depending on argument, which can be told apart by the extension explicitly, and will become the according Lua values once sent to Lua.
</p></div></div>
<div class="item"><a class="header" id="lua_current" href="#lua_current" title="(permalink)">lua_current</a><div class="content"><p>
When a Lua state calls the exposed GML script, this variable holds the ID of the "caller" state. Can be used if you want to do anything aside of just returning value(s).
</p></div></div>
<div class="item"><a class="header" id="lua_show_error" href="#lua_show_error" title="(permalink)">lua_show_error(text)</a><div class="content"><p>
Sends an error message to the currently executing Lua state.
</p><p>
This should only be used inside scripts exposed via <a href="#lua_add_function">lua_add_function</a>.
</p><pre class="gmlmd">
<span class="co">/// scr_variable_global_get(name)</span>
<span class="kw">if</span> <span class="op">(</span><span class="sf">is_string</span><span class="op">(</span><span class="sv">argument0</span><span class="op">)</span><span class="op">)</span> <span class="cb">{</span>
<span class="kw">return</span> <span class="sf">variable_global_get</span><span class="op">(</span><span class="sv">argument0</span><span class="op">)</span><span class="op">;</span>
<span class="cb">}</span> <span class="kw">else</span> <span class="sf">lua_show_error</span><span class="op">(</span><span class="st">"Expected a variable name to be a string."</span><span class="op">)</span><span class="op">;</span>
</pre></div></div>
<div class="item"><a class="header" id="Using-GM-instance-variables-from-Lua" href="#Using-GM-instance-variables-from-Lua" title="(permalink)">Using GM instance variables from Lua</a><div class="content"><p>
If you are using GameMaker Studio 2 or an Early Access version of GameMaker: Studio 1, you can have Lua directly read and write variables on GameMaker instances.
</p><p>
To do so, you would add three scripts to your project:
</p><pre class="gmlmd">
<span class="co">/// ref_variable_instance_get(context, name)</span>
<span class="kw">var</span> <span class="lv">q</span> <span class="op">=</span> <span class="sv">argument0</span><span class="op">,</span> <span class="lv">s</span> <span class="op">=</span> <span class="sv">argument1</span><span class="op">;</span>
<span class="kw">with</span> <span class="op">(</span><span class="lv">q</span><span class="op">)</span> <span class="kw">return</span> <span class="sf">variable_instance_get</span><span class="op">(</span><span class="sv">id</span><span class="op">,</span> <span class="lv">s</span><span class="op">)</span><span class="op">;</span>
<span class="kw">if</span> <span class="op">(</span><span class="lv">q</span> <span class="op">&lt;</span> <span class="nu">100000</span><span class="op">)</span> <span class="cb">{</span>
<a class="sf" href="#lua_show_error">lua_show_error</a><span class="op">(</span><span class="st">"Couldn't find any instances of "</span> <span class="op">+</span> <span class="sf">string</span><span class="op">(</span><span class="lv">q</span><span class="op">)</span>
<span class="op">+</span> <span class="st">" ("</span> <span class="op">+</span> <span class="sf">object_get_name</span><span class="op">(</span><span class="lv">q</span><span class="op">)</span> <span class="op">+</span> <span class="st">")"</span><span class="op">)</span><span class="op">;</span>
<span class="cb">}</span> <span class="kw">else</span> <a class="sf" href="#lua_show_error">lua_show_error</a><span class="op">(</span><span class="st">"Couldn't find instance "</span> <span class="op">+</span> <span class="sf">string</span><span class="op">(</span><span class="lv">q</span><span class="op">)</span><span class="op">)</span><span class="op">;</span>
<span class="kw">return</span> <span class="sv">undefined</span><span class="op">;</span>
</pre><p>(reads a variable from an instance),
</p><pre class="gmlmd">
<span class="co">/// ref_variable_instance_set(context, name, value)</span>
<span class="kw">var</span> <span class="lv">q</span> <span class="op">=</span> <span class="sv">argument0</span><span class="op">,</span> <span class="lv">s</span> <span class="op">=</span> <span class="sv">argument1</span><span class="op">,</span> <span class="lv">v</span> <span class="op">=</span> <span class="sv">argument2</span><span class="op">,</span> <span class="lv">n</span> <span class="op">=</span> <span class="nu">0</span><span class="op">;</span>
<span class="kw">with</span> <span class="op">(</span><span class="lv">q</span><span class="op">)</span> <span class="cb">{</span> <span class="sf">variable_instance_set</span><span class="op">(</span><span class="sv">id</span><span class="op">,</span> <span class="lv">s</span><span class="op">,</span> <span class="lv">v</span><span class="op">)</span><span class="op">;</span> <span class="lv">n</span><span class="op">++</span><span class="op">;</span> <span class="cb">}</span>
<span class="kw">if</span> <span class="op">(</span><span class="lv">n</span><span class="op">)</span> <span class="kw">exit</span><span class="op">;</span>
<span class="kw">if</span> <span class="op">(</span><span class="lv">q</span> <span class="op">&lt;</span> <span class="nu">100000</span><span class="op">)</span> <span class="cb">{</span>
<a class="sf" href="#lua_show_error">lua_show_error</a><span class="op">(</span><span class="st">"Couldn't find any instances of "</span> <span class="op">+</span> <span class="sf">string</span><span class="op">(</span><span class="lv">q</span><span class="op">)</span>
<span class="op">+</span> <span class="st">" ("</span> <span class="op">+</span> <span class="sf">object_get_name</span><span class="op">(</span><span class="lv">q</span><span class="op">)</span> <span class="op">+</span> <span class="st">")"</span><span class="op">)</span><span class="op">;</span>
<span class="cb">}</span> <span class="kw">else</span> <a class="sf" href="#lua_show_error">lua_show_error</a><span class="op">(</span><span class="st">"Couldn't find instance "</span> <span class="op">+</span> <span class="sf">string</span><span class="op">(</span><span class="lv">q</span><span class="op">)</span><span class="op">)</span><span class="op">;</span>
</pre><p>(writes a variable to an instance(s)),
</p><pre class="gmlmd">
<span class="co">/// ref_variable_instance_init(lua_state)</span>
<span class="kw">var</span> <span class="lv">q</span> <span class="op">=</span> <span class="sv">argument0</span><span class="op">;</span>
<a class="sf" href="#lua_add_function">lua_add_function</a><span class="op">(</span><span class="lv">q</span><span class="op">,</span> <span class="st">"variable_instance_get"</span><span class="op">,</span> <span class="uv">ref_variable_instance_get</span><span class="op">)</span><span class="op">;</span>
<a class="sf" href="#lua_add_function">lua_add_function</a><span class="op">(</span><span class="lv">q</span><span class="op">,</span> <span class="st">"variable_instance_set"</span><span class="op">,</span> <span class="uv">ref_variable_instance_set</span><span class="op">)</span><span class="op">;</span>
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="lv">q</span><span class="op">,</span> <span class="st">'-- ref_variable_instance_init()
__idfields = __idfields or { };
debug.setmetatable(0, {
__index = function(self, name)
if (__idfields[name]) then
return _G[name];
else
return variable_instance_get(self, name);
end
end,
__newindex = variable_instance_set,
})
'</span><span class="op">)</span><span class="op">;</span>
</pre><p>(exposes the above scripts to a Lua state and sets it up to use them when trying to read/write a field on a numeric value (id)).
</p><p>
Then you can use them as following:
</p><pre class="gmlmd">
<span class="co">// create a Lua state:</span>
<span class="uv">state</span> <span class="op">=</span> <a class="sf" href="#lua_state_create">lua_state_create</a><span class="op">(</span><span class="op">)</span><span class="op">;</span>
<span class="co">// allow the state to work with GM instances:</span>
<span class="uf">ref_variable_instance_init</span><span class="op">(</span><span class="uv">state</span><span class="op">)</span><span class="op">;</span>
<span class="co">// add a test function to the state -</span>
<span class="co">// function takes an instance and modifies it's `result` variable.</span>
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"function test(q) q.result = 'Hello!' end"</span><span class="op">)</span><span class="op">;</span>
<span class="co">// call the test-function for the current instance and display the result:</span>
<span class="uv">result</span> <span class="op">=</span> <span class="st">""</span><span class="op">;</span>
<a class="sf" href="#lua_call">lua_call</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"test"</span><span class="op">,</span> <span class="sv">id</span><span class="op">)</span><span class="op">;</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="uv">result</span><span class="op">)</span><span class="op">;</span>
</pre></div></div>
</p>
<script type="text/javascript">(function(){function v(a,b){var l=a.exec(b);return null!=l?l[1]:null}window.luaScriptGen=function(a){var b,l,y=RegExp("^[aeouiy]","g"),f="",f=f+"var state = argument0;\n",m=[],w="",g;b=RegExp("^[ \\t]*(\\w+)[ \\t]*(?:#|=[ \\t]*([^\n;]+))[ \\t]*$","gm");a.replace(b,function(a,b,d){null==d&&(d=b);f+='lua_global_set(state, "'+b+'", '+d+");\n";return a});l=RegExp(":[ \\t]*(\\w+)","g");b=RegExp("^[ \\t]*(:)?[ \\t]*(\\w+)(?:[ \\t]*:[ \\t]*(\\w+))?[ \\t]*\\(([^\n)]*)\\)[ \\t]*(:[ \\t]*(\\w*)[ \\t]*)?[;]?[ \\t]*$",
"gm");a.replace(b,function(b,a,d,g,c,q,n){a=null!=a;null==g&&(g=d);var e=c;n=(q=null!=q)&&"bool"==n.toLowerCase();a&&(m.push(d),""!=e&&(e=", "+e),e="self"+e);f+='lua_add_function(state, "'+d+'", ref_'+d+");\n";c=""+("\n#define ref_"+d+"\n/// "+d+"("+e+")\n");var r;r=""!=e?e.split(","):[];e=r.length;c+="if (argument_count != "+e+") return "+('lua_show_error("'+d+": Expected "+e+" argument")+(1!=e?"s":"")+', got " + string(argument_count));\n';for(var h=-1;++h<e;){var x=r[h],p=v(l,x);if(null!=p){var k;
switch(p){case "bool":case "color":case "float":case "id":case "index":case "int":case "number":case "real":k=["is_real","is_int64"];break;case "string":k=["is_string"];break;default:k=null}if(null!=k){var t="argument"+h;c+="if !(";for(var u=0;u<k.length;c+=k[u++]+"("+t+")")0<u&&(c+=" || ");c+=""+(') return lua_show_error("'+d+": Expected "+(null!=v(y,p)?"an":"a")+(" "+p+" for "+t+" (")+x.trim()+('), got " + lua_print_value('+t+"));\n"))}}}a&&(c+="with (argument0) ");q&&(c+="return ");n&&(c+="lua_bool(");
c+=g+"(";for(h=d=a?1:0;h<e;c+="argument"+h++)h>d&&(c+=", ");n&&(c+=")");w+=""+(c+");\n");return b});b=m.length;if(0<b)for(a=0;a<b;f+="end');\n")for(g=m[a++],f+="lua_add_code(state, 'if (__idfields ~= nil) then\n",a=0;a<b;f+=" __idfields."+g+" = true;\n")g=m[a++];return f+=""+w}})();</script>
<p><div class="item"><a class="header" id="lua-gen" href="#lua-gen" title="(permalink)">Automatically exposing scripts/functions</a><div class="content"><p>
If you are building a medium-scale scripting API, you may find yourself needing to expose a large number of scripts (and/or built-in functions), as well as introducing argument type checking to prevent GML-side errors.
</p><p>
To save you from having to deal with that, Apollo includes a small utility that generates wrapper and loader scripts.
</p><p>
It accepts function definitions in <tt>funcname(arg1:type1, arg2:type2, ...):rtype</tt>,
</p><ul>
<li> <tt>arg1, arg2, ...</tt>: argument names. Will be shown in errors returned to Lua.
</li><li> <tt>type1, type2, ...</tt>: argument types. Optional.
If defined, code will be added to ensure that each argument matches it's type.
Known types are <tt>real</tt>, <tt>bool</tt>, <tt>string</tt>;
<tt>color</tt>, <tt>int</tt>, <tt>index</tt>, <tt>id</tt> can also be used, but are treated same as real.
</li><li> <tt>rtype</tt>: returned type, if the function returns a specific one.
If set to <tt>bool</tt>, return-statement will be wrapped in <tt>lua_bool</tt> call.
</li><li> If prefixed with <tt>:</tt>, function will be marked as "instance function" and will accept an instance ID as first argument, also allowing to call it as <tt>inst.func(...)</tt> if instance access scripts are set up.
</li></ul><p>
Constants can be defined either as <tt>name#</tt> (uses the value of same-named constant/variable) or <tt>name = value</tt> (computes the given GML value at inclusion time).
</p><p>
The tool is included with the extension as <tt>ApolloGen.exe</tt>;
</p><p>
A web-based version is available below:
</p> <textarea rows="7" id="gen_in" onchange="">// Examples:
show_debug_message(value)
is_string(value):bool
string_lower(s:string):
clamp(val:number, min:number, max:number):
:instance_destroy()
:motion_add(dir:number, speed:number)
c_white#
game_version = 1000</textarea><p>Whenever the contents of above field are changed, updated loader script will be output into the field below:
</p> <textarea rows="7" id="gen_out"></textarea><p>You can then save them into a .gml file and import it to your project.
</p> <script>(function() {
function proc() { gen_out.value = luaScriptGen(gen_in.value); }
gen_in.onchange = proc;
proc();
})();</script></div></div>
</p></div></div>
<div class="item"><a class="header" id="Writing-Lua-code" href="#Writing-Lua-code" title="(permalink)">Writing Lua code</a><div class="content"><p>
<div class="item"><a class="header" id="Learning-Lua" href="#Learning-Lua" title="(permalink)">Learning Lua</a><div class="content"><p>
<a href="https://www.lua.org/start.html">"getting started"</a> page on the Lua' website houses a large collection of links to tutorials, wikis, and other learning materials.
</p><p>
<a href="https://www.lua.org/manual/5.3/manual.html">Lua Manual</a> provides detailed explanations on how internal elements and all standard functions lf the language work.
</p></div></div>
<div class="item"><a class="header" id="Translating-GML-to-Lua" href="#Translating-GML-to-Lua" title="(permalink)">Translating GML to Lua</a><div class="content"><p>
If you have pre-existing GML code that you'd like to quickly port for use with Apollo, I have also developed an <a href="http://yal.cc/r/17/lua/gen/">online GML-&gt;Lua compiler</a>.
</p><p>
While automatic conversion won't make extensive use of Lua-specific language features, it produces functional code in vast majority of cases and the output is clean enough to tweak it manually if needed.
</p></div></div>
</p></div></div>
<div class="item"><a class="header" id="Lua-coroutines" href="#Lua-coroutines" title="(permalink)">Lua coroutines</a><div class="content"><p>
<div class="item"><a class="header" id="A-summary-on-Lua-coroutines" href="#A-summary-on-Lua-coroutines" title="(permalink)">A summary on Lua coroutines</a><div class="content"><p>
A <a href="https://en.wikipedia.org/wiki/Coroutine">coroutine</a>, in short, is a function that can pause/resume execution at arbitrary points. These can be used for iterators, cutscenes (pausing/resuming allows to write timing in an intuitive way), tweening, AI, or anything else that benefits from maintaining the state across multi-call execution.
</p></div></div>
<div class="item"><a class="header" id="lua_thread_create" href="#lua_thread_create" title="(permalink)">lua_thread_create(state_id)</a><div class="content"><p>
Creates a "thread" state for the given Lua state and returns it's ID.
</p><p>
Such "threads" share the global context (variables, functions, etc.) with their parent state, but have their own clal stack, meaning that they can do their own thing (namely, executing coroutines) while the parent state does something else.
</p><pre class="gmlmd">
<span class="uv">thread</span> <span class="op">=</span> <span class="sf">lua_thread_create</span><span class="op">(</span><span class="uv">state</span><span class="op">)</span><span class="op">;</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_thread_destroy" href="#lua_thread_destroy" title="(permalink)">lua_thread_destroy(state_id)</a><div class="content"><p>
Destroys a previously created "thread" state.
</p><p>
Does not free resources of the parent state, only what was owned by the thread itself.
Is a convenience function and is interchangeable with <tt>lua_state_destroy</tt>.
</p></div></div>
<div class="item"><a class="header" id="lua_call_start" href="#lua_call_start" title="(permalink)">lua_call_start(state_id, name, ...arguments)</a><div class="content"><p>
Starts a coroutine call on the given sate, returns whether the operation succeeded.
</p><p>
Note that some functions will work oddly (or not work at all) on a state that is currently amidst the coroutine call, which is why you should generally create a thread for the coroutine call.
</p></div></div>
<div class="item"><a class="header" id="lua_call_start_w" href="#lua_call_start_w" title="(permalink)">lua_call_start_w(state_id, name, arguments:array)</a><div class="content"><p>
Same as <tt>lua_call_start</tt>, but takes arguments as an array.
</p></div></div>
<div class="item"><a class="header" id="lua_call_next" href="#lua_call_next" title="(permalink)">lua_call_next(state_id)</a><div class="content"><p>
Executes the next iteration on the given state and returns whether the coroutine call is ongoing (as opposed to finishing or encountering a runtime error).
</p><p>
The general scheme of performing coroutine calls is thus as following:
</p><pre class="gmlmd">
<a class="sf" href="#lua_add_code">lua_add_code</a><span class="op">(</span><span class="uv">state</span><span class="op">,</span> <span class="st">"
function test(num)
for i = 1, num do
coroutine.yield(i)
end
return 'rad!'
end
"</span><span class="op">)</span><span class="op">;</span>
<span class="uv">th</span> <span class="op">=</span> <a class="sf" href="#lua_thread_create">lua_thread_create</a><span class="op">(</span><span class="uv">state</span><span class="op">)</span><span class="op">;</span>
<span class="kw">if</span> <span class="op">(</span><a class="sf" href="#lua_call_start">lua_call_start</a><span class="op">(</span><span class="uv">th</span><span class="op">,</span> <span class="st">"test"</span><span class="op">,</span> <span class="nu">4</span><span class="op">)</span><span class="op">)</span> <span class="cb">{</span>
<span class="kw">while</span> <span class="op">(</span><span class="sf">lua_call_next</span><span class="op">(</span><span class="uv">th</span><span class="op">)</span><span class="op">)</span> <span class="cb">{</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="st">"yield: "</span> <span class="op">+</span> <span class="sf">string</span><span class="op">(</span><a class="sv" href="#lua_call_result">lua_call_result</a><span class="op">)</span><span class="op">)</span><span class="op">;</span>
<span class="cb">}</span>
<span class="sf">show_debug_message</span><span class="op">(</span><span class="st">"result: "</span> <span class="op">+</span> <span class="sf">string</span><span class="op">(</span><a class="sv" href="#lua_call_result">lua_call_result</a><span class="op">)</span><span class="op">)</span><span class="op">;</span>
<span class="cb">}</span>
<a class="sf" href="#lua_thread_destroy">lua_thread_destroy</a><span class="op">(</span><span class="uv">th</span><span class="op">)</span><span class="op">;</span>
</pre></div></div>
<div class="item"><a class="header" id="lua_call_result" href="#lua_call_result" title="(permalink)">lua_call_result</a><div class="content"><p>
Holds the result of the last <tt>lua_call_next</tt> - yielded value when the execution continues, and final returned value when the execution stops.
</p></div></div>
</p></div></div>
<div class="item"><a class="header" id="FAQ" href="#FAQ" title="(permalink)">FAQ</a><div class="content"><p>
<div class="item"><a class="header" id="lua-version" href="#lua-version" title="(permalink)">What Lua version is used?</a><div class="content"><p>
Apollo uses Lua 5.3.4 as of writing this.
</p><p>
In case you'd like a custom version (such as to use LuaJIT, or to use a Lua fork with
different syntax), C++ source code is included - it will work with any Lua build
down to 5.1.
</p></div></div>
<div class="item"><a class="header" id="What-platforms-does-it-run-on" href="#What-platforms-does-it-run-on" title="(permalink)">What platforms does it run on?</a><div class="content"><p>
The extension runs on Windows, Mac, and Linux - linked dynamically in all cases.
</p><p>
Apollo v2 beta currently only comes with a Windows (GMS1,GMS2) binary,
but you can compile it yourself (code is portable).
</p><p>
Mac may require additional tinkering (via <tt>install_name_tool</tt> - <a href="https://github.com/YellowAfterlife/steamworks.gml/blob/master/build_osx.sh#L7">example</a>), as library inclusion paths may vary depending on whether the game is running from IDE, whether YYC is enabled, and GMS version. If you are familiar with Mac extension development yourself, feel free to get in touch about better ways of handling this.
</p></div></div>
</p></div></div>
<div class="item"><a class="header" id="Limitations" href="#Limitations" title="(permalink)">Limitations</a><div class="content"><p>
<div class="item"><a class="header" id="Lua-tables-cannot-be-transmitted-to-GML-automatically" href="#Lua-tables-cannot-be-transmitted-to-GML-automatically" title="(permalink)">Lua tables cannot be transmitted to GML automatically</a><div class="content"><p>
While these are roughly equivalent to GM's <tt>ds_map</tt>s, the two work very differently -
<tt>ds_map</tt>s are passed by-index and managed manually (ds_map_destroy),
Lua' tables are passed by-reference and managed by garbage collector.
</p><p>
While future iterations on GML should make it possible to automatically convert between tables and lightweight data structures, this would only allow to return a new table/structure rather than modifying an existing one.
</p><p>
The issue can be approached in several ways:
</p><ul>
<li> Expose <tt>ds_map</tt>s to Lua code and use them instead of tables for transfer.
</li><li> Have a wrapper function on Lua side to expand the table into multiple values prior to calling the GML script and/or wrap multiple returned values from GML back into a table.
</li><li> If you do not need to read data from the table (but store/retrieve it), you can convert it to index and back on Lua side via lookup tables (see below).
</li></ul></div></div>
<div class="item"><a class="header" id="Lua-specific-reference-types-cannot-be-transmitted-to-GML-automatically" href="#Lua-specific-reference-types-cannot-be-transmitted-to-GML-automatically" title="(permalink)">Lua-specific reference types cannot be transmitted to GML automatically</a><div class="content"><p>
Lua supports several additional reference types (such as Lua function references),
but these cannot be safely sent to GML as pointers as they are garbage-collected,
and thus may get recycled while still referenced on the GML side of things
(resulting in hard crash when trying to use the passed back value).
</p><p>
A good way to deal with this is to make a pair of lookup tables - since Lua allows table indexes to be of any type, you can do something like the following:
</p> <pre class="lua">ref <span class="op">=</span> <span class="op">{</span>
__r2i <span class="op">=</span> <span class="op">{</span> <span class="op">},</span>
__i2r <span class="op">=</span> <span class="op">{</span> <span class="op">},</span>
__next <span class="op">=</span> <span class="nu0">0</span>
<span class="op">}</span>
<span class="kw1">function</span> ref.toid<span class="op">(</span>fn<span class="op">)</span>
<span class="kw1">local</span> id <span class="op">=</span> ref.__r2i<span class="op">[</span>fn<span class="op">]</span>
<span class="kw1">if</span> <span class="op">(</span>id <span class="op">==</span> <span class="kw1">nil</span><span class="op">)</span> <span class="kw1">then</span>
id <span class="op">=</span> ref.__next
ref.__next <span class="op">=</span> id <span class="op">+</span> <span class="nu0">1</span>
ref.__r2i<span class="op">[</span>fn<span class="op">]</span> <span class="op">=</span> id
ref.__i2r<span class="op">[</span>id<span class="op">]</span> <span class="op">=</span> fn
<span class="kw1">end</span>
<span class="kw1">return</span> id
<span class="kw1">end</span>
<span class="kw1">function</span> ref.fromid<span class="op">(</span>id<span class="op">)</span>
<span class="kw1">return</span> ref.__i2r<span class="op">[</span>id<span class="op">]</span>
<span class="kw1">end</span>
<span class="kw1">function</span> ref.free<span class="op">(</span>fn<span class="op">)</span>
<span class="kw1">local</span> id
<span class="kw1">if</span> <span class="op">(</span><span class="kw1">type</span><span class="op">(</span>fn<span class="op">)</span> <span class="op">==</span> <span class="st1">"number"</span><span class="op">)</span> <span class="kw1">then</span>
id <span class="op">=</span> fn
fn <span class="op">=</span> ref.__i2r<span class="op">[</span>id<span class="op">]</span>
<span class="kw1">else</span>
id <span class="op">=</span> ref.__r2i<span class="op">[</span>fn<span class="op">]</span>
<span class="kw1">end</span>
ref.__r2i<span class="op">[</span>fn<span class="op">]</span> <span class="op">=</span> <span class="kw1">nil</span>
ref.__i2r<span class="op">[</span>id<span class="op">]</span> <span class="op">=</span> <span class="kw1">nil</span>
<span class="kw1">end</span></pre><p>Which allow you to use <tt>ref.toid(some_reference)</tt> to return/create a numeric ID for a reference, <tt>ref.fromid(index)</tt> to convert one of those back to a reference, and <tt>ref.free(index_or_reference)</tt> to remove the lookup pairs (allowing Lua to safely recycle the reference when it is no longer used).
</p></div></div>
</p></div></div><!--doc>-->
</div></div></div>
<script>(function() {
var doc, headers;
//
var path = "Apollo cheat sheet";
var state = null;
if (window.localStorage && JSON.parse) {
state = window.localStorage.getItem(path);
state = state ? JSON.parse(state) : { };
if (state == null) state = { };
}
var isLocal = (location.host.indexOf("localhost") == 0);
//
function h3bind(h3) {
var node = h3.parentNode;
var snip = node.children[1];
var id = h3.id || h3.textContent;
h3.snip = snip;
h3.doc_set = function(z) {
if (z) node.classList.add("open"); else node.classList.remove("open");
if (state) {
state[id] = z;
window.localStorage.setItem(path, JSON.stringify(state));
}
}
h3.doc_hide = function() {
this.doc_set(false);
}
h3.doc_show = function() {
this.doc_set(true);
}
h3.onclick = function(_) {
var seen = !node.classList.contains("open");
h3.doc_set(seen);
return false;
};
}
function getHashFunc(id) {
var node = document.getElementById(id);
if (node == null) return null;
return function(e) {
while (node && node != doc) {
if (node.classList.contains("item")) {
node.classList.add("open");
}
node = node.parentElement;
}
};
}
// Display helpers:
window.opt_none = function() {
for (var li = 0; li < headers.length; li++) headers[li].doc_hide();
};
window.opt_list = function() {
for (var li = 0; li < headers.length; li++) {
var h3 = headers[li];
if (h3.parentNode.parentNode != doc) {
h3.doc_hide();
} else h3.doc_show();
}
};
window.opt_all = function() {
for (var li = 0; li < headers.length; li++) headers[li].doc_show();
};
window.live_post = function() {
doc = document.getElementById("doc");
headers = doc.getElementsByClassName("header");
//
for (var i = 0; i < headers.length; i++) h3bind(headers[i]);
// Clicks in document expand the related section:
var anchors = doc.getElementsByTagName("a");
for (var i = 0; i < anchors.length; i++) {
var anchor = anchors[i];
if (anchor.classList.contains("header")) continue;
var href = anchor.getAttribute("href");
if (href[0] == "#") {
var fn = getHashFunc(href.substr(1));
if (!fn) {
anchor.classList.add("broken");
anchor.title = "(section missing)";
} else anchor.addEventListener("click", fn);
}
}
//
for (var li = 0; li < headers.length; li++) {
var h3 = headers[li];
var val = state ? state[h3.id || h3.textContent] : null;
if (val == null) val = isLocal || h3.parentNode.parentNode == doc;
if (val) h3.doc_show(); else h3.doc_hide();
}
};
window.live_post();
//
(function() {
var hash = document.location.hash;
if (hash) {
var _hash = hash.substr(1);
getHashFunc(_hash)();
setTimeout(function() {
document.location.hash = hash + " ";
setTimeout(function() {
document.location.hash = hash;
}, 100);
}, 100);
}
})();
//
doc.setAttribute("ready", "");
})();
</script>
</body></html>
Reference in a new issue Copy permalink