AngelScript subsystem future

[ohlidalp]

Something to tackle after v0.4.8 release and OGRE 1.11+ port:

AngelScript is great, but RoR's programming interface needs improvement.

• Event callbacks are limiting I dislike event callbacks. You receive those ad-hoc and need to do a lot of checks "was this done yet?" "is that thing running?". So the scripter ends up simply buffering state information from various events in custom variables. Also you're limited by the events RoR offers and need to ask developers for more if you need them. Also the existing TRIGGER_EVENT() macros work by synchronously invoking the handler script function - not good for parallelism and maintenance.
• Event queue is better With event queue, the scripter chooses when to process events and can quickly check dependencies/interaction. TRIGGER_EVENT() macro writing to std::vector<> makes much more sense.
• Free access to all sim. data is the best - That way, the scripter simply queries and evaluates whatever he needs. Right now we only have rough interface - for example we can query actor's 'position' - is that cameras or node 0? I don't even know!.
• We need per-tick invocation and N/B API AngelScript is easily performant enough to be invoked within physics simulation step. With proper positions/forces API, we could let modders implement custom shock absorbers (stabilizers?), command hydraulics or even a new powertrain. Think about it - instead of having convoluted and hard-to-extend code for all these features, we'd only keep the raw softbody physics (most of the N/B, anyways) and do all the complex things in external scripts managed by the community (with our own libs/contributions)
• Per-frame invocation of script should only access SimBuffer - I'm reffering to the architecture of https://github.com/RigsOfRods/rigs-of-rods/pull/1538 - all simulation should be done within physics-timestep (with scripts invoked there) and only Gfx should be done per-frame, asynchronously, reading buffered data in GfxScene/GfxActors
• Sound API - RoR's sound events are just as limiting as any other event system. It works for the common case, but anything special (special hydro/command/shock/engine effects) is a bummer.
• DearIMGU API - Why not let scripters create their own GUI for whatever reason (objectives, scenarios, diagnostics). DearIMGU's API consists exclusively of stateful global functions, so it practically binds itself - ImGui::Begin("window name"); can as well be AngelScript code. It would only be accessible in per-frame invocation of script (not in per-physics-tick) - see https://www.angelcode.com/angelscript/sdk/docs/manual/doc_adv_dynamic_config.html
• Cairo graphics API - We have a limited texture-generation functionality for text signs. What about an ultimate API which could generate any texture with any graphics, possibly also using SVG images as templates? I've had https://en.wikipedia.org/wiki/Cairo_(graphics) in mind for some time and I even started building interface for it: https://github.com/only-a-ptr/cairomm-angelscript. RoR would cache the generated textures if the modder wants. Check out this working demo: https://github.com/only-a-ptr/cairomm-angelscript/blob/master/demo-app/script.as
• Access to GVars - global properties which affect the whole game state (returning to menu, pausing, setting gfx/sound/visual settings). See https://github.com/RigsOfRods/rigs-of-rods/wiki/GVars:-global-(console)-variables
• Example content - A tutorial map scripted to teach you trucking (attaching loads, hauling, fuelling - oh yes, fuelling is one of those things you could script for your vehicles) could as well serve as example of scripting, with proper commentary and code clarity.

RoR has traditionally had everything data driven - Truckfiles, soundscripts, eventboxes in .odef files - and that's a good thing. The problem is, implementing all the logic is then up to the developers who are not the best fit - I'm not at all into motorsports, so how am I supposed to code a powertrain with all the mods and specifics that exist in real world? And where do I find the time? Moving the complexity out would give us a chance of getting more devs interested specifically in this stuff - with proper in-game GUI, scripts aren't scary like application programming.

I'm not suggesting all modders should write code instead of config files. I'm suggesting that the config files they write won't be parsed and executed by RoR's code directly, but by community-driven suite of scripts which will then control RoR. Sounds fair?

[ohlidalp]

