Overhaul plugin examples to focus on essential patterns

- Simplify to one /hello command showing isinstance sender checks
  (Player vs ConsoleCommandSender) and config.toml usage
- Simplify listener to player join/quit with custom messages
- Add default config.toml for save_default_config() demo
- Remove separate CommandExecutor, scheduler, permission attachment,
  priority, and ServerListPingEvent examples

Author: wu-vincent

CHANGELOG.md

@@ -7,15 +7,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### Changed
+- Overhauled plugin examples to focus on essential patterns: lifecycle, config, commands, events
+- Simplified to one command (`/hello`) demonstrating `isinstance` sender checks and config usage
+- Simplified listener to player join/quit with custom messages
+- Removed scheduler, permission attachment, and priority examples (too advanced for a starter template)
 - Modernized build system with hatch-vcs for automatic git-tag versioning
 - Switched from pip to uv for dependency management and builds
 - Updated minimum Python version to 3.10
 - Bumped api_version from 0.6 to 0.11
-- Simplified source file names (plugin.py, listener.py, command.py)
+- Simplified source file names (plugin.py, listener.py)
 - CI now runs linting (ruff)
 - Replaced publish workflow with full release automation (changelog, tagging, PyPI, GitHub release)
 
 ### Added
+- Default config.toml demonstrating plugin configuration
 - Ruff linting configuration
 - Dependabot for automated dependency updates
 - CHANGELOG.md following Keep a Changelog format
+
+### Removed
+- Separate CommandExecutor class (command.py); on_command approach is simpler for examples

README.md

