OSafeThread 1.0.0

Modders resource to start and run OStim threads without crashing due to combat status.

For Users

This is a modder's resource.  It does nothing on its own.  As a mod user, install this only if a mod you are installing specifically tells you this mod is a dependency. 

For Modders

OStim is very sensitive to the combat state of actors in a thread.  An actor being in combat when OThread.Start(id) or QuickStart(...) is called will cause a CTD 100% of the time.  Even if you check combat state before attempting to start a thread, actors can be detected by a hostile and enter combat state while the thread is going, which will also cause a CTD. (BTW, this seems to be not an oversight but a conscious decision by the OStim team to avoid overstepping the core focus of the framework into the territory of handling actor combat states, which is a decision I respect.)

This plugin handles that for modders in a performant, native way so that every OStim mod doesn't have to try to implement this system themselves.

Example use case this opens up: A Bard class skill that is triggered in combat that starts an OStim ballroom dancing scene with the enemy.  Such a mod is now possible easily by using OSafeThread.Start to start the thread safely instead of calling OThread.Start directly.  This plugin provides tools to let modders manage when and whether any calmed actors are returned to their pre-thread state. (Any actors not specifically claimed are automatically reset a few seconds after thread end or on an in-game reload to prevent stuck calmed states. The number of seconds is configurable if SKSE Menu Framework is installed.)  This allows gameplay options like "charming" a hostile actor and then having them become non-hostile afterward.  Any gameplay logic is up to you.  This mod just provides modders the tools to start the thread safely and claim/release different categories of actors.

Q: Will this plugin break on each new update/build of the OStim dll?
A: No, this plugin actually does not hook into the OStim plugin directly.  It uses only the public, stable API.  You build your desired thread using threadbuilder the same way you normally would.  Then, instead of passing that builder id into OThread.Start(builderId) to have OStim start it, you instead call OSafeThread.(builderId).  This gives OSafeThread a chance to do its work before passing on the request to OThread.  No hooks needed.  (Alternatively, you can call OSafeThread.QuickStart on an array of actors the same way you would directly call OThread.QuickStart.)  This plugin should be stable across OStim updates unless there is a major change to the public API.

How to Use

The best way to understand the intended DX is to review the functions exposed to Papyrus in source/scripts/OSafeThread.psc.

Demo Plugin

The demo is an extremely simple implementation you can try out just to see that the plugin works and is extremely fast vs trying to do something similar in Papyrus.  It listens for 'V' keydown and will try to QuickStart a random Ostim scene with the nearest actor whenever the key is pressed. Do not keep this installed for normal gameplay.  It's not a full mod and will listen for that key even in menus and such and will also try to start a scene with any actor nearest when you press the key.  There is no filter (other than the built-in OStim filter for what types of actors are valid).  It's just meant to be a quick demo of the speed and combat safety.

Source

Source available on GitHub

The README in the repo has instructions for how to recompile.