[Announcement] [Gdscript] Godot 4.x Client Work in Progress

[Goutte]

Hello !

I started experimenting with a Godot client (GDScript), and albeit there's not much to show right now I wanted to write something here in case anyone else is interested in joining forces. I looked here for the keywords Godot and GDScript.

Here's the working branch.

Rationale

Being able to quickly draw a pure GDScript client for any OAS would be amazing for some online games, even though Godot has its own network engine, because in HTML5 exports only the HTTP client is available (for now). Anyway, there's plenty of uses for HTTP connections to a server in games (auth, leaderboards, news, etc.).

I don't know if GDScript will have all the features we need, we'll see along the way.

Y U NO C ?

Having to compile Godot itself and distribute it to all collaborators is no small task.
And I'd rather not have Mono if I can help it.

Design

Some ideas, constraints inherent to Godot, etc. Nothing is frozen yet.

Indent using Tabs

Godot uses tabs by default, although it is configurable.

Java code should be indented like the other generators.

Try not to pollute global space (with class_name) ?

Godot does not have namespaces. (for now)

What should we add in the global namespace (via class_name, or perhaps singleton nodes) ?

If we do decide to use class_name (and pollute global space) for models and api, which I suspect we'll need to get nice type defs, we need to set up for all class names a prefix that will act as a namespace.

We can rather easily do this for models with --model-name-prefix, just need to make sure our users know about it. I found --api-name-suffix but no prefix, although it is used in toApiName(). Probably because of lack of support across targets ? Should I add my own --api-name-prefix CLI option or wait ?

snake_case vs camelCase

I'd love some configuration but I won't bother with it until at least I have a working client.

Static typing

Godot does not allow nullable types (we're waiting for them).

This means we either skip types, or try to figure out how to replace null by the appropriate pseudo-null value for the given type. ("" for String, etc.)
But it becomes awkward for int values, where 0 might not be a sensible pseudo-null.

Async

In HTML5 exports, only async is available.
Since it is my personal target, I'll favor it.

Godot 4 has Callables and lambda defs, but no Promises yet.
I think the best method signature for our generated async API method endpoints would be to return a Promise.
But if we start waiting on the promises of Godot… ;)

Therefore, for the first major version of the generator, we'll use Callables in that fashion, unless you have a better idea :

func createUser(
	# … ← generated params from the endpoint schema
	on_success: Callable,  # func(result: User)
	on_failure: Callable  # func(error: ApiError)
):
	pass  # ← method implementation

This function signature is actually very cumbersome to use (see the current state of the demo in samples), because we'll often need to chain requests. We need to find an implementation of Promise in pure GDScript, and fast.

To Singleton or not to Singleton

