Saveload API #79644

nlupugla · 2023-07-18T23:15:12Z

This PR introduces an API and editor interface for saving and loading games inspired by the high level Multiplayer API and based on the discussion in proposal godotengine/godot-proposals#7041. I have been testing the project with a small demo: godotengine/godot-demo-projects#935.

Usage Guide

instructions

The workflow for the Saveload API should be familiar to anyone who has used the high level MultiplayerAPI before. Here are The steps I followed to add saving and loading to the demo project linked above.

Start from a basic "game" without any saving/loading where the player can move and every so often, an "enemy" will spawn.

Add a SaveloadSynchronizer to the main scene.

Click the SaveloadSynchronizer and begin configuring it using the Save Load plugin that appears at the bottom of the editor.

Click the "Add property to sync" button to bring up a list of nodes in the current scene.

Select the "Player" scene to bring up a list of all of it's saveable properties. Almost any Variant type can be selected, including Dictionary and Array. However, Object is not allowed, as a bad actor could theoretically inject malicious code into the save data for an Object, which would run as soon as the harmful save file were loaded.

Choose the position property and observe that the Save Load plugin now displays Player:position as a property to be saved.

Open the "Enemy" scene and repeat.

Back in the Main scene, add a SaveloadSpawner node. The node should show a configuration warning because we haven't yet assigned a Spawn Path.

Use the inspector on the right to assign the Main node as the Spawn Path.

Expand the Auto Spawn List in the SaveloadSpawner inspector pane on the right and click "Add Element" to add the "Enemy" scene to the Auto Spawn List.

We are now down configuring the saving and loading system for this extremely simple "game". All that's left is to call Saveload.save and Saveload.load at the appropriate time. These might be called from a script like so:

func _unhandled_input(event: InputEvent) -> void:
	if event.is_action_pressed(&"save"):
		SaveloadAPI.save("res://TestSave")
	elif event.is_action_pressed(&"open"):
		SaveloadAPI.load("res://TestSave")

Additional Info

The data is saved in a binary format, so the savefile will not be human readable. However, you can use SaveloadAPI.serialize to save your game's data to a Dictionary in memory, which you can then print for debugging purposes.
Several SaveloadAPI functions take a configuration_data parameter, however, this parameter is not currently used, so should be left blank for now.

Edit 2023/July/18 19:36: added link to demo project.

Edit 2023/July/19 14:19: attached zip of demo project
saveload_api.zip

Edit 2023/July/24 18:07: added "finish cleaning up vestigial multiplayer code" to todo list.

Edit 2023/July/25 11:21: added "support multithreading to facilitate loading bars and save wheels" to todo list.

Edit 2023/September/09 11:22: added usage guide

Edit 2023/September/18 13:05: made usage guide collapsible

TODO:

Testing and feedback from other Godot devs
Testing and feedback from Godot users
Finish cleaning up vestigial multiplayer code
Documentation
Allow sub "sections" of the game to be saved and loaded
Support multithreading to facilitate loading bars and save wheels
improve the synchronizer configuration UX with ctrl and shift click multi-select
improve the synchronizer configuration UX with wild card pattern matching
create custom resource format saver and loader for saveload files

…ome problems.

… method declarations in saveload_api.h

AThousandShips · 2023-07-19T07:50:29Z

Translations shouldn't be added or edited manually, they are generated separately and synced from the webplate

Will take a deeper look when I have time!

nlupugla · 2023-07-19T11:20:01Z

Thanks! At some point I did a refactor of Multiplayer -> Saveload and it must have touched more parts of the code than I realized. Should be easy to fix :)

TheYellowArchitect · 2023-07-19T18:03:05Z

If you added the link to the demo project redirect directly to a .zip instead of another issue, there would be more feedback :P

nlupugla · 2023-07-19T18:20:34Z

If you added the link to the demo project redirect directly to a .zip instead of another issue, there would be more feedback :P

Thanks for the interest! I've updated my original post with the zip file :)

TheYellowArchitect · 2023-07-20T19:21:51Z

I cannot run the zipped project in 4.1. The same bug applies when I git clone your your branch saveload_api

Edit: I tried on 4.2dev1 too, same error pretty much

nlupugla · 2023-07-20T19:36:35Z

This feature is still in draft stage, so it hasn't been merged into 4.1 or 4.2 yet.

Try running the demo using an exe compiled from this PR. The easiest way to do it would be to checkout my saveload-api engine branch, compile, then open the project with the newly compiled Godot exe.

