VSIM is a work in progress. VSIM is currently primarily aimed at programmers who are interested in things like emulation, Lua, 3D models, or physics simulation. For example, it can provide a good starting point for creating your own custom front-end for libretro. The hope is that some developers will be interested and will create plugins that add functionality or content that non-programmers can easily access.


Key What It Does
F5 Install plugin
Ctrl-F1 Open help in browser
` Toggle Lua console
1-9 Zoom and interact with emulator #N
F7 Put zoomed emulator in full screen mode
Ctrl-F10 Exit

Finding Plugins

Currently is the best place to find plugins or post any you create.


Installing Plugins

To install a plugin press F5, paste in the plugin URL with Control-V, then hit ENTER. You will need to restart the program before the plugin will be active.

Creating Plugins

To create a plugin, first make a directory in [VSIM root]/lua/. Plugins can contain files and/or lua code in init.lua. You can test your plugin by adding it to the list in the [VSIM root]/plugins file and restarting VSIM. When it is ready open the console and type plugin_makezip("mydir")[ENTER] where mydir is the subdirectory of [VSIM root]/lua/ (just the folder name, not a full path). It will create a .7z file in [VSIM root]/lua/plugins/forupload which you can upload to your host. Then just share the URL for your plugin.



Run selected emulator (set with emu.core()) with an optional command/rom/binary and options table with emulator variable settings. Note: if there is a cores.cfg file it is parsed by the utils plugin at program start and placed in vsimcorecfg. NOTE: YOU MUST HAVE THE REQUIRED ROM OR OTHER FILES INSTALLED IN THE EXPECTED LOCATIONS. You may run the same core multiple times simultaneously or several different cores depending on system resources.

run Top Gear SNES game


specify the emulator core to use with emulate() commmands

next emulate() with MAME core


get memory data from emulator; returns a lua string


get size of memory from emulator


change emulator memory data

show some numbers at top of C64 screen


reset emulator machine


specify emulator option


set this emu option to string "true" to pause emulation


set this emu option to string "true" to turn on positional audio from emulator


insert virtual disk into emulator drive


eject disk from virtual emulator drive


delete emulator and node


run emulator in the full window

Models and Positioning


Rez (instantiate) a 3d model (3ds dae xml x mdl lwo obj mesh bsp md2 md3 stl ply) NOTE: Not all models are compatible. YMMV.


change selected node which subsequent commands like pos() and rot() affect


(model.put "true"): selected node casts a shadow (does not work on high-poly meshes),texturePerc, spherePerc, radius)

create a sky dome; texturePerc=0..1, spherePerc=0..2


set this variable on any node to change ambient light color of entire scene

model.put(property, value1, value2..)

set an attribute on a node or the system


set this attribute on any node to string "true" to show VSIM internal messages in STDOUT


make the selected node a child of nodeid

model.pos(x, y, z)

move the currently selected node

model.scale(xscl, yscl, zscl)

scale the currently selected node

model.rot(x, y, z)

rotate the currently selected node

model.mesh(indices, vertices)

create a mesh from the specified tables

create a simple triangle mesh and a node from it


add a scene node based on a mesh

model.pointlight(r, g, b, radius)

add a point light; rgb 0..1

model.texture(imgfname, [n]

apply an image as a texture to a node; optional texture num n


add a 3d line with thickness


add a 3d line


get attribute value of selected node


aim the camera at a position


position and look direction of selected node becomes relative to nodeid,y1,z1,x2,y2,z2,ms,loop,repeat)

animate selected node; loop/repeat string "true" or "false"

Flow Control

flow.wait(ms, funcname, repeat)

wait X milliseconds and then run a function by name

calls funcRepeats() approx. every 20 ms


wait for UI to process all lua commands


change current working directory

flow.on(event, funcname)

call a handler on event trigger



add a force w/dir (fx,fy,fz) and rel. pos (px,py,pz); returns forceid


remove force


remove torque


add a torque around axis tx,ty,tz ; longer vector = greater torque; returns torqueid


apply an impulse given direction and relative position


Enable collisions by setting this attribute

enable collision and set mass to 5

User Interface


keys used for movement (0), console (1) or emulator(2+)




set w/model.put on any node to png filename to change the overlay image


create a new screen or switch to an existing; print() and palette() affect this screen


apply emu or ui screen as a texture to a node

texture a node with an emulator screen

write some text on a mesh/node


change color values at index


show console (1) or hide (0)

ui.filedialog(title, filetypes)

Open a file dialog and return the selected filename

ui.draw(id, commands)

add, update or delete draw commands based on Cairo. Commands and arguments separated by spaces. id -1 to append, blank command string to delete. Available commands: font, size, path (start new path), move x y, line x y, sub (new subpath), end (end sub-path), scale x y, trans x y, save (save state), rest (restore state), arc x y radius degreestart degreeend, curve (cubic Bezier) dx1 dy1 dx2 dy2 dx3 dy3, rot deg, rect x y w h, color r g b a (0..1), fill, stroke (fill/stroke required to actually output shapes). See Cairo documentation and the following examples.

load and select font; then change the command list at that index to use a different font

creates a rotating plus with label indicating degrees rotated

ui.text(id, string)

add,update, or delete a text element at the current x, y coordinate


net.geturl(url, callback)

HTTP GET and return response body to callback function

net.saveurl(url, fname, callback)

HTTP GET and save response to fname


emucmd(core, argswspaces)

run a .cmd that simulates cmd-line for emulator


List files in directory

7-zip compression and decompression


unzip a file (uses 7-Zip, LGPL,