To implement this, tough, we need to create a new scripting interface from scratch, the existing won't cut it:

• it's designed to be invoked once per frame with deltatime as parameter - not optimal, see above.
• all of the interface is available at all times - unacceptable.

Draft

Just an initial idea - some things may not be possible or need updates. @AnotherFoxGuy @ulteq @tritonas00 @Speciesx I'd really like your early feedback just to be sure I'm not writing nonsense. Sorry for doodling future concepts instead of finishing v0.4.8, but lately I've never had time at home - now I'm at work, I can't code and I'm bored.

Hooks

Hooks are pre-defined moment in game session where scripts can be invoked.

• APP_BOOT - Once when app is launched, just before entering main menu loop.
• APP_SHUTDOWN - Once when app is being shut down; for collecting stats etc...
• MAIN_MENU_FRAME - Per-frame rendered in main menu.
• TERRAIN_LOAD - Once when terrain is loaded, just before starting sim. loop.
• TERRAIN_UNLOAD - When returning to main menu; for collecting stats etc...
• SIMULATION_FRAME - Just before rendering a frame in simulation. Simulation data are read only (GfxScene/GfxActor buffers) because scene update+rendering are not synchronous with simulation. You can modify the OGRE scene from here, though. Also, you can draw with DearIMGUI. Invoked also when simulation is paused.
• ACTOR_SPAWN - Once when an instance of actor is spawned (actor = one softbody object, whether a vehicle or load)
• ACTOR_REMOVE - once when actor is removed.
• SIMULATION_STEP_GLOBAL(N) - invoked every N simulation steps (step = 500microseconds). Performance critical. Has the freedom to modify anything in the simulation.
• SIMULATION_STEP_ACTOR(A, N) - invoked every N simulation steps (step = 500microseconds). Performance sensitive. Has the freedom to modify anything on actor A (actor = one softbody object, whether a vehicle or load)

Note: Multiplayer state can be accessed/controlled at any time using GVars.

Hooking methods

• from config files - you specify a script function name in some config file (hardcoded+documented function signature) - no conditions, always invoked
• from script - you do any kind of checks you want and then call something like AddHook(HOOK_TYPE,MyHookFunction)

Script sources

• GVars (RoR.cfg) - can use any hooks.
• terrn2 - can use terrain + actor hooks.
• actor - can use terrain + actor hooks (terrain hooks are useful for custom dashboard/machine controls via DearIMGUI for example)

APIs and their availability

• DearIMGUI - MAIN_MENU_FRAME , SIMULATION_FRAME
• Sound - MAIN_MENU_FRAME , SIMULATION_FRAME, SIMULATIONSTEP[global/actor]; Sounds are by nature asynchronous commands for a background thread running within the sound library, it's OK and desirable to update sounds quickly in the physics.
• GVars - everywhere.
• Cairo graphics - BOOT, TERRAIN_LOAD, ACTOR_SPAWN
• N/B (within existing actor) - SIMULATIONSTEP[global/actor], ACTOR_[spawn/remove]
• N/B (creating new actor) - BOOT, TERRAIN_LOAD

Running script files and sharing data

Script files are only executed in hooks APP_BOOT, TERRAIN_LOAD, ACTOR_SPAWN - only here you can define global variables and functions. Other hooks can only invoke registered functions and thus can only read/write existing global variables, but not add new ones.

Because starting with v0.4.8 graphics (updating 3D scene + rendering) will run in parallel with simulation, you can't access global variables from hook SIMULATION_FRAME - you must send/receive data to/from it manually. To do it, use RoR::SetFrameInput(objectWithSimData) and RoR::GetFrameOutput(objectWithGuiData) in a SIMULATION_STEP* hook and RoR::GetFrameInput(objectWithSimData) and RoR::SetFrameOutput(objectWithGuiData). This will be most useful for drawing custom gui with DearIMGUI - in SIMULATION_FRAME hook, you receive simulation data to visualize, draw GUI and send resulting user input back.