nicholass003/topstats

Purpose and Runtime

TopStats is a PHP plugin for PocketMine-MP servers that records player activity metrics and renders ranked in-world leaderboards. PocketMine loads the plugin from plugin.yml; the primary lifecycle/bootstrap class is src/plugin.php. Runtime configuration and database selection are supplied through resources/config.yml and resources/database.yml.

Plugin Bootstrap and Service Wiring

src/plugin.php owns plugin startup/shutdown concerns: loading configuration, initializing persistence, registering listeners/commands, and coordinating leaderboard updates. It is the boundary between PocketMine’s plugin API and internal subsystems. Shared utility behavior resides in src/utils/util.php.

Statistic Collection Pipeline

PocketMine player/game events are subscribed through src/listener/events.php, with event abstractions/handlers in src/event/event.php and src/event/update.php. These translate server activity into statistic increments or updates rather than coupling event handling directly to storage. Supported metric definitions are centralized in src/database/data/type.php; per-player statistic action data is represented by src/database/data/action.php.

Persistence Abstraction and Providers

src/database/idatabase.php defines the database boundary used by the rest of the plugin. Provider implementations support JSON, MySQL, SQLite, and a common SQL layer via src/database/json.php, src/database/mysql.php, src/database/sqlite.php, and src/database/sql.php. SQL schemas are packaged at resources/database/mysql.sql and resources/database/sqlite.sql. Query construction/execution is separated into src/database/query/query.php and src/database/query/action.php, limiting provider-specific persistence concerns.

Leaderboard Lifecycle and Rendering

src/leaderboard/manager.php manages created leaderboard instances, lookup, persistence, and refresh orchestration. src/leaderboard/leaderboard.php represents an individual displayed ranking, including the README-described player-entity and floating-text models. Rankings consume persisted statistics and are refreshed asynchronously/on schedule through src/task/update.php.

Commands and Administrative Control

The /topstats command entry point is src/command/topstats.php. Administrative operations are dispatched to subcommands under src/command/subcommand/, notably creation, deletion, listing, teleportation, model/type selection, and autosave. These commands form the operator-facing boundary for managing leaderboard instances rather than directly exposing storage internals.

External Integration and Scheduling

src/external/external.php and src/external/types.php provide a plugin-facing extension boundary for custom statistics from other plugins; src/external/support/top_voter.php is a concrete supported integration. Periodic update work is isolated in src/task/update.php, preventing ranking/display refresh logic from being embedded in event callbacks. The deployment target is PocketMine-MP; optional infrastructure is local JSON files or configured SQLite/MySQL storage.