@@ -3,7 +3,7 @@
 [![Build](https://github.com/EndstoneMC/python-example-plugin/actions/workflows/build.yml/badge.svg)](https://github.com/EndstoneMC/python-example-plugin/actions/workflows/build.yml)
 
 An example Python plugin for [Endstone](https://github.com/EndstoneMC/endstone) servers, demonstrating commands,
-events, permissions, scheduled tasks, and separate listener/executor classes.
+events, configuration, and permissions.
 
 ## Prerequisites
 
@@ -46,9 +46,9 @@ python-example-plugin/
 ├── src/
 │   └── endstone_example/
 │       ├── __init__.py       # Package entry point, re-exports ExamplePlugin
-│       ├── plugin.py         # Plugin class with commands, events, scheduler
-│       ├── listener.py       # Separate event listener class
-│       └── command.py        # Custom CommandExecutor for /python
+│       ├── plugin.py         # Plugin class: lifecycle, config, commands
+│       ├── listener.py       # Event listener: player join/quit
+│       └── config.toml       # Default plugin configuration
 ├── .github/
 │   ├── dependabot.yml       # Automated dependency updates
 │   └── workflows/

src/endstone_example/command.py

@@ -0,0 +1,2 @@
+# The greeting message sent by the /hello command
+greeting = "Hello"

src/endstone_example/config.toml

@@ -1,32 +1,18 @@
-import datetime
-
 from endstone import ColorFormat
-from endstone.event import EventPriority, PlayerJoinEvent, PlayerQuitEvent, ServerListPingEvent, event_handler
+from endstone.event import PlayerJoinEvent, PlayerQuitEvent, event_handler
 from endstone.plugin import Plugin
 
 
 class ExampleListener:
     def __init__(self, plugin: Plugin) -> None:
         self._plugin = plugin
 
-    @event_handler(priority=EventPriority.HIGHEST)
-    def on_server_list_ping(self, event: ServerListPingEvent) -> None:
-        event.motd = ColorFormat.BOLD + ColorFormat.AQUA + datetime.datetime.now().strftime("%c")
-        addr = event.address
-        event.level_name = f"Your IP is {ColorFormat.YELLOW}{addr.hostname}:{addr.port}{ColorFormat.RESET}"
-
     @event_handler
     def on_player_join(self, event: PlayerJoinEvent) -> None:
         player = event.player
-        self._plugin.logger.info(
-            ColorFormat.YELLOW + f"{player.name}[/{player.address}] joined the game with UUID {player.unique_id}"
-        )
-
-        # example of explicitly removing one's permission of using /me command
-        player.add_attachment(self._plugin, "minecraft.command.me", False)
-        player.update_commands()  # don't forget to resend the commands
+        event.join_message = f"{ColorFormat.YELLOW}{player.name} joined the game"
+        self._plugin.logger.info(f"{player.name} joined from {player.address}")
 
     @event_handler
     def on_player_quit(self, event: PlayerQuitEvent) -> None:
-        player = event.player
-        self._plugin.logger.info(ColorFormat.YELLOW + f"{player.name}[/{player.address}] left the game.")
+        event.quit_message = f"{ColorFormat.YELLOW}{event.player.name} left the game"

src/endstone_example/listener.py

@@ -1,92 +1,48 @@
-import datetime
-
-from endstone.command import Command, CommandSender
-from endstone.event import EventPriority, ServerLoadEvent, event_handler
+from endstone import Player
+from endstone.command import Command, CommandSender, ConsoleCommandSender
 from endstone.plugin import Plugin
 
-from endstone_example.command import PythonCommandExecutor
 from endstone_example.listener import ExampleListener
 
 
 class ExamplePlugin(Plugin):
-    prefix = "PythonExamplePlugin"
+    prefix = "ExamplePlugin"
     api_version = "0.11"
-    load = "POSTWORLD"
 
     commands = {
-        "python": {
-            "description": "Zen of python",
-            "usages": ["/python"],
-            "aliases": ["py"],
-            "permissions": ["python_example.command.python"],
-        },
-        "kickme": {
-            "description": "Ask the server to kick you with a custom message",
-            "usages": ["/kickme [reason: message]"],
-            "permissions": ["python_example.command.kickme"],
+        "hello": {
+            "description": "Send a greeting",
+            "usages": ["/hello"],
+            "permissions": ["example.command.hello"],
         },
     }
 
     permissions = {
-        "python_example.command": {
-            "description": "Allow users to use all commands provided by this plugin.",
-            "default": True,
-            "children": {
-                "python_example.command.python": True,
-                "python_example.command.kickme": True,
-            },
-        },
-        "python_example.command.python": {
-            "description": "Allow users to use the /python command.",
-            "default": "op",
-        },
-        "python_example.command.kickme": {
-            "description": "Allow users to use the /kickme command.",
+        "example.command.hello": {
+            "description": "Allow users to use the /hello command.",
             "default": True,
         },
     }
 
-    def on_load(self) -> None:
-        self.logger.info("on_load is called!")
-
     def on_enable(self) -> None:
-        self.logger.info("on_enable is called!")
-        self.get_command("python").executor = PythonCommandExecutor()
-
-        self.register_events(self)  # register event listeners defined directly in Plugin class
-        self.register_events(ExampleListener(self))  # you can also register event listeners in a separate class
-
-        self.server.scheduler.run_task(self, self.log_time, delay=0, period=20 * 1)  # every second
+        self.save_default_config()
+        self.register_events(ExampleListener(self))
+        self.logger.info("ExamplePlugin enabled!")
 
     def on_disable(self) -> None:
-        self.logger.info("on_disable is called!")
+        self.logger.info("ExamplePlugin disabled!")
 
     def on_command(self, sender: CommandSender, command: Command, args: list[str]) -> bool:
-        # You can also handle commands here instead of setting an executor in on_enable if you prefer
         match command.name:
-            case "kickme":
-                player = sender.as_player()
-                if player is None:
-                    sender.send_error_message("You must be a player to execute this command.")
-                    return False
-
-                if len(args) > 0:
-                    player.kick(args[0])
+            case "hello":
+                greeting = self.config["greeting"]  # from config.toml
+
+                # Use isinstance to check the sender type
+                if isinstance(sender, Player):
+                    sender.send_message(f"{greeting}, {sender.name}!")
+                elif isinstance(sender, ConsoleCommandSender):
+                    self.logger.info(f"{greeting} from the console!")
                 else:
-                    player.kick("You asked for it!")
+                    sender.send_message(f"{greeting}!")
 
         return True
-
-    @event_handler
-    def on_server_load(self, event: ServerLoadEvent) -> None:
-        self.logger.info(f"{event.event_name} is passed to on_server_load")
-
-    @event_handler(priority=EventPriority.HIGH)
-    def on_server_load_2(self, event: ServerLoadEvent) -> None:
-        # this will be called after on_server_load because of a higher priority
-        self.logger.info(f"{event.event_name} is passed to on_server_load2")
-
-    def log_time(self) -> None:
-        now = datetime.datetime.now().strftime("%c")
-        for player in self.server.online_players:
-            player.send_popup(now)