This is used by pyright, a type checker for Python. There are no *.py sources for the core engine bindings so the type checker will warn or error on some settings otherwise.

Can't this be initialized programmatically instead?

I can remove the configuration file. It's something that was more necessary when I started the extension, but the tooling has advanced since then and people may want to use other tooling for their own projects.

By that I meant, could this be expressed in an orx config file instead, and set programmatically when starting the extension?
This way we keep all configuration stuff consistent across engine & extensions.

This is pocketpy's header. The only modification from upstream is the reference to orx's memory allocation functions.

This is pocketpy's implementation. It is taken directly from upstream without modification.

This should be moved inside include/extensions, and included directly from orxPy.h.

I started with that but it breaks compilation of C++ projects since the code does not compile as C++.

Ah I see, in that case let's move it inside the newly added extensions subdirectory.

Very nice change - thank you! I moved src/pocketpy/ into src/extensions/pocketpy/.

Initialize the pocketpy virtual machine. This does not execute any game-specific Python code. It does define all of the orx.* engine module bindings.

This calls the user's/game's orx.init function, called from the init project's main source file.

Shouldn't this call also be inside orxExtensions.h, in InitExtensions()?
Is there a reason why it is separate from orxPy_InitVM()?

I started with this combined as well, but if a project defines its own modules from C then those need to be defined before any game Python code is run. Splitting the two initializes the VM early, then gives space for custom C bindings and module definitions.

Does the VM rely on any orx API? If not, we could move its initialization to the BootStrap function instead.
I'd rather not have any extension code outside of orxExtensions.h as much as possible as it breaks adding/removing extensions (the main source file can't be touched once created).

Short version of all the text below: I think we can make this change. I have some minor concerns around more advanced use cases described below. If it's ok for me to change the InitExtensions return type then I think my main concerns would be addressed.

The call to orxPy_Init here is like the call to orxPy_Update and orxPy_CameraUpdate earlier in the file. They each call Python functions defined by game code at the engine-appropriate time. I've tested locally and orxPy_Init could be called from InitExtensions if orxPy_InitVM is called from BootstrapExtensions.

I have some concerns with that change:

• InitExtensions doesn't return a status value. Would it be ok to have InitExtensions return orxSTATUS rather than void? In the PR's current state a failure during orxInit_Py will stop the game from starting up. I think that's a good feature to have but I'm not sure if others would agree.
• It obfuscates where the game's Python code is loaded and the user's orx.init callback function is called. I think that's ok. The Python extension is kind of like Scroll in that it can be used to change where primary game logic is run (C vs C++ vs C++/Scroll vs Python). However the Python extension uses the existing C/C++/Scroll engine callbacks for bootstrap/init/update/camera update rather than defining its own.
• It is less clear where a user's custom C to Python bindings should be added. If orxPy_Init is called from InitExtensions then those modules must be defined before the call to InitExtensions. That should work as long as those module definitions do not rely on other extensions being initialized first. Custom module definitions shouldn't require that - initialization should happen when the game logic is initialized. I think that's ok as well.

A bit of extra context on the extension's two init functions:

orxPy_InitVM initializes the pocketpy VM and registers the orx.* Python modules with that VM. It does not run any Python code or call any orx APIs. It could be called from BootstrapExtensions.

orxPy_Init loads and runs the user's [=name].py code, sets up any references or bindings between user code and the pocketpy VM, and calls the user-defined Python init function if one has been defined. Arbitrary orx and Python code can be run at this point.

I'll have to check orxPy.h, but shouldn't it no rely on Scroll at all and be orthogonal to it, so as to have a single code flow no matter what the kind of project is?

NDEBUG signals to pocketpy that this is not a debug build.

You can add a separate defines line for Python, it might make it slightly more easy to read.
Or just decompose the existing one on multiple lines.

miniscroll has its own registration logic to simplify what needs to be done by the user.

Should we give it a more obvious name maybe, like PyScroll?

I like PyScroll! I started with "mini" as the prefix because of its relatively limited scope, but I think PyScroll is better and disambiguates well with Scroll.

Minor alignment issue. Is this file auto-generated?

This file comes from the pocketpy project. pocketpy generates the combined pocketpy.h and pocketpy.c files from individual header and source files as part of the release process.

I'll have to check orxPy.h, but shouldn't it no rely on Scroll at all and be orthogonal to it, so as to have a single code flow no matter what the kind of project is?

By that I meant, could this be expressed in an orx config file instead, and set programmatically when starting the extension?
This way we keep all configuration stuff consistent across engine & extensions.

Why not use the TriggerList here as well?

miniscroll/pyscroll does not support the same . and other prefixes that Scroll does, so it can't match the behavior the scroll provides with the TriggerList. It's something I could probably add, but last time I looked there were some features Scroll relies on for this that were not bound by orxpy.

Ah I see, so the inputs are handled entirely in Python code then?

Fine by me, but I do find the data-only input handling handy for simple situations and I would recommend implementing something similar to what's inside ScrollBase (it's not much code).

so the inputs are handled entirely in Python code then?

Somewhat - it uses a similar approach to what is done in Scroll, but not as refined. This is run for each orx object registered with pyscroll/miniscroll on each update:

      # Input triggers
      for input_name in mini.input_names:
        if orx.input.has_been_activated(input_name):
          mini.o.fire_trigger("Input", refinement=[input_name])

The mini.input_names list is populated when the object is created, based on the input set associated with the object, similar to what's done by Scroll but captured on object creation rather than looking up the inputs at runtime.

I agree the additional functionality and flexibility provided by Scroll is worth having here. I'll work on that.

You can add a separate defines line for Python, it might make it slightly more easy to read.
Or just decompose the existing one on multiple lines.

I decomposed the existing one on multiple lines and am happy to change the approach further if you prefer.

if the only difference is the first parameter, you can have the -scroll/+scroll only for that parameter instead, for brevity.

Similar suggestion as before: use -scroll/+scroll only around the first parameter.

Done for both.

All the -python blocks could be merged in a single one and the callbacks registered at the very end instead.

Done.

It's super minor, but given this already follows most of orx's coding conventions, would you mind going the extra mile and prefixing function parameters with _?
For example:
orxCHAR *orxPy_ReadSourceFromMain(const orxSTRING _zPath, int *_piDataSize)

Certainly - apologies for the inconsistency for those function parameter names. I'll fix that and push an updated commit in a few minutes.

Style fixes are in 687f589. There were a lot! Thank you for calling the naming mismatch out. I'd like this to feel like orx as much as possible.

Thanks for taking care of it!