How rptools/maptool works
Primary architectural components
• Client Application:
– This is found under packages like "net.rptools.maptool.client" (and its numerous subpackages for UI, tools, macro management, and chat).
– It uses Swing (and some JavaFX integration) for the user interface and includes modules for the drawing canvas, token management, chat panels, and extra client-side features (asset management, preferences, etc.).
• Communication/Connection Subsystem:
– The “clientserver” package and the classes for connection types (AbstractConnection, SocketConnection, WebRTCConnection) indicate an abstraction layer that handles network communications between the client and a central server.
– Also, note the "protocol" and "proto" definitions that define the message and data transfer objects. These define a standardized messaging protocol between client and server.
• Server/Backend Component:
– Found under "net.rptools.maptool.server" and related classes (MapToolServer, Handshake classes, ServerCommand, etc.).
– This component processes incoming client connections, synchronizes game state (such as campaign data, tokens, and zones), and orchestrates the overall multiplayer session.
• Core Business and Domain Logic:
– Located in the "net.rptools.maptool.model" package (and related subpackages).
– This area handles the game state (campaigns, tokens, zones, macros, drawing objects) as well as linking them to display and interactions.
• Dice and Expression Engine:
– Housed within "net.rptools.dicelib" packages, these components provide support for dice rolls and text-based formula evaluations, which are essential to role-playing games.
• Utility & Shared Libraries:
– General-purpose utilities, file I/O, networking utilities, logging, and resource management reside in "net.rptools.lib", "net.rptools.util", etc.
– Resources (graphics, sounds, language files) are stored under the "src/main/resources" tree.
Relationships and data flows
• The Client Application interacts with end-users via its rich UI and then dispatches commands (for chat, macro triggers, or token updates) to the Communication Subsystem.
• The Communication Subsystem provides an abstraction that allows different types of connections (socket-based, WebRTC) to pass messages from client to server and vice versa.
• The Server receives commands and updates from clients, accesses or modifies the shared game state managed by the Domain Model, and then dispatches updates back to the clients.
• The Protocol layer encapsulates message formats (defined by Proto files) that standardize data exchange.
Architectural patterns and design principles
• Separation of Concerns: Notice how UI code is completely separate from the domain logic (Model) and the communication layer.
• Client-Server Architecture: The clear boundary between the client (UI and local game logic) and the remotely hosted game/server.
• Plugin/Extension points: The use of macros, customizable token overlays, and support for external scripts indicate that the system is designed to be extensible.
• Event-Driven and Observer Patterns: Look for the “events” packages (e.g., MapToolEventBus, token events) which are used to notify different parts of the system about state changes.
Relevant technologies
• Java (core language, Gradle build system).
• Swing and JavaFX for UI.
• Protocol Buffers (Protobuf definitions in src/main/proto).
• Networking abstractions (including WebRTC and Socket connections).
• Crowdin for localization (as referenced in the README banners).
Overall, be as detailed as possible
• The goal is not to oversimplify the architecture but to capture the major modules and their interactions.
• Clear separation between the user event producers, the network/communication layer, and the server’s state-management systems.
• This granularity will help when evolving or debugging the architecture.