feat: Add canonical serialization mode to event and variable serialization

Core/GDCore/Events/Builtin/CommentEvent.cpp

@@ -6,6 +6,7 @@
 
 #include "CommentEvent.h"
 #include "GDCore/CommonTools.h"
+#include "GDCore/Serialization/Serializer.h"
 #include "GDCore/Serialization/SerializerElement.h"
 
 using namespace std;
@@ -29,6 +30,7 @@ bool CommentEvent::ReplaceAllSearchableStrings(
 }
 
 void CommentEvent::SerializeTo(SerializerElement &element) const {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   element.AddChild("color")
       .SetAttribute("r", r)
       .SetAttribute("g", v)
@@ -38,7 +40,7 @@ void CommentEvent::SerializeTo(SerializerElement &element) const {
       .SetAttribute("textB", textB);
 
   element.AddChild("comment").SetValue(com1);
-  if (!com2.empty()) element.AddChild("comment2").SetValue(com2);
+  if (canonical || !com2.empty()) element.AddChild("comment2").SetValue(com2);
 }
 
 void CommentEvent::UnserializeFrom(gd::Project &project,

Core/GDCore/Events/Builtin/ForEachChildVariableEvent.cpp

@@ -6,6 +6,7 @@
 
 #include "ForEachChildVariableEvent.h"
 #include "GDCore/Events/Serialization.h"
+#include "GDCore/Serialization/Serializer.h"
 #include "GDCore/Serialization/SerializerElement.h"
 
 using namespace std;
@@ -81,6 +82,7 @@ vector<pair<const gd::Expression*, const gd::ParameterMetadata> >
 }
 
 void ForEachChildVariableEvent::SerializeTo(SerializerElement& element) const {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   element.AddChild("iterableVariableName").SetValue(iterableVariableName.GetPlainString());
   element.AddChild("valueIteratorVariableName").SetValue(valueIteratorVariableName.GetPlainString());
   element.AddChild("keyIteratorVariableName").SetValue(keyIteratorVariableName.GetPlainString());
@@ -89,13 +91,13 @@ void ForEachChildVariableEvent::SerializeTo(SerializerElement& element) const {
   gd::EventsListSerialization::SerializeInstructionsTo(
       actions, element.AddChild("actions"));
 
-  if (!events.IsEmpty())
+  if (canonical || !events.IsEmpty())
     gd::EventsListSerialization::SerializeEventsTo(events,
                                                   element.AddChild("events"));
-  if (HasVariables()) {
+  if (canonical || HasVariables()) {
     variables.SerializeTo(element.AddChild("variables"));
   }
-  if (!loopIndexVariableName.empty()) {
+  if (canonical || !loopIndexVariableName.empty()) {
     element.AddChild("loopIndexVariable").SetStringValue(loopIndexVariableName);
   }
 }

Core/GDCore/Events/Builtin/ForEachEvent.cpp

@@ -7,6 +7,7 @@
 #include "ForEachEvent.h"
 #include "GDCore/Events/Serialization.h"
 #include "GDCore/Events/Tools/EventsCodeNameMangler.h"
+#include "GDCore/Serialization/Serializer.h"
 #include "GDCore/Serialization/SerializerElement.h"
 
 using namespace std;
@@ -83,25 +84,26 @@ vector<pair<const gd::Expression*, const gd::ParameterMetadata> >
 }
 
 void ForEachEvent::SerializeTo(SerializerElement& element) const {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   element.AddChild("object").SetValue(objectsToPick.GetPlainString());
   gd::EventsListSerialization::SerializeInstructionsTo(
       conditions, element.AddChild("conditions"));
   gd::EventsListSerialization::SerializeInstructionsTo(
       actions, element.AddChild("actions"));
 
-  if (!events.IsEmpty())
+  if (canonical || !events.IsEmpty())
     gd::EventsListSerialization::SerializeEventsTo(events,
                                                   element.AddChild("events"));
-  if (HasVariables()) {
+  if (canonical || HasVariables()) {
     variables.SerializeTo(element.AddChild("variables"));
   }
-  if (!loopIndexVariableName.empty()) {
+  if (canonical || !loopIndexVariableName.empty()) {
     element.AddChild("loopIndexVariable").SetStringValue(loopIndexVariableName);
   }
-  if (!orderBy.GetPlainString().empty()) {
+  if (canonical || !orderBy.GetPlainString().empty()) {
     element.AddChild("orderBy").SetValue(orderBy.GetPlainString());
     element.AddChild("order").SetStringValue(order);
-    if (!limit.GetPlainString().empty()) {
+    if (canonical || !limit.GetPlainString().empty()) {
       element.AddChild("limit").SetValue(limit.GetPlainString());
     }
   }

Core/GDCore/Events/Builtin/RepeatEvent.cpp

@@ -6,6 +6,7 @@
 
 #include "RepeatEvent.h"
 #include "GDCore/Events/Serialization.h"
+#include "GDCore/Serialization/Serializer.h"
 #include "GDCore/Serialization/SerializerElement.h"
 
 using namespace std;
@@ -70,20 +71,21 @@ vector<pair<const gd::Expression*, const gd::ParameterMetadata> >
 }
 
 void RepeatEvent::SerializeTo(SerializerElement& element) const {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   element.AddChild("repeatExpression")
       .SetValue(repeatNumberExpression.GetPlainString());
   gd::EventsListSerialization::SerializeInstructionsTo(
       conditions, element.AddChild("conditions"));
   gd::EventsListSerialization::SerializeInstructionsTo(
       actions, element.AddChild("actions"));
 
-  if (!events.IsEmpty())
+  if (canonical || !events.IsEmpty())
     gd::EventsListSerialization::SerializeEventsTo(events,
                                                   element.AddChild("events"));
-  if (HasVariables()) {
+  if (canonical || HasVariables()) {
     variables.SerializeTo(element.AddChild("variables"));
   }
-  if (!loopIndexVariableName.empty()) {
+  if (canonical || !loopIndexVariableName.empty()) {
     element.AddChild("loopIndexVariable").SetStringValue(loopIndexVariableName);
   }
 }

Core/GDCore/Events/Builtin/StandardEvent.cpp

@@ -9,6 +9,7 @@
 #include "GDCore/Events/CodeGeneration/EventsCodeGenerationContext.h"
 #include "GDCore/Events/CodeGeneration/EventsCodeGenerator.h"
 #include "GDCore/Events/Serialization.h"
+#include "GDCore/Serialization/Serializer.h"
 #include "GDCore/Serialization/SerializerElement.h"
 
 using namespace std;
@@ -50,15 +51,16 @@ vector<gd::InstructionsList*> StandardEvent::GetAllActionsVectors() {
 }
 
 void StandardEvent::SerializeTo(SerializerElement& element) const {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   gd::EventsListSerialization::SerializeInstructionsTo(
       conditions, element.AddChild("conditions"));
   gd::EventsListSerialization::SerializeInstructionsTo(
       actions, element.AddChild("actions"));
 
-  if (!events.IsEmpty())
+  if (canonical || !events.IsEmpty())
     gd::EventsListSerialization::SerializeEventsTo(events,
                                                   element.AddChild("events"));
-  if (HasVariables()) {
+  if (canonical || HasVariables()) {
     variables.SerializeTo(element.AddChild("variables"));
   }
 }

Core/GDCore/Events/Builtin/WhileEvent.cpp

@@ -7,6 +7,7 @@
 #if defined(GD_IDE_ONLY)
 #include "WhileEvent.h"
 #include "GDCore/Events/Serialization.h"
+#include "GDCore/Serialization/Serializer.h"
 #include "GDCore/Serialization/SerializerElement.h"
 
 using namespace std;
@@ -45,6 +46,7 @@ vector<const gd::InstructionsList*> WhileEvent::GetAllActionsVectors() const {
 }
 
 void WhileEvent::SerializeTo(SerializerElement& element) const {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   element.SetAttribute("infiniteLoopWarning", infiniteLoopWarning);
   gd::EventsListSerialization::SerializeInstructionsTo(
       whileConditions, element.AddChild("whileConditions"));
@@ -53,13 +55,13 @@ void WhileEvent::SerializeTo(SerializerElement& element) const {
   gd::EventsListSerialization::SerializeInstructionsTo(
       actions, element.AddChild("actions"));
 
-  if (!events.IsEmpty())
+  if (canonical || !events.IsEmpty())
     gd::EventsListSerialization::SerializeEventsTo(events,
                                                   element.AddChild("events"));
-  if (HasVariables()) {
+  if (canonical || HasVariables()) {
     variables.SerializeTo(element.AddChild("variables"));
   }
-  if (!loopIndexVariableName.empty()) {
+  if (canonical || !loopIndexVariableName.empty()) {
     element.AddChild("loopIndexVariable").SetStringValue(loopIndexVariableName);
   }
 }

Core/GDCore/Events/Serialization.cpp

@@ -230,14 +230,16 @@ void EventsListSerialization::UnserializeEventsFrom(
 
 void EventsListSerialization::SerializeEventsTo(const EventsList& list,
                                                 SerializerElement& events) {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   events.ConsiderAsArrayOf("event");
   for (std::size_t j = 0; j < list.size(); j++) {
     const gd::BaseEvent& event = list.GetEvent(j);
     SerializerElement& eventElem = events.AddChild("event");
 
-    if (event.IsDisabled())
+    if (canonical || event.IsDisabled())
       eventElem.SetAttribute("disabled", event.IsDisabled());
-    if (event.IsFolded()) eventElem.SetAttribute("folded", event.IsFolded());
+    if (canonical || event.IsFolded())
+      eventElem.SetAttribute("folded", event.IsFolded());
     if (!event.GetAiGeneratedEventId().empty())
       eventElem.SetAttribute("aiGeneratedEventId", event.GetAiGeneratedEventId());
     eventElem.AddChild("type").SetValue(event.GetType());
@@ -346,15 +348,16 @@ void gd::EventsListSerialization::UnserializeInstructionsFrom(
 
 void gd::EventsListSerialization::SerializeInstructionsTo(
     const gd::InstructionsList& list, SerializerElement& instructions) {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   instructions.ConsiderAsArrayOf("instruction");
   for (std::size_t k = 0; k < list.size(); k++) {
     SerializerElement& instruction = instructions.AddChild("instruction");
     instruction.AddChild("type").SetAttribute("value", list[k].GetType());
 
-    if (list[k].IsInverted())
-      instruction.GetChild("type").SetAttribute("inverted", true);
-    if (list[k].IsAwaited())
-      instruction.GetChild("type").SetAttribute("await", true);
+    if (canonical || list[k].IsInverted())
+      instruction.GetChild("type").SetAttribute("inverted", list[k].IsInverted());
+    if (canonical || list[k].IsAwaited())
+      instruction.GetChild("type").SetAttribute("await", list[k].IsAwaited());
 
     // Parameters
     SerializerElement& parameters = instruction.AddChild("parameters");
@@ -376,7 +379,7 @@ void gd::EventsListSerialization::SerializeInstructionsTo(
     }
 
     // Sub instructions
-    if (!list[k].GetSubInstructions().empty()) {
+    if (canonical || !list[k].GetSubInstructions().empty()) {
       SerializeInstructionsTo(list[k].GetSubInstructions(),
                               instruction.AddChild("subInstructions"));
     }

Core/GDCore/Project/Variable.cpp

@@ -8,6 +8,7 @@
 
 #include <sstream>
 
+#include "GDCore/Serialization/Serializer.h"
 #include "GDCore/Serialization/SerializerElement.h"
 #include "GDCore/String.h"
 #include "GDCore/Tools/UUID/UUID.h"
@@ -255,10 +256,12 @@ bool Variable::InsertChild(const gd::String& name,
 };
 
 void Variable::SerializeTo(SerializerElement& element) const {
+  const bool canonical = gd::Serializer::IsCanonicalMode();
   element.SetStringAttribute("type", TypeAsString(GetType()));
-  if (IsFolded()) element.SetBoolAttribute("folded", true);
+  if (canonical || IsFolded())
+    element.SetBoolAttribute("folded", IsFolded());
 
-  if (!persistentUuid.empty())
+  if (canonical || !persistentUuid.empty())
     element.SetStringAttribute("persistentUuid", persistentUuid);
 
   if (type == Type::String) {

Core/GDCore/Serialization/Serializer.cpp

@@ -6,8 +6,10 @@
 
 #include "GDCore/Serialization/Serializer.h"
 
+#include <functional>
 #include <iomanip>
 #include <iostream>
+#include <map>
 #include <string>
 #include <utility>
 #include <vector>
@@ -22,6 +24,8 @@ using namespace rapidjson;
 
 namespace gd {
 
+bool Serializer::s_canonicalMode = false;
+
 gd::String Serializer::ToEscapedXMLString(const gd::String& str) {
   return str.FindAndReplace("&", "&amp;")
       .FindAndReplace("'", "&apos;")
@@ -95,19 +99,61 @@ void ElementToRapidJson(const gd::SerializerElement& element,
     const auto& attributes = element.GetAllAttributes();
     const auto& children = element.GetAllChildren();
 
-    for (const auto& attribute : attributes) {
-      Value name(attribute.first.c_str(),
-                 allocator);  // Copying the name is required.
-      Value childValue;
-      ElementToRapidJson(attribute.second, childValue, allocator);
-      value.AddMember(name, childValue, allocator);
-    }
-    for (const auto& child : children) {
-      Value name(child.first.c_str(),
-                 allocator);  // Copying the name is required.
-      Value childValue;
-      ElementToRapidJson(*child.second, childValue, allocator);
-      value.AddMember(name, childValue, allocator);
+    if (gd::Serializer::IsCanonicalMode()) {
+      // In canonical mode, merge attributes and children into a single
+      // alphabetically-sorted sequence so that the resulting JSON has
+      // stable, alphabetical key order. Attributes are stored in a
+      // std::map (already sorted) but children are stored in insertion
+      // order; we re-sort the union here.
+      //
+      // Children with the same name (rare, but allowed) keep their
+      // relative insertion order thanks to std::multimap stability.
+      struct Entry {
+        bool isAttribute;
+        const SerializerValue* attributeValue;     // valid if isAttribute
+        const gd::SerializerElement* childElement; // valid if !isAttribute
+      };
+      std::multimap<gd::String, Entry> sortedEntries;
+
+      for (const auto& attribute : attributes) {
+        sortedEntries.emplace(
+            attribute.first,
+            Entry{true, &attribute.second, nullptr});
+      }
+      for (const auto& child : children) {
+        sortedEntries.emplace(
+            child.first,
+            Entry{false, nullptr, child.second.get()});
+      }
+
+      for (const auto& entry : sortedEntries) {
+        Value name(entry.first.c_str(), allocator);
+        Value childValue;
+        if (entry.second.isAttribute) {
+          // Implicit conversion SerializerValue -> SerializerElement.
+          ElementToRapidJson(
+              *entry.second.attributeValue, childValue, allocator);
+        } else {
+          ElementToRapidJson(
+              *entry.second.childElement, childValue, allocator);
+        }
+        value.AddMember(name, childValue, allocator);
+      }
+    } else {
+      for (const auto& attribute : attributes) {
+        Value name(attribute.first.c_str(),
+                   allocator);  // Copying the name is required.
+        Value childValue;
+        ElementToRapidJson(attribute.second, childValue, allocator);
+        value.AddMember(name, childValue, allocator);
+      }
+      for (const auto& child : children) {
+        Value name(child.first.c_str(),
+                   allocator);  // Copying the name is required.
+        Value childValue;
+        ElementToRapidJson(*child.second, childValue, allocator);
+        value.AddMember(name, childValue, allocator);
+      }
     }
   }
 }

Core/GDCore/Serialization/Serializer.h

@@ -52,10 +52,36 @@ class GD_CORE_API Serializer {
   }
   ///@}
 
+  /** \name Canonical serialization mode.
+   * When enabled, ToJSON writes object keys in alphabetical order and
+   * various SerializeTo helpers write default values (false, "", []) for
+   * properties that would otherwise be omitted.
+   *
+   * This makes git diffs minimal and shift-free when toggling boolean
+   * flags or adding/removing optional sub-structures (e.g. sub-events,
+   * local variables).
+   */
+  ///@{
+  /**
+   * \brief Enable/disable canonical serialization mode globally.
+   *
+   * Affects ToJSON (alphabetical key order) and various SerializeTo helpers
+   * (always writing default values for optional properties).
+   */
+  static void SetCanonicalMode(bool canonical) { s_canonicalMode = canonical; }
+
+  /**
+   * \brief Returns true if canonical serialization mode is currently active.
+   */
+  static bool IsCanonicalMode() { return s_canonicalMode; }
+  ///@}
+
   virtual ~Serializer(){};
 
  private:
   Serializer(){};
+
+  static bool s_canonicalMode;
 };
 
 }  // namespace gd