NEPTUNE API V1 release (Patreon)

Neptune is a plugin that creates a simple API inside VAM, allowing local services & tools to send commands to VAM and use it as a rendering environment. This is a framework for other developers, there's no use for it for players at this point.

I'm sharing this because I've seen people use 3rd party software for connecting things to vam and this might help them out. It doesn't require anything special, it's a normal vam plugin.

There's a VAM2 API that was mentioned, it looks like VAM2 might have builtin support for API calls in the future. Devs could use Neptune as a way to do complex UIs & features that will work on VAM1 today, and which later could be more easily adapted for VAM2 just by switching API calls.

HOW TO USE IT

It requires Allow Plugin Network Access to be enabled in VAM Security settings

Plugin can be added as a Session plugin. It should work as a scene plugin too.

First time when running, players will likely get a Firewall popup to allow or deny VAM access:

this is for the plugin to be able to open up a port where to receive the API calls

The simplest & most powerful way to use this API is with the "trigger button" call:

This will trigger the button with the id "MyButton", if there is one in your scene. In VAM buttons you can do very complex logic. So this call alone can be used to trigger pretty much anything you want in VAM and do very complex things.

HOW TO MAKE CALLS

These are regular GET/POST calls to 127.0.0.1:7872 . POST calls require data sent as JSON.

The POST data has 2 fields that the plugin currently reads:

entityid - string field meant as a general way to send ids of atoms or things to do operations on,

message - string field where you can send more data to VAM. You can send encoded json objects too, like in my ApiPostAtom example

CURRENT ENDPOINTS

GET /status

This is a simple example call that can be used as template for GET calls. Returns "ok" if Neptune is running correctly.

POST /testmessage

This is a simple example that returns the message received. You can use this for testing and as a template for other calls.

POST /general/triggerbutton

This will trigger the button with the id you send.

POST /atom/add

This will create a new atom, of the type you sent. (Same names as in the vam new atom menu)

POST /atom/delete

This deletes the atom with the name you send.

POST /atom/get

This returns info about an atom. You can use this with the /atom call to update the atom.

POST /atom (experimental)

This allows changing an atom. It requires an encoded json following the structure received from the /atom/get call. I tested this very little and some stuff didn't work. What I've seen work were atom position, rotation, scale. What didn't work was color of material. Other stuff is untested

GET /atoms

This returns a list of the current atoms and their info. This could be very big in size depending on your scene and if you have animation data in your scene.

ADDING CUSTOM ENDPOINTS

I tried to make it very easy to add new endpoints. Each endpoint is a separate file in the Calls folder:

To make your own endpoint:

Copy an existing one and rename the file, like "ApiPostMyEndpoint.cs", and the class inside it, like "ApiPostMyEndpoint"

Edit Neptune.cslist and make sure to add your file there too like the rest. Like "Calls\ApiPostMyEndpoint.cs"

Edit ConfigApiCalls.cs and add an entry in the "//add here more get calls" areas, like the other ones there. There's two areas, one for Get calls and one for Post. You can put here the path you want for your endpoint, like this :

case "v1/myendpoint": ApiPostMyEndpoint.Respond(context, queryParams); return;

Then you can do the logic you want in the ApiPostMyEndpoint.cs file, following the examples. You'll have to reload the plugin after each change.

BUGS

there's a known bug after reloading the plugin, the first call made to it might throw a bad request error.

LICENSE & CONTRIBUTIONS

Code is MIT license, so feel free to reuse it or put it on github if you want. If anyone adds endpoints and wants them to be directly in the official VAR here, you can send them to me and I'll try to update the VAR when I can. I'll try to add some more endpoints in the future too so suggestions for endpoints are welcomed.