Differences

This shows you the differences between two versions of the page.

--- rpd:modding_platform_abstraction [2025/12/25 18:23] – auto lint fix Mikhael
+++ rpd:modding_platform_abstraction [2025/12/25 18:24] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+====== Platform Abstraction System for Modders ======
+The Remixed Dungeon project uses a sophisticated platform abstraction system that allows the game to run on multiple platforms (Android, Desktop, Web) and distribution channels (Google Play, F-Droid, ruStore, etc.) while sharing the majority of core game logic. Understanding this system is crucial for developing cross-platform mods.
+===== Overview =====
+The platform abstraction system separates platform-specific functionality from the core game code using:
+  * **Interface-based abstraction** - Common interfaces and base classes that define contracts for platform-specific functionality
+  * **Class replacement** - Different implementations of the same class for different platforms
+  * **Build system integration** - Platform-specific code inclusion at build time
+===== Key Concepts for Modders =====
+==== Market Separation ====
+The game uses product flavors to support different markets:
+  * **Google Play** - Full analytics and crash reporting through Firebase
+  * **F-Droid** - No analytics, stub implementations to meet F-Droid requirements
+  * **ruStore** - Russian market specific features
+  * **Desktop** - No analytics, file-based storage
+  * **Web** - Browser-based functionality
+==== EventCollector Example ====
+One of the most important examples for modders is the **EventCollector** class, which handles analytics and crash reporting:
+  * **Core Usage** (in your mod code):
+    <code java>
+    import com.nyrds.platform.EventCollector;
+    // Used throughout your mod
+    EventCollector.logEvent("mod_started");
+    EventCollector.logException(e);
+    </code>
+  * **Market-Specific Implementations**:
+    * ''src/googlePlay/java/com/nyrds/platform/EventCollector.java'' - Full Firebase implementation
+    * ''src/fdroid/java/com/nyrds/platform/EventCollector.java'' - Empty stub implementation
+    * ''src/ruStore/java/com/nyrds/platform/EventCollector.java'' - Minimal logging implementation
+    * ''src/libgdx/java/com/nyrds/platform/EventCollector.java'' - Desktop implementation
+The build system automatically selects the correct implementation based on the selected flavor.
+==== Preferences System ====
+The preferences system is another important abstraction:
+  * **Android** - Uses encrypted SharedPreferences
+  * **Desktop** - Uses HJSON file-based storage
+  * **Web** - Uses browser localStorage
+===== Creating Platform-Aware Mods =====
+When creating mods that need platform-specific features:
+==== 1. Use Platform Abstractions ====
+Always use the existing platform abstraction classes rather than platform-specific APIs directly:
+<code java>
+// Good - uses platform abstraction
+import com.nyrds.platform.storage.Preferences;
+Preferences.INSTANCE.put("music_volume", 0.8);
+float volume = Preferences.INSTANCE.getFloat("music_volume", 1.0f);
+// Avoid - platform-specific APIs
+SharedPreferences prefs = context.getSharedPreferences(...); // Android-only
+</code>
+==== 2. Check Platform Capabilities ====
+For complex platform-specific functionality, you can check which platform you're on:
+<code java>
+import com.nyrds.platform.PlatformSupport;
+if(PlatformSupport.isAndroid()) {
+    // Android-specific code
+} else if(PlatformSupport.isDesktop()) {
+    // Desktop-specific code
+}
+</code>
+==== 3. Add Platform-Specific Implementations ====
+If your mod needs platform-specific functionality, create the abstraction in your mod the same way the main game does:
+. Define the interface or abstract class in your shared code
+. Implement platform-specific versions in respective flavor directories
+. Use the same fully-qualified class name for all implementations
+===== Cross-Platform Testing =====
+When developing mods, test on multiple platforms if possible, particularly:
+  * **Android Google Play** - Full feature set
+  * **Android F-Droid** - No analytics, may have different feature restrictions
+  * **Desktop** - Different storage and input methods
+===== Common Platform Abstractions =====
+==== Storage ====
+  * **Preferences** - Key-value storage
+  * **FileSystem** - File operations with SAF support on Android
+==== Audio ====
+  * **MusicManager** - Background music
+  * **Sample** - Sound effects
+==== Analytics ====
+  * **EventCollector** - Logging events and exceptions
+==== Input ====
+  * **Touchscreen** - Touch and mouse input abstraction
+  * **Keys** - Keyboard input abstraction
+===== Best Practices for Modders =====
+  - Always use the existing platform abstraction classes
+  - Test your mod on different platform flavors when possible
+  - Use stub implementations in F-Droid flavor to comply with privacy requirements
+  - Follow the package structure used by the main game
+  - Don't make assumptions about platform-specific behavior
+Understanding the platform abstraction system will help you create mods that work across all platforms and distribution channels where Remixed Dungeon is available.