I tried to avoid using Singletons (aka. Autoloads), so XxxxApi classes are simple RefCounted (plain ol' Godot Object with garbage collection), but that means each XxxxApi holds its own (host, port) configuration to lazily create its client when none was provided. Same goes for extra headers the user wants to send.

You can create the configuration once and pass it to each API class.

---

State of Things

I managed to bootstrap the gdscript target, compile and generate the petstore sample.
Now we need to fill the templates with working code, one feature at a time.

• Models template basic bones
• Apis template basic bones
• Basic Java CodeGen
• Enums
• Datetimes ← using String, shifting timezone responsibility on user
• Model Collections ← using Arrays with dubious recursion support
• Reserved Words ← mostly done, never done
• Configure enabled/disabled features
• Demo / Integration Tests
• Normalization
• Serialization (JSON)
• Model validation of required
• Model validation of constraints (length, etc.)
• Deserialization (JSON) ← my focus
• Deserialization (JSON+LD) ← skipped (ouch)
• Serialization (XML) ← skipped
• Deserialization (XML) ← skipped
• RequestBodies Components
• SecuritySchemes ← hmm
• Response Errors ← may skip
• Unit Tests
• Header customization
• Single host configuration from OAS
• Multiple host configuration from OAS
• HTTPClient async constraint
• HTTPClient reuse through Apis
• Override endpoints for easier template overriding (perhaps via template partials?)
• Bunch of configuration (YAML)
• Bunch of configuration (CLI)

Probably won't do everything on this list myself. Will do enough for my own use, hopefully.

I'm looking at the other language targets and throwing darts. Wish me luck !

Burning questions

1. Is there somewhere a docker image (or whatever) for a server with a working petstore I can use for my demo during dev ?

   Yes → https://github.com/OpenAPITools/openapi-generator/wiki/Integration-Tests (thanks @wing328)

2. Should I use handlebars straight away or keep using mustache, as mildly recommended ? I'm used to (and fond of) jinja2 and Twig (Pebble, for Java).

   Moved to handlebars because the truthy value of mustache includes "" and "null" and that does not play well with {{#example}}.

3. I made a small python script to grab the reserved keywords from Godot's XML. Since it might be useful again when updating the generator to account for changes in Godot, I'd like to keep it close. Where can I store it ? (right now it's in modules/openapi-generator/src/main/resources/gdscript, schmoozing with the templates)

[wing328]

Should I use handlebars straight away or keep using mustache, as mildly recommended ? I'm used to (and fond of) jinja2 and Twig (Pebble, for Java).

It's up to you and I think the community gets used to mustache.

[wing328]

Is there somewhere a docker image (or whatever) for a server with a working petstore I can use for my demo during dev ?

Would this help? https://github.com/OpenAPITools/openapi-generator/wiki/Integration-Tests

[Goutte]

The backbone is here and as I'm getting slowly more proficient in OAS code gen, it's time to delve into tests.

[Goutte]

The doc states:

A simple test script/app to test Petstore (e.g. test.php) to serve as a starting point for developers to easily play with the auto-generated SDK

I can't find any test.php in the source, and I'm not sure where in the repo to put my own test file. (same question for the python util to extract reserved words).

Also, for integration testing, I think I can make a single (or more later as needed) GDScript test file and run it from the CLI, and return an error code > 0 if any test failed.

I can wrap the call(s) into a shell script for convenience. Where should I put such files ?

[Goutte]

godot4 --headless samples/client/petstore/gdscript

🎉 I have a test-suite in the form of a Godot project in samples, that I can run in --headless mode and return a meaningful exit code.

Now, the serious business can finally start…

[Goutte]

I'm glad to announce that the integration test can create a user, log in, and create a pet.
It's very rough around the edges, but it works.

I'm stuck, though

I'm now using that test to do some refactoring and exploration into namespaces.

I can rather easily prefix and suffix the Api and Models with their already-defined parameters. I'm not doing anything, it _just works_®.

Yet I have some core files (base class, error) that I want to be able to customize the same way, using for example coreNamePrefix in the YAML config:

generatorName: gdscript
outputDir: samples/client/petstore/gdscript
inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
templateDir: modules/openapi-generator/src/main/resources/gdscript
additionalProperties:
  hideGenerationTimestamp: "true"
  apiNamePrefix: Demo
  modelNamePrefix: Demo
  coreNamePrefix: Demo

The property coreNamePrefix shows up in the templates, even if not defined in GdscriptClientCodegenOptionsProvider, but even if defined there I can't figure out how to access it from GdscriptClientCodegen's constructor or processOpts().

additionalProperties.containsKey(CORE_NAME_PREFIX) yields false

I want to change the filename when defining my SupportedFile like so :

supportingFiles.add(new SupportingFile("ApiBee.handlebars", "core", toCoreFilename("ApiBee") + ".gd"));

The method toCoreFilename tries to find the coreNamePrefix additional property in additionalProperties and fails. I'm guessing I'm not looking in the right place, or at the right time, or perhaps I overlooked the adequate override.

This probably ties into GdscriptClientCodegenOptionsProvider whose purpose I do not understand anymore, as I thought was used for precisely such custom parameters like coreNamePrefix.

Any lights on these would be appreciated. @wing328 ?

[Goutte]

It was too baffling ; I should have noticed my confusion earlier, but it's only after re-reading my message above that I thought of the wrong assumption I was making.

public static final String CORE_NAME_PREFIX = "coreNamePréfix";

When I wrote this line, I checked against presence in the template, and io and behold the variable was there, so I went merrily on my way.

Textbook confirmation bias.

Got stuck way too long on a sneaky diacritic, but at least I learned a lot about the internals of the generator along the way 🦊 !

[Goutte]

I'm going to take some time and consume a real-world OAS with this, before I carry on and freeze things for MR. Might take a few months.
I'm also not convinced by the Callable approach, since it yields pretty ugly code on usage. (see the demo)

I'm also not comfortable with the feature set configuration, if you have any tips, or any other specific gen I should mirror, I'm all ears.

[wing328]

@Goutte thanks for your work on this. Can you please PM via Slack me when you've time?

https://join.slack.com/t/openapi-generator/shared_invite/zt-12jxxd7p2-XUeQM~4pzsU9x~eGLQqX2g

[Frontrider]

At least Godot 3 has a style guide, that is based on how the c++ code is formatted. I don't think it changed for 4, would be the best to follow this.

https://www.reddit.com/r/godot/comments/yngda3/gdstyle_naming_convention_and_code_order_cheat/
https://www.gdquest.com/docs/guidelines/best-practices/godot-gdscript/

[iamarkdev]

Any updates on this @Goutte ?