I can see if I can attach my custom exe to this PR, but I'm guessing it will be too big and/or github might have security restrictions against uploading exes.

AThousandShips · 2023-07-21T08:04:10Z

modules/saveload/saveload_api.h

+class SaveloadAPI : public RefCounted {
+	GDCLASS(SaveloadAPI, RefCounted);
+
+	static SaveloadAPI *singleton;


It being RefCounted and having a singleton are mutually exclusive, singletons are unique, handled by the system, not created or freed by the user

Thanks for the tip! I figured as much from reading through the error logs, but it's nice to have confirmation that my suspicion was right :)

@AThousandShips In changing from RefCounted to Object, will I have to add some logic to free SaveloadAPI to avoid a memory leak?

All I have for the destructor right now is

virtual ~SaveloadAPI() {}

Look at how it's done in other modules on register/unregister, like navigation with the mesh generator there

You will want to clear the singleton pointer on destruction to be safe

AThousandShips · 2023-07-23T08:52:03Z

I'd recommend using clang-format to ensure that the formatting is correct

nlupugla · 2023-07-23T14:00:30Z

Doh! I set up clang on my desktop but forgot to on my laptop xD

AThousandShips · 2023-07-23T14:25:55Z

modules/saveload/register_types.cpp

+		GDREGISTER_CLASS(SceneSaveloadConfig);
+		GDREGISTER_CLASS(SaveloadSpawner);
+		GDREGISTER_CLASS(SaveloadSynchronizer);
+		GDREGISTER_CLASS(SceneSaveload);


I think this too needs to be abstract, as you should never be able to create one

Huh, really? All of these are concrete classes though. SaveloadSpawner and SaveloadSynchronizer are nodes. SceneSaveload is an implementation of SaveloadAPI. SceneSaveloadConfig is just for configuring the saveload.

I noticed this error in the linux tests.

/home/runner/work/godot/godot/modules/mono/glue/GodotSharp/GodotSharp/Generated/GodotObjects/SceneSaveload.cs(11,22): error CS0709: 'SceneSaveload': cannot derive from static class 'SaveloadApi' [/home/runner/work/godot/godot/modules/mono/glue/GodotSharp/GodotSharp/GodotSharp.csproj]

What even is a static class? 😅

The SceneSaveload specifically, abstract here means limiting construction, the PhysicsServer2D/3D are abstract for example

I believe this is what breaks the mono things, worth testing

Because SceneSaveload implements the abstract SaveloadAPI? I'll try it!

Thanks for all the support with the CI ❤️

…e whether this will appease the .NET tests.

AThousandShips

You also need to update the documentation for @GlobalScope, see the CI, tough you'd need to match the way you name the singleton below, go with either SceneSaveload or SaveloadAPI but make sure you unregister with the same name

Edit: You will have to add documentation for the API for CI to pass

AThousandShips · 2023-07-25T08:00:08Z

modules/saveload/register_types.cpp

+		saveload_api = memnew(SceneSaveload);
+		GDREGISTER_ABSTRACT_CLASS(SaveloadAPI);
+		GDREGISTER_ABSTRACT_CLASS(SceneSaveload);
+		Engine::get_singleton()->add_singleton(Engine::Singleton("SceneSaveload", saveload_api));


Suggested change

Engine::get_singleton()->add_singleton(Engine::Singleton("SceneSaveload", saveload_api));

Engine::get_singleton()->add_singleton(Engine::Singleton("SaveloadAPI", SaveloadAPI::get_singleton(), "SaveloadAPI"));

The unit tests require that singletons be derived directly from Object, and you're using different names for the singletons here and when unregistering

Alternatively:

Suggested change

Engine::get_singleton()->add_singleton(Engine::Singleton("SceneSaveload", saveload_api));

Engine::get_singleton()->add_singleton(Engine::Singleton("SceneSaveload", SaveloadAPI::get_singleton(), "SaveloadAPI"));

But update the unregister

I'm testing these changes locally and running the CI on my repository just to check

Edit: It works mostly now it seems, with these changes

Though it does need a cleanup, and I'd suggest that you don't merge the upstream branch into your branch but rebase it, that makes the commit history much easier to navigate, I spent a bit of time trying to rebase it cleanly and got stuck because of the diverging history there, so wasn't able to test it right now without doing a lot of rebuilding for that reason

Okay, thanks again for all the help!

I'll make those changes to unregister. What file do I need to edit to add documentation?

I'll clean up the git history soon. My first priority is getting a minimum viable product that people can try out, even if things are still a little messy.

Rebasing it to make building more convenient is good, but remember to rebase and not merge in the future for updating the branch

You need to add documentation specifically for the module classes, try building and running --doctool

Did it! Hopefully this one passes finally 🎏

Seems like it passed the .NET tests :D

The logs for editor w/ doubles confuse me. It seems to be failing on something completely unrelated to saveload.

Yeah there's memory capacity issues on the godot-cpp build, sporadically, unrelated to this PR, is happening across different PRs currently

I see, that explains the multiple attempts. Thanks for the info!

You can do it little builder! 🙌

It sounds like the CI is ready to rerun failed builds now. Feel free to give it a spin whenever you have time :)

