Topic: Plugin API

[void]

Hello, fellow AGS-Users,

while using the AGSs Plugin API quite intensive during the past time, I noticed there're some things that may be missing right now. For example, there is no clean way of retrieving all the objects of the game, not only the current room. I know this is more likely due to the resource management of the engine (I guess it only loads the current room and discards all previous objects), but a possibility to load a room on demand would be great.

Also, the implementation of the callback functions back to the scripting language is rather inconvenient. Having three integers as arguments just isn't enough and requires a good portion of workarounds that are not very comfortable. There should be a way of at least pass a String object back to the engine.

I also noticed that the handling of the data types isn't very consistent. Sometimes you use an AGSCharacter struct, sometimes an integer as ID, but there's no way getting the ID from the struct (or at least I don't remember any).

Those things are just my quick thoughts on that, I guess there may be more, but I mainly intended to start a discussion about the API and its further development. Your thoughts on that?

[sonneveld]

I would be nice if other platforms were included in this discussion.

[monkey_05_06]

The plugin API is essentially nothing more than a publicly exposed (from the perspective of an external library) portion of the main engine code. This would (should) definitely be cleaned up in the refactoring/rewriting of the engine code. There are various things like this where CJ just patched in this requested functionality or that, but he himself admitted that due to spending more time implementing new features and bug fixes than optimizing and maintaining a consistent codebase led to the current state of the engine's source.

Various people are definitely working on it, but it would be good to know what people would like to have exposed to the plugin API (ideally most plugin functionality would be feasible using an AGS-native module instead, but the plugin API is definitely useful in the meantime).

A lot of the more recent changes aren't available to the plugin API, such as the AudioClip and AudioChannel types. That could be useful.

[Crimson Wizard]

It' been a year! wow.
Anyway.

Unfortunately, it seems that we won't be able to maintain (engine's) Plugin API in its current form. By saying "not able" I mean it will be
pain in the... head to do so.
What's wrong with current plugin system?

1) It grants free access to internal engine data. Which...
   a) allows plugin to easily corrupt engine's memory;
   b) prevents from changing internal object implementation;
   c) prevents from changing data location in memory (like, dynamic reallocation on new place, which is common when arrays of objects grow or shrink);

2) It is based on classes with virtual inheritance. Which is not so bad on its own, but it appears that different compilers pass class objects slightly different, and that "slightly" is enough to screw things up when there's virtual table pointer in them.


Keeping those points in mind, those are requirements for (engine's) Plugin API:
1. It should not provide addresses (pointers, references) to real engine objects or parts of those objects.
Instead, engine may return interface objects that serve medium between plugin and game object, and, in certain cases, temporary PODs used to
read/write game object's state.
2. It should not have interfaces with virtual functions. This means that interfaces may only have normal functions and member variables.
3. Additionally, we may consider to let people write plugins in C, in which case the only option for interfaces are C structs with function pointers in them.

In fact, unless I forget some other opportunitues, it seems that C-style interfaces (structs with function pointers) are the only option, because if we can't use virtual functions, we won't be able to create extending classes in plugin to pass their objects to engine (like for the font renderer) :-/.

[Wyz]

Yes I guess that simple structs and function pointers is a safe bet for compatibility. There could perhaps be a wrapper API for people that implements OO-style functionality for people that prefer this. Such wrapper would be compiled along with compiling the actual plugin so it will not suffer from the same cross-compiler issues.

Personally I don't really mind exposing internal representations to plugin developers but I see how this would limit efforts to change internal structures and perhaps hinder progress. It would be nice if there was a more general way to probe and change game variables and since the scripting environment is already OO it would be great if it would make use of this. This way you can tap into any of the default game objects like Characters and Rooms, but also objects managed by other plugins or perhaps something for the future: user built classes.

Something I think is of great use is a callback system (events, functions pointers, whatever you want to call it); I'd like to see this in general for the scripting environment but for plugins it is a great start and something that would be quite useful.

One short note on managed objects and the way they work now:
They register objects with virtual parts; something that will break as already mentioned. What always struck me is that it is a bit inconsistent with the way script functions are registered: this is simply done with a 'register' call specifying the parameter count. For managed objects you need the object interfaces. I guess this could be replaced with another 'register' call but this time specifying callbacks for the serialization, memory allocation and freeing functions (and a string for the object name). I guess this is a simple fix though for backwards compatibility I guess there needs to be a version check.