Moongate Documentation

[BlackNecro]

New version here: http://www.wiremod.com/forum/wiremod...w-version.html


First the FAQ:

I: What is the MoonGate?
Well it's basically a wire chip that allows you to enter a lua script and it then executes the script like the expression gate or the cpu does.
( Incase you're interested why I called it MoonGate - lua/moon - lua chip - moon chip - moon gate - wordplay hah :S )

II: Why should I use the MoonGate instead of the Expression Gate/CPU
There are several reasons - It's syntax is way easier than zASM (maybe easier than expression gate for some but that depends on further scripting experience et cetera)
and more powerful than CPU and Expression gate

III: So if it's more powerful - what features does it got?
It supports Basic Arithmetics, Trigonometry, Vectors, Angles, Strings and Tables (and Color In/Outputs but you won't be needed THAT much ;P)
Besides those functions it also comes with default lua features like if statements, loops, functions et cetera.

IV: Wait - If you can input lua and it can do that much stuff can't some skilled user fuck with my server?
No he can't - The moongate code is locked in to a function enviroment that has a limited global table. Basicly they're not going to be able to access anything other than what's provided


Ok now to the Documentation itself:


I. The MoonGate Wire Component:
It's got 4 inputs by default:

On: Turns the whole component On or Off

MemBus: Input for hi-speed links

Reset: Resets the whole component incase of errors or for whatever reason you want to reset it

By default we also got 2 outputs:

Error: Should be 0 all the time but incase you get runtime errors it outputs 1 ( and you'll get a screen notice )

Memory: Again hi-speed link support

II. The Editor:

You can open the editor either using the console command 'moongateeditor' or by pulling out the MoonGate stool (Wire - Control section)
and pressing the Editor button

On the top of the script you'll see 6 buttons which should be pretty much self-explanatory.
Just incase they aren't a full description of them follows in Additional Notes II.
A sidenote incase some of those buttons won't work make sure you got a file in the file list selected.
Speaking of the filelist - it's the list entry you'll see on the top right.
To open a file just double click it.

The first text entry you'll see is the name entry - your moongate gets the name you enter there.
Additionally you can also define tags for it so your stool file list is a bit more organized.
You seperate tags with a semicolon.

The second text entry defines the inputs. All your userdefined inputs go here.
You can also set the type of an input (Vector Sring et cetera) with an suffix.
E.g. appending :V to an input will make it an Vector input.
For different seperators and datatype suffixes have a look at Additional Notes I.

The third text entry defines the outputs. Same rules as for the inputs apply here.

The fourth text entry defines the script itself. This is the core of the MoonGate.
Here you enter your lua script. More on this in the next chapter

At this point I also want to point out that there are some shortcuts listed in Additional Notes II.

III. Scripting Guidelines/Rules:

I expect you already know the basics of lua - I won't explain those here.

Ok first I should point out what the chip does, what you can do with it and where it's limits are:
It runs your script everytime a custom wireinput changes or if you use the NextThink function (more bout that one in the Additional Notes III) and in that script you can access input values do calculations or whatever with them and
then set the output variables to a value and after the script got called the outputs get triggered in the order you defined them.
All variables ( expect inputs variables ) are stored between function calls so you can create basic and advanced memory stuff.
You got a plenty of functions to do advanced calculations and other stuff such as vector angle string and table support.
You can also access entities to a certain degree - So you can get positions angles and velocity of entities based on entity index, but
you got no direct access to entities ( for security reasons )
Ok this should give you a pretty well overview about the chip and it's functions now how to use them.

You can access all userdefined input values by just accessing the variable of the same name.
Same for outputs - you can access all userdefined outputs using variables of the same name.
E.g. for an output called Out and an input called In you could just do:
Out = In * 2

Ok those are the basics of the MoonGate <-> Wire interaction now what you can actually do in the script.

You got full native lua syntax meaning you can use loops, if-statements and functions.

Additionaly to those you can access some functions you could access in gmod lua too.
For example the whole math, string and table library as well as some global functions and a few custom functions.
You can also use some metatables like the Vector metatable.
You'll find a full list of all functions, libraries and metatables you can use in Additional Notes III

That's it already the MoonGate is actually a quite simple Wire component the most complicate thing is just that you need to know lua,
but that should be a quite small problem.

So then good luck and have some fun with it - I had my fun writing it (pain and frustration too, but mostly fun) So I hope it'll be of any use for somebody.

Additional Notes:
I:
In/Output seperators: ' ' , ',' , '|' , '!'

Suffix - DataType:
:V - Vector
:S - String
:T - Table
:C - Color
:N - Normal - Note this is optional

II:
The different Buttons explained:
New: Creates a new script, clears text entries and stuff
Save: Saves the script.
Save As: Saves the script under a new filename.
Validate: Validates the basic syntax of the script - Runtime errors can still occur like substracting a number from a function using nil variables et cetera.
Upload: Uploads the file to the server - No use in Singleplayer as the stool uses the same folder as you save stuff to.
Delete: Delete the selected script
Shortcuts you can use in the text entries:
Ctrl + N: New File
Ctrl + D: Validate File ( Will Validate but won't display a message if validation was successful just when an error occured)
Ctrl + S: Save File

III:
List of Usable Libraries, Global Functions and Custom Functions:
math
string
table
constraint *
ents *
file *
filex *
game *
gmod *
player *
sql *
team *
util *
Global Functions:
Angle
Color
CurTime
LerpAngle
LerpVector
Matrix
Vector
tonumber
tostring
type
EffectData *
ValidEntity *

* Only usable if you're an admin on the server.

Custom Functions:

GetAng( entindex number )
Returns an Angle of the entity with the given entindex or if entindex is nil own Angle

GetAngVel( entindex number )
Returns a Vector of the anglevelocity of the entity with the given entindex or if
entindex is nil own Angle

GetColor( entindex number )
Returns a Color table of the entity with the given entindex or if entindex is nil own
Angle

GetPos( entindex number )
Returns a Vector the position of the entity with the given entindex or if entindex is
nil own Angle

GetVel( entindex number )
Returns a Vector of the entity with the given entindex or if entindex is nil own Angle

LocalToWorld(entindex number, position Vector)
Returns a Vector of the world position of the local input Vector to ent of given
entindex (assumes self if entindex is nil)

WorldToLocal(entindex number, position Vector)
Returns a Vector of the local position to ent of given entindex of input world Vector
(assumes self if entindex is nil)

print( Data, ... )
Customized print function that prints at the owner's console.


InputTriggered( Input string )
Returns Boolean/String
Returns true if Input was triggered between current call and last call.
If Input is nil it will return the last triggered input.
If Input is true it will return the last triggered input and reset last triggered input.
If no Input was triggered yet or last triggered input was reset it returns nil.

TriggerOutput( Output string, value )
Returns Boolean
Triggers the output before the end of a function call returns true on success false on
failure (caused for example by wrong output name)

GetGlobal( Name )
Returns Variable Datatype
Returns a variable shared between all MoonGates of the same Owner

SetGlobal( Name, Value )
Sets a variable shared between all MoonGates of the same Owner

GetMemory( Address number )
Hi-speed support:
Get memory value at given address
Address < 65536 will access it's own memory
Address > 65536 will access external memory

SetMemory( Address number, Value number )
Hi-speed support:
Sets memory at given address to value
Address < 65536 will access it's own memory
Address > 65536 will access external memory

NextThink( Delay number )
The script will be called again in the amount of seconds you provide.
This allows you to create fully automated scripts that require no inputs to be triggered.

TriggerOnInput( Enabled boolean )
If this is set to false the script won't get called by input changes.
Use this if you want your script only to be called by NextThink

TriggerOnInput( Enabled boolean )
If this is set to false the script won't get called by input changes.
Use this if you want your script only to be called by NextThink


For explanation of Libraries and Global Functions please have a look at the Gmod Wiki





I would pretty much prefer to not do it like this but as long as Tad (who told me to get it on the svn) isn't present and I got no access to the svn I'll have to share it like this.

moongate.rar

Just extract it in a some new folder in your addon's folder (Moongate would be appropriate) and have some fun with it. Only the server needs it no additional modules or anything required.

[-Gamah]

.......wow

I'd love to try this but after reading that, my brain hurts.

[BlackNecro]

.......wow

I'd love to try this but after reading that, my brain hurts.

The joy of documentations ... 500+ pages for a simple text entry :lol:
Just try it it isn't that complicated but if I write something down it always sounds way more complex than it is :S

Also why do these vb boards always kill all sorta layout :hang:

[Fomoria]

Ooh, shiny. It's just destroyed any chance of me learning how to use the CPU. Nice to see globals being used.

A quick question about tables, though; what kind of funkiness can we expect to see when sharing them between chips? Is it set up to duplicate the entries in the table into a fresh one, or will it share the table pointer so that chips can set up their own private communication channels? Does this change when we use the global functionality?

[BlackNecro]

A quick question about tables, though; what kind of funkiness can we expect to see when sharing them between chips? Is it set up to duplicate the entries in the table into a fresh one, or will it share the table pointer so that chips can set up their own private communication channels? Does this change when we use the global functionality?

They just send over copies of those tables.
But if you use the Set/GetGlobal functions you are able to communicate between two gates.

[-Gamah]

now that we have direct wire/lua interaction, is it possible we get lua/dll interaction?

[Fomoria]

Globals appear not to work, in my tests at least.

[Syranide]

now that we have direct wire/lua interaction, is it possible we get lua/dll interaction?

There already is, but dangerous as it is to directly expose lua on a server, exposing DLLs would be pure madness.

[Black Phoenix]

There already is, but dangerous as it is to directly expose lua on a server, exposing DLLs would be pure madness.

Hey, let's write a DLL that gives us full access to executing raw program code (we can link it to GCC or something) - that gives us full processing power of CPU, and lots of cool features

[Selig]

Hey, let's write a DLL that gives us full access to executing raw program code (we can link it to GCC or something) - that gives us full processing power of CPU, and lots of cool features

sounds good,and lets not forget to link in universe-ctrl.c so we can change the global constants (speed of light, strength of gravity, etc) i am so glad we can change the real world now.