Woohoo! Passed the CI for real this time :D Thanks for the patience and persistence AThousandShips 💯

…veloadAPI to appease the .NET tests.

nlupugla · 2023-07-26T16:20:04Z

@TheYellowArchitect You should now be able to test this feature by downloading the Godot exe artifact generated from the tests run on this PR.

AThousandShips · 2023-08-07T16:39:14Z

modules/saveload/saveload_synchronizer.h

+	void set_root_path(const NodePath &p_path);
+	NodePath get_root_path() const;
+
+	SaveloadSynchronizer(){};


Suggested change

SaveloadSynchronizer(){};

SaveloadSynchronizer() {}

Huh, something must be messed up with my Clang formatter. When I ran clang, it deleted that extra space, which I thought was funny considering it wanted to add spaces in other places.

It's because you added a semicolon to it, it shouldn't have one here

Oh, I see! That makes sense. Thanks :)

AThousandShips · 2023-08-07T16:39:28Z

modules/saveload/scene_saveload.h

+	virtual Error save(const String &p_path, const Variant &p_configuration_data = Variant()) override;
+	virtual Error load(const String &p_path, const Variant &p_configuration_data = Variant()) override;
+
+	SceneSaveload(){};


Suggested change

SceneSaveload(){};

SceneSaveload() {}

AThousandShips · 2023-08-07T16:39:38Z

modules/saveload/scene_saveload.h

+	virtual Error load(const String &p_path, const Variant &p_configuration_data = Variant()) override;
+
+	SceneSaveload(){};
+	~SceneSaveload(){};


Suggested change

~SceneSaveload(){};

~SceneSaveload() {}

…o save-load-api

nlupugla · 2023-09-09T23:25:40Z

@AThousandShips When you get a chance, can you rerun the CI so I have some build artifacts for people in discord to use? Thanks!

AThousandShips · 2023-09-10T08:12:18Z

The CI is outdated, you need to push again I think

…ve-load-api

nlupugla · 2023-09-10T13:35:25Z

Okay, just pushed! Let me know if I need to do anything else.

…ve-load-api

akien-mga and others added 18 commits June 12, 2023 21:03

Added saveload module

983f2d9

Added saveload module

78f3c48

Changed "replicator" to "saveloader"

4a4b381

Attempted to implement SceneSaveload::encode

2c0eb55

Exposed SaveloadAPI to GDScript.

ce02813

Added and exposed get_state_wrapper (will rename later)

6e7a3c9

Added and exposed get_sync_nodes() to get all synchronizer nodes.

4d2bf18

Tried to implement an intermediate data structure but there's still s…

35b44d6

…ome problems.

Fixed executable crashing immediately by adding = 0 to end of virtual…

16c7d73

… method declarations in saveload_api.h

Removed some print statements

25bfda5

Added icons for Saveload nodes

811b2d8

Implemented loading

9664c3d

Implemented spawning

cda85a6

Started cleaning up vestigial multiplayer code

fe6e029

Spawning now clears tracked nodes before loading

a1a52ee

Cleaned up code

ef98539

Moved saveload from a node property to an engine singleton.

bc835cb

merged with upstream master

810235c

Sauermann added enhancement topic:core topic:editor labels Jul 18, 2023

Sauermann added this to the 4.x milestone Jul 18, 2023

nlupugla added a commit to nlupugla/godot-demo-projects that referenced this pull request Jul 18, 2023

Demo project for testing Saveload API godotengine/godot#79644

9346f99

nlupugla mentioned this pull request Jul 18, 2023

Demo project for testing Saveload API godotengine/godot-demo-projects#935

