Merge remote-tracking branch 'origin/master'

Author: Alumopper

README.md

@@ -1,122 +1,95 @@
-# Sniffer
+> [!NOTE]
+> This project is now being developed by Bookshelf team and has been renamed to Sniffer. Bookshelf has added more features to Sniffer and developed a VSCode plugin! So head over to their repository to stay updated~
+>
+> It's worth mentioning that the original author is still actively contributing to Sniffer's development~
+>
+> Sniffer: <https://github.com/mcbookshelf/sniffer>
 
-## Overview
 
-Sniffer is a debug adapter for Minecraft datapacks that allows you to debug your `.mcfunction` files directly from Visual Studio Code. It provides features like breakpoints, step execution, and variable inspection to make datapack development easier and more efficient.
+# Datapack Breakpoint
 
-## Features
+English | [简体中文](README_zh.md)
 
-- Set breakpoints in `.mcfunction` files
-- Connect to a running Minecraft instance
-- Inspect game state during debugging
-- Step through command execution
-- Path mapping between Minecraft and local files
+## Introduce
 
-## Requirements
+This is a fabric mod for Minecraft 1.21, which allows you to set breakpoints in the game and "freeze" the game when 
+the breakpoint is reached.
 
-- Minecraft with Fabric Loader
-- Visual Studio Code
+## Usage
 
+* Set a breakpoint
 
-<!-- ## Installation
+In datapack, you can insert `#breakpoint` into .mcfunction file to set a breakpoint. For example:
 
-### Minecraft Mod Installation
+```mcfunction
+#test:test
 
-1. Install [Fabric Loader](https://fabricmc.net/use/) for your Minecraft version
-2. Download the Sniffer mod JAR from the [releases page](https://github.com/mcbookshelf/sniffer/releases)
-3. Place the JAR file in your Minecraft `mods` folder
-4. Launch Minecraft with Fabric
-
-### VSCode Extension Installation
-
-1. Open Visual Studio Code
-2. Go to the Extensions view (Ctrl+Shift+X)
-3. Search for "Sniffer"
-4. Click Install -->
-
-## Mod Configuration
-The mod can be configured through the in-game configuration screen, accessible via Mod Menu. 
-You can also configure the mod in the `config/sniffer.json` file.
-The following options are available:
-
-### Debug Server Settings
-- **Server Port**: The port number for the debug server (default: 25599)
-- **Server path**: The path to the debug server (default: `/dap`)
-
-## Connecting to Minecraft
-
-1. Open your datapack project in VSCode
-2. Create a `.vscode/launch.json` file with the following configuration:
-
-```json
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "sniffer",
-      "request": "attach",
-      "name": "Connect to Minecraft",
-      "address": "ws://localhost:25599/dap"
-    }
-  ]
-}
+say 1
+say 2
+#breakpoint
+say 3
+say 4
 ```
 
-3. Start Minecraft with the Sniffer mod installed
-4. In VSCode, press F5 or click the "Run and Debug" button
-5. Select "Connect to Minecraft" from the dropdown menu
+In this case, after the game executes `say 2`, the game will be "frozen" because it meets the breakpoint. 
 
-You can now place breakpoints in your `.mcfunction` files and execute it from the game to step through the code.
+When the game is "frozen", you can still move around, do whatever you want, just like execute the command `tick freeze`.
+So you can check the game state, or do some debugging.
 
-## Usage in Minecraft
+* Step
 
-The debugger can be controlled directly from Minecraft using the following commands:
+When the game is "frozen", you can use the command `/breakpoint step` to execute the next command. In above example, 
+after the game meets the breakpoint, you can use `/breakpoint step` to execute `say 3`, and then use `/breakpoint step`
+to execute `say 4`. When all commands are executed, the game will be unfrozen and continue running.
 
-- `/breakpoint continue`: Resume execution after hitting a breakpoint
-- `/breakpoint step`: Execute the next command and pause
-- `/breakpoint step_over`: Skip to the next command in the current function
-- `/breakpoint step_out`: Continue execution until the current function returns
+* Continue
 
-All commands require operator permissions (level 2) to use.
+When the game is "frozen", you can use the command `/breakpoint move` to unfreeze the game and continue running.
 
-When execution is paused at a breakpoint, the gametick will be freezed.
+* Get Macro Arguments
 
+By using `/breakpoint get <key>`, you can get the value of the macro argument if the game is executing a macro function.
+For example:
 
+```mcfunction
+#test:test_macro
 
-## Development
-
-### Project Structure
+say start
+#breakpoint
+$say $(msg)
+say end
+```
 
-- `src/main`: Main mod code for Minecraft
-- `src/client`: Client-side mod code
-- `vscode`: VSCode extension source code
+After executing `function test:test_macro {"msg":"test"}`, we passed the value `test` to the macro argument `msg` and 
+then the game will pause before `$say $(msg)`. At this time, you can use `/breakpoint get msg` to get the value `test`.
 
-### Building the Project
+* Get Function Stack
 
-To build the Minecraft mod:
+By using `/breakpoint stack`, you can get the function stack of the current game. For example, if we have following two
+functions:
 
-```bash
-./gradlew build
-```
+```mcfunction
+#test:test1
 
-To build the VSCode extension:
+say 1
+function test:test2
+say 2
 
-```bash
-cd vscode
-npm install
-npm run build
+#test: test2
+say A
+#breakpoint
+say B
 ```
 
-## License
+When the game pauses at the breakpoint, you can use `/breakpoint stack` and the function stack will be printed in the
+chat screen:
 
-This project is licensed under the MPL-2.0 License - see the [LICENSE](LICENSE) file for details.
-
-## Contributing
+```
+test:test2
+test:test
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+```
 
-## Acknowledgements
+* Run command in current context
 
-- [Fabric](https://fabricmc.net/) - Mod loader for Minecraft
-- [VSCode Debug Adapter](https://code.visualstudio.com/api/extension-guides/debugger-extension) - VSCode debugging API
-- [Datapack Debugger](https://github.com/Alumopper/Datapack-Debugger/) by [Alumopper](https://github.com/Alumopper) - Original implementation of the debugger, without the DAP layer
+By using `/breakpoint run <command>`, you can run any command in the current context, just like `execute ... run ...`.