Merge branch 'main' into dev

Author: okunamayanad

content/docs/en/guides/plugin/store-persistant-data.mdx

@@ -0,0 +1,135 @@
+---
+title: "Storing Persistant Data on the Player"
+description: "Learn how to save and load persistant data using Components"
+authors:
+	- name: "ArcticDev"
+	  url: "https://github.com/ArcticRaven"
+	- name: "Neil Revin"
+	  url: "https://itsneil.dev/"
+---
+
+Here is how to store persistent data using a custom component on a Player.
+
+## Build your Component Class
+
+Creating a custom component class leverages the Component system made with the ECS architecture in mind. For more information on Components, check out the [ECS Guide](../ecs/hytale-ecs-theory.mdx#components).
+
+Start by creating your custom component class. This will be extremely similar to how regular components are created, however we'll setup a custom Codec so the server can translate this data to BSON, or the server's internal json encoder.
+
+<Callout type="info">
+Each variable you want to store in your component must have its own Codec field defined in the BuilderCodec.
+Since the codec system is lambda based, you provide a setter and getter for each field.
+
+Using complex data types (like Lists, Maps, etc) is possible, but can get tricky.
+Refer to the available Codec types in the `Server.jar/com/hypixel/hytale/codec/` package for more information on what types are available.
+
+Note that the 'key' used in the KeyedCodec must start with a Capital Letter, otherwise it may not serialize properly.
+</Callout>
+
+```java
+public class YourPlayerData implements Component<EntityStore> {
+
+    // define some vars!
+    private int someInteger;
+    private String someString;
+    private Map<String, String> someMap;
+
+    public static final BuilderCodec<YourPlayerData> CODEC =
+            BuilderCodec.builder(YourPlayerData.class, YourPlayerData::new)
+            .addField(new KeyedCodec<>("SomeInteger", Codec.INTEGER),
+                    (data, value) -> data.someInteger = value, // setter
+                    data -> data.someInteger) // getter
+            .addField(new KeyedCodec<>("SomeString", Codec.STRING),
+                    (data, value) -> data.someString = value, // setter
+                    data -> data.someString) // getter
+            .addField(new KeyedCodec<>("SomeMap",
+                            new MapCodec<>(Codec.STRING, HashMap::new, false)),
+                    (data, value) -> data.someMap = value, // setter
+                    data -> data.someMap) // getter
+            .build();
+
+
+
+    // Getters and Setters are for the purpose of this example omitted.
+
+    // constructor
+    public YourPlayerData() {
+        this.someInteger = 0;
+        this.someString = "";
+        this.someMap = new HashMap<>();
+    }
+
+    // copy constructor for cloning
+    public YourPlayerData(YourPlayerData clone) {
+        this.someInteger = clone.someInteger;
+        this.someString = clone.someString;
+        this.someMap = clone.someMap;
+    }
+
+    @NullableDecl
+    @Override
+    public Component<EntityStore> clone() {
+        return new YourPlayerData(this);
+    }
+}
+```
+
+## Register your Component
+Inside your main class's `setup()` method, register your new Component.
+
+```java
+public class YourPlugin extends JavaPlugin {
+
+    private ComponentType<EntityStore, YourPlayerData> yourPlayerDataComponent;
+
+    public YourPlugin(@NonNullDecl JavaPluginInit init) {
+        super(init);
+    }
+
+    @Override
+    protected void setup(){
+        this.yourPlayerDataComponent = this.getEntityStoreRegistry().registerComponent(
+            YourPlayerData.class,
+            "YourPlayerDataComponent",
+            YourPlayerData.CODEC
+        );
+    }
+
+    public ComponentType<EntityStore, YourPlayerData> getYourPlayerDataComponent() {
+        return this.yourPlayerDataComponent;
+    }
+}
+```
+
+## Using your Data
+
+Your component will be stored within the `Store<EntityStore>` when added to the player. In the provided example,
+we'll fetch this data off the player using the `ensureAndGetComponent()` method, which will add the component to
+the player if it does not exist.
+
+```java
+public class IncompleteCustomCommand extends AbstractPlayerCommand {
+
+    public IncompleteCustomCommand() {
+        super("nope", "don't use this command");
+    }
+
+    @Override
+    protected void execute(
+        @NonNullDecl CommandContext commandContext,
+        @NonNullDecl Store<EntityStore> store,
+        @NonNullDecl Ref<EntityStore> ref,
+        @NonNullDecl PlayerRef playerRef,
+        @NonNullDecl World world
+    ) {
+        YourPlayerData customData = store.ensureAndGetComponent(ref, YourPlugin.instance().getYourPlayerDataComponent());
+
+ 		// use your data
+    }
+}
+```
+
+And that's it! Your data will now be saved and loaded automatically with the player.
+
+## Conclusion
+Using custom components to store persistent data on players is a powerful way to maintain state across sessions. By following the steps outlined above, you can easily create, register, and utilize your own data structures within the Hytale modding framework. This approach ensures that your data is seamlessly integrated with the game's existing systems, providing a robust solution for managing player-specific information. Happy modding!