Draft

Fixed formatting and spurious changes to docs and translations.

635ac55

AThousandShips reviewed Jul 21, 2023

View reviewed changes

Changed SaveloadAPI to an Object from RefCounted.

9566b76

nlupugla added 2 commits July 23, 2023 09:53

Changed SaveloadAPI to an Object from RefCounted.

61d3f17

Merged and fixed formatting issues.

bd4901f

AThousandShips reviewed Jul 23, 2023

View reviewed changes

nlupugla added 3 commits July 23, 2023 11:13

Registered SceneSaveload as abstract.

1ba54e2

Tried to fix module uninitialization.

a95f494

Made singleton instance of SceneSaveload instead of SaveloadAPI to se…

e0458f4

…e whether this will appease the .NET tests.

AThousandShips reviewed Jul 25, 2023

View reviewed changes

nlupugla added 3 commits July 25, 2023 10:47

Added docs and made singleton instance of SceneSaveload instead of Sa…

16d0c6f

…veloadAPI to appease the .NET tests.

Added docs and unregistered SceneSaveload to appease the .NET tests.

ee33b11

Unregistered SceneSaveload to appease the .NET tests.

7f7f2ad

nlupugla added 3 commits July 27, 2023 20:28

Cleaned out more vestigial multiplayer code.

4e0c232

Cleaned out more vestigial multiplayer code.

ac1ee57

Fixed style to make Clang happy

95b8889

AThousandShips reviewed Aug 7, 2023

View reviewed changes

nlupugla added 2 commits August 7, 2023 15:22

Fixed style to make Clang happy

3328268

Merge branch 'save-load-api' of https://github.com/nlupugla/godot int…

1148fc8

…o save-load-api

Merge branch 'master' of https://github.com/godotengine/godot into sa…

c4ca104

…ve-load-api

nlupugla added 2 commits September 18, 2023 12:29

Merge branch 'master' of https://github.com/godotengine/godot into sa…

847aec0

…ve-load-api

Properly encapsulated module by moving docs and icons

3450058

nlupugla mentioned this pull request Sep 21, 2023

Create high-level saving/loading API similar to high-level multiplayer API godotengine/godot-proposals#7041

Open

KoBeWi mentioned this pull request Feb 20, 2024

Can this work for Godot 4+ games with multiplayer and open world chunks? KoBeWi/The-Soulhunter#2

Open

	Engine::get_singleton()->add_singleton(Engine::Singleton("SceneSaveload", saveload_api));
	Engine::get_singleton()->add_singleton(Engine::Singleton("SaveloadAPI", SaveloadAPI::get_singleton(), "SaveloadAPI"));

Saveload API #79644

Are you sure you want to change the base?

Saveload API #79644

Conversation

nlupugla commented Jul 18, 2023 • edited Loading

Usage Guide

Additional Info

AThousandShips commented Jul 19, 2023 • edited Loading

nlupugla commented Jul 19, 2023

TheYellowArchitect commented Jul 19, 2023

nlupugla commented Jul 19, 2023

TheYellowArchitect commented Jul 20, 2023 • edited Loading

nlupugla commented Jul 20, 2023

AThousandShips Jul 21, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AThousandShips Jul 21, 2023 • edited Loading

Choose a reason for hiding this comment

AThousandShips commented Jul 23, 2023

nlupugla commented Jul 23, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AThousandShips Jul 23, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AThousandShips left a comment • edited Loading

Choose a reason for hiding this comment

AThousandShips Jul 25, 2023 • edited Loading

Choose a reason for hiding this comment

AThousandShips Jul 25, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nlupugla commented Jul 26, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nlupugla commented Sep 9, 2023

AThousandShips commented Sep 10, 2023 • edited Loading

nlupugla commented Sep 10, 2023

nlupugla commented Jul 18, 2023 •

edited

Loading

AThousandShips commented Jul 19, 2023 •

edited

Loading

TheYellowArchitect commented Jul 20, 2023 •

edited

Loading

AThousandShips Jul 21, 2023 •

edited

Loading

AThousandShips Jul 21, 2023 •

edited

Loading

AThousandShips Jul 23, 2023 •

edited

Loading

AThousandShips left a comment •

edited

Loading

AThousandShips Jul 25, 2023 •

edited

Loading

AThousandShips Jul 25, 2023 •

edited

Loading

AThousandShips commented Sep 10, 2023 •

edited

Loading