Developers

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.

Keybindings

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 https://reddit.com/r/vsim is the best place to find plugins or post any you create.

top

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.

Emulation

emu.emulate(emulatorid,filetoload,tableopts)

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

emu.core(fnameNoExt)

specify the emulator core to use with emulate() commmands

next emulate() with MAME core

emu.getmem(emulatorid,bank,offset,numbytes)

get memory data from emulator; returns a lua string

emu.memsize(emulatorid,bank)

get size of memory from emulator

emu.setmem(emulatorid,bank,offset,binStr)

change emulator memory data

show some numbers at top of C64 screen

emu.reset(emulatorid)

reset emulator machine

emu.opt(emulatorid,property,value)

specify emulator option

vsim_pause

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

vsim_3daudio

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

emu.insert(emulatorid,drivenum,dskfile)

insert virtual disk into emulator drive

emu.eject(emulatorid,drivenum)

eject disk from virtual emulator drive

emu.delete(emulatorid)

delete emulator and node

emu.full(emulatorid)

run emulator in the full window

Models and Positioning

model.rez

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.

model.sel(nodeid)

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

VSIM_CAST_SHADOW

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

model.sky(skydomeTextureFname,texturePerc, spherePerc, radius)

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

VSIM_AMBIENT

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

VSIM_DBG_MSGS

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

model.parent(nodeid)

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

model.node(meshid)

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

model.line3dex(x1,y1,z1,x2,y2,z2,clr)

add a 3d line with thickness

model.line3d(x1,y1,z1,x2,y2,z2,clr)

add a 3d line

model.get(property)

get attribute value of selected node

model.lookat(x,y,z)

aim the camera at a position

model.siton(nodeid)

position and look direction of selected node becomes relative to nodeid

model.fly(x1,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

flow.waitui()

wait for UI to process all lua commands

flow.chdir(path)

change current working directory

flow.on(event, funcname)

call a handler on event trigger

Physics

physics.force(fx,fy,fz,px,py,pz)

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

physics.delforce(forceid)

remove force

physics.deltorque(torqueid)

remove torque

physics.torque(tx,ty,tz)

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

physics.impulse(fx,fx,yz,px,py,pz)

apply an impulse given direction and relative position

collision

Enable collisions by setting this attribute

enable collision and set mass to 5

User Interface

ui.screeninp(which)

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

print(arg1,arg2..)

ui.cls()

VSIM_OVERLAY

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

ui.screen(num)

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

ui.screenon(nodeid)

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

ui.palette(index,r,g,b,a)

change color values at index

ui.showscreen(num)

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

Networking

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

Utilities

emucmd(core, argswspaces)

run a .cmd that simulates cmd-line for emulator

dir(glob)

List files in directory

7-zip compression and decompression

unzip(fname)

unzip a file (uses 7-Zip, LGPL, www.7-zip.org)