Saving tutorial only mentions JSON

[nlupugla]

Your Godot version: 4.0.1

Issue description: The current tutorial on saving games only mentions JSON for serializing save data. I understand that generally, we want to discourage users from using JSON as opposed to Godot's built in resource serialization as JSON is less efficient and harder to work with in the engine.

It would be great to have an article discussing the pros and cons of different serialization methods, as well as a few common "gotchas" that people might run in to or perhaps an FAQ section. For instance, why should or shouldn't I save my whole game as one giant packed scene? What security issues should I be aware of when loading game data from custom resources? When I load my game and something breaks, what strategies can I use to debug the problem?

I'm willing to take the lead on writing these docs, but I will need help as I haven't actually made a fully fledged save system in Godot yet and I'm still a new contributor. If you'd like to help out, feel free to @nlupugla in Rocket chat.

URL to the documentation page (if already existing): https://docs.godotengine.org/en/stable/tutorials/io/saving_games.html

[Calinou]

It may also be worth mentioning that if you're saving replays, you should store transforms on a regular basis (every physics frame, or less often to reduce filesize) and not inputs as Godot's physics engine is not deterministic. This means that if you play back the same inputs several times, you will probably get a different outcome – the longer the replay, the more likely this is to happen.

Even with a deterministic physics engine, storing inputs means your replay will break if you fix a movement-related bug or if game balance is changed in any way (unless you keep compatibility toggles available for old replays, which is complex).

[and-rad]

@nlupugla Here is the example project. I kept it minimalistic, but the savegame system has all the necessary features to be used in a simple game right now. You can ignore the character folder, it just contains a character controller to be able to move around the level. The important stuff happens in the savegame and ui folders, and in the game's main level.

I documented everything extensively, but you can always hit me up if things are unclear.

SavegameExamples.zip

[nlupugla]

Hi folks, and especially @and-rad, I've taken a pause on working on updating the saving tutorial in favor of working on making a high-level saving API inspired by the high-level multiplayer API. In the mean time, others are welcome to work on the saving tutorial if they so wish. Meanwhile, I'd love some feedback on the draft of the high-level multiplayer API :) https://github.com/godotengine/godot-proposals/issues/7041

[eswartz]

FWIW, I came across this same docs issue and think it's a little more serious than it seems.

Think about this from the point of view of a new Godot user. If you look at the Manual section for "File and data I/O", I think most people will come away with the conclusion that Godot provides support only for reading/writing 3rd party data ("Runtime file loading and saving") while users need to use JSON for custom purposes ("Saving games").

I understand the appeal of a completely standalone save game format which doesn't leak any details of one's scene tree or the like. But as a high-level entry in the manual, it does a disservice to those learning Godot not to mention up front that Resource and PackedScene can be extended for data serialization, since this allows you to store any other Resource-based object by extension.

I found JSON to be a bad fit because Godot's JSON object doesn't support custom serialization or deserialization (requiring one to resort to var_to_bytes + binary blob encoding for other objects, with mixed results and opaque save game state). And repackaging complex state (esp. with inter-Node references) in JSON is a pain in general, whereas the Resource/PackedScene saving/loading will do this for you.

Like the description hints, JSON is just one choice, not the only one. IMHO, for learning and discoverability, just mentioning the existence of Resource and PackedScene and its potential for user content serialization on this page could be a fine short-term solution to this issue.