diff --git a/docs/en/plugins/classes.md b/docs/en/plugins/classes.md new file mode 100644 index 0000000..8c754b5 --- /dev/null +++ b/docs/en/plugins/classes.md @@ -0,0 +1,245 @@ +Sure, here's a translation of the text: + +# Passed Classes + +## Worth looking at + +1. What are `*args` and `**kwargs`? -> [Post on Habr (RU)](https://habr.com/ru/companies/ruvds/articles/482464/) + +## KuiToi +_`kt = KuiToi("PluginName"")`_ + +### kt.log +_Constant_\ +Returns a pre-configured logger + +### kt.name +_Constant_\ +Returns the name of the plugin + +### kt.dir +_Constant_\ +Returns the directory of the plugin + +### kt.open() +_Parameters are the same as for open()_\ +Opens a file in kt.dir + +### kt.register_event(event_name: str, event_func: function) +_`event_name: str` -> The name of the event that `event_func` will be called on._\ +_`event_func: function` -> The function that will be called._ + +In `event_func`, you can pass both regular functions and async functions - you don't need to make them async beforehand.\ +You can also create your own events with your own names.\ +You can register an unlimited number of events. + +### kt.call_event(event_name: str, *args, **kwargs) -> list: +_`event_name: str` -> The name of the event to call._\ +_`*args, **kwargs` -> Arguments to be passed to the function._ + +### **async** kt.call_async_event(event_name: str, *args, **kwargs) -> list: +_`event_name: str` -> The name of the event to call._\ +_`*args, **kwargs` -> Arguments to be passed to the function._\ +_Must be called with `await`_ + +###### _I recommend familiarizing yourself with *args, **kwargs_, there is a link at the beginning +Data is passed to all events in the form of: `{"event_name": event_name, "args": args, "kwargs": kwargs}`\ +`args: list` -> Represents an array of data passed to the event\ +`kwargs: dict` -> Represents a dictionary of data passed to the event +The data will be returned from all successful attempts in an array. + +### kt.call_lua_event(event_name: str, *args) -> list: +_`event_name: str` -> The name of the event to call._\ +_`*args` -> Arguments to be passed to the function._ + +Added to support backward compatibility.\ +The lua function is called with a direct transmission of arguments `lua_func(*args)` + +### kt.get_player([pid: int], [nick: str]) -> Player | None: +_`pid: int` -> Player ID - The identifier of the player._\ +_`nick: str` -> Player Nickname - The name of the player._ + +The method returns a player object by their `pid` or `nick`.\ +If the player cannot be found, `None` will be returned. + +### kt.get_players() -> List[Player] | list: + +The method returns an array with all players.\ +The array will be empty if there are no players. + +### kt.players_counter() -> int: + +The method returns the number of players currently online. + +### kt.is_player_connected([pid: int], [nick: str]) -> bool: +_`pid: int` -> Player ID - The identifier of the player._\ +_`nick: str` -> Player Nickname - The name of the player._ + +The method returns a player object by their `pid` or `nick`. + +## Player (or Client) +_`pl = kt.get_player()`_\ +_`pl = event_data['kwargs']['player']`_ + +### pl.log -> Logger +_Constant_\ +Returns a pre-configured logger + +### pl.addr -> str +_Constant_\ +Returns the IP address of the player + +### pl.pid -> int +### pl.cid -> int +_Constant_\ +Returns the client ID _(pid: PlayerId = cid: ClientId)_ + +### pl.key -> str +_Constant_\ +Returns the key passed during authentication + +### pl.nick -> str +_Variable_\ +The nickname passed during authentication from the BeamMP server, can be changed, consequences are untested + +### pl.roles -> str +_Variable_\ +The role passed during authentication from the BeamMP server, can be changed (if an incorrect role is set, unexpected things may happen.) + +### pl.guest -> bool +_Constant_\ +Returns whether the player is a guest, passed during authentication from the BeamMP server + +### pl.identifiers -> dict +_Constant_\ +Identifiers passed during authentication from the BeamMP server. + +### pl.ready -> bool +_Constant, changed by the core_\ +Returns a bool value, if True -> the player has downloaded all resources, loaded on the map + +### pl.cars -> dict +_Constant, changed by the core_\ +Returns a dictionary of cars like thisSure, here's the translation: + +# Passed Classes + +## Worth looking at + +1. What are `*args` and `**kwargs`? -> [Post on Habr ↗](https://habr.com/ru/companies/ruvds/articles/482464/) + +## KuiToi +_`kt = KuiToi("PluginName"")`_ + +### kt.log +_Constant_\ +Returns a pre-configured logger + +### kt.name +_Constant_\ +Returns the name of the plugin + +### kt.dir +_Constant_\ +Returns the directory of the plugin + +### kt.open() +_Parameters are the same as for open()_\ +Opens a file in kt.dir + +### kt.register_event(event_name: str, event_func: function) +_`event_name: str` -> The name of the event that `event_func` will be called on._\ +_`event_func: function` -> The function that will be called._ + +In `event_func`, you can pass both regular functions and async functions - you don't need to make them async beforehand.\ +You can also create your own events with your own names.\ +You can register an unlimited number of events. + +### kt.call_event(event_name: str, *args, **kwargs) -> list: +_`event_name: str` -> The name of the event to call._\ +_`*args, **kwargs` -> Arguments to be passed to the function._ + +### **async** kt.call_async_event(event_name: str, *args, **kwargs) -> list: +_`event_name: str` -> The name of the event to call._\ +_`*args, **kwargs` -> Arguments to be passed to the function._\ +_Must be called with `await`_ + +###### _I recommend familiarizing yourself with *args, **kwargs_, there is a link at the beginning +Data is passed to all events in the form of: `{"event_name": event_name, "args": args, "kwargs": kwargs}`\ +`args: list` -> Represents an array of data passed to the event\ +`kwargs: dict` -> Represents a dictionary of data passed to the event +The data will be returned from all successful attempts in an array. + +### kt.call_lua_event(event_name: str, *args) -> list: +_`event_name: str` -> The name of the event to call._\ +_`*args` -> Arguments to be passed to the function._ + +Added to support backward compatibility.\ +The lua function is called with a direct transmission of arguments `lua_func(*args)` + +### kt.get_player([pid: int], [nick: str]) -> Player | None: +_`pid: int` -> Player ID - The identifier of the player._\ +_`nick: str` -> Player Nickname - The name of the player._ + +The method returns a player object by their `pid` or `nick`.\ +If the player cannot be found, `None` will be returned. + +### kt.get_players() -> List[Player] | list: + +The method returns an array with all players.\ +The array will be empty if there are no players. + +### kt.players_counter() -> int: + +The method returns the number of players currently online. + +### kt.is_player_connected([pid: int], [nick: str]) -> bool: +_`pid: int` -> Player ID - The identifier of the player._\ +_`nick: str` -> Player Nickname - The name of the player._ + +The method returns a player object by their `pid` or `nick`. + +## Player (or Client) +_`pl = kt.get_player()`_\ +_`pl = event_data['kwargs']['player']`_ + +### pl.log -> Logger +_Constant_\ +Returns a pre-configured logger + +### pl.addr -> str +_Constant_\ +Returns the IP address of the player + +### pl.pid -> int +### pl.cid -> int +_Constant_\ +Returns the client ID _(pid: PlayerId = cid: ClientId)_ + +### pl.key -> str +_Constant_\ +Returns the key passed during authentication + +### pl.nick -> str +_Variable_\ +The nickname passed during authentication from the BeamMP server, can be changed, consequences are untested + +### pl.roles -> str +_Variable_\ +The role passed during authentication from the BeamMP server, can be changed (if an incorrect role is set, unexpected things may happen.) + +### pl.guest -> bool +_Constant_\ +Returns whether the player is a guest, passed during authentication from the BeamMP server + +### pl.identifiers -> dict +_Constant_\ +Identifiers passed during authentication from the BeamMP server. + +### pl.ready -> bool +_Constant, changed by the core_\ +Returns a bool value, if True -> the player has downloaded all resources, loaded on the map + +### pl.cars -> dict +_Constant, changed by the core_\ +Returns a dictionary of cars like this \ No newline at end of file diff --git a/docs/en/plugins/events_list.md b/docs/en/plugins/events_list.md new file mode 100644 index 0000000..833a64f --- /dev/null +++ b/docs/en/plugins/events_list.md @@ -0,0 +1,4 @@ +# List of available events + +Most events will receive `pl = data['kwargs']['player']`, you can find a description [here](./classes.md) + diff --git a/docs/en/plugins/async_example.py b/docs/en/plugins/examples/async_example.py similarity index 100% rename from docs/en/plugins/async_example.py rename to docs/en/plugins/examples/async_example.py diff --git a/docs/en/plugins/example.py b/docs/en/plugins/examples/example.py similarity index 100% rename from docs/en/plugins/example.py rename to docs/en/plugins/examples/example.py diff --git a/docs/en/plugins/lua/example.lua b/docs/en/plugins/lua/example.lua new file mode 100644 index 0000000..984646f --- /dev/null +++ b/docs/en/plugins/lua/example.lua @@ -0,0 +1,27 @@ +print("example.lua") + +--CreateTimer Testing +local mytimer = MP.CreateTimer() +--.--.--.--.--.--.--. + +--GetOSName Testing +print("OS Name: "..MP.GetOSName()) +--.--.--.--.--.--.- + +--GetServerVersion Testing +local major, minor, patch = MP.GetServerVersion() +print("Server Version: "..major.."."..minor.."."..patch) +--.--.--.--.--.--.--.--.-- + +--Events Testing-- +function handleChat(player_id, player_name, message) + print("Lua handleChat:", player_id, player_name, message, "; Uptime: "..mytimer:GetCurrent()) + return 1 +end + +MP.RegisterEvent("onChatMessage", "handleChat") +--.--.--.--.--.--. + +function onInit() + print("Initializing ready!") +end diff --git a/docs/en/plugins/lua/readme.md b/docs/en/plugins/lua/readme.md new file mode 100644 index 0000000..bbf2c70 --- /dev/null +++ b/docs/en/plugins/lua/readme.md @@ -0,0 +1,35 @@ +# Providing Backward Compatibility for BeamMP Lua + +KiuToi provides almost full support for lua plugins with BeamMP. All necessary methods have been created, and testing has revealed the following nuances: + +KiuToi does not support: `MP.Set()` + +#### Economic Rework V2.0 (Paid, Discord (RU): [Hlebushek](https://discordapp.com/users/449634697593749516)) + +1. To obtain `pluginPath`, use: `debug.getinfo(1).source:gsub("\\","/")` => `debug.getinfo(1).source:gsub("\\","/"):gsub("@", "")` as the path returns with `@`, which broke the plugin. + +#### Cobalt Essentials V1.7.5 (Free, [github](https://github.com/prestonelam2003/CobaltEssentials/)) + +1. To obtain `pluginPath`, use: `debug.getinfo(1).source:gsub("\\","/")` => `debug.getinfo(1).source:gsub("\\","/"):gsub("@", "")` as the path returns with `@`, which broke the plugin. +2. All `require()` statements had to be moved after `onInit`. +3. In some cases, `MP.RegisterEvent` had to be moved after the function declaration, i.e.: +```lua +--This is incorrect, registration may fail +MP.RegisterEvent("onPlayerAuth","onPlayerAuth") +function onPlayerAuth(name, role, isGuest) + -- Some plugin code +end + +--This is the correct version +MP.RegisterEvent("onPlayerAuth","onPlayerAuth") +``` + +### A Little About How it Works + +Plugin loading goes through several stages: + +1. The `plugins/` folder is scanned. +2. If the folder is not in PyPlugins and there are `*.lua` files in the folder, then it is added as a plugin folder, let's say it will be `plugins/LuaPlugin` +3. Next, `lua.loadfile({filename})` is performed from this folder (this is the standard method in lua). +4. Finally, the `onInit()` function is called, and an event is triggered. +5. If no errors occur during the execution of `onInit()`, you can see the message `Lua plugins: LuaPlugin:ok` through the `lua_plugins` command. \ No newline at end of file diff --git a/docs/en/plugins/readme.md b/docs/en/plugins/readme.md index d72234d..2a0113d 100644 --- a/docs/en/plugins/readme.md +++ b/docs/en/plugins/readme.md @@ -1,12 +1,18 @@ -# Plugin System +Это описание системы плагинов для KuiToi сервера на Python: -## Installing the Library with "Stubs" -###### (This means that it will not work without a server, but the IDE will suggest the API) -###### (The library is still under development) +## Events +### Events list: [here](./events_list.md) + +## Classes +### Classes list: [here](./classes.md) + +## Installing the library with "stubs" +###### (This means it won't work without the server, but your IDE will suggest the API) +###### (The library is still in development) * Using pip:\ `$ pip install KuiToi` -* From source code:\ +* From source:\ `git clone https://github.com/KuiToi/KuiToi-PyLib` ## Example @@ -17,7 +23,7 @@ try: except ImportError: pass -kt = KuiToi("Example") +kt = KuiToi("ExamplePlugin") log = kt.log def my_event_handler(event_data): @@ -25,14 +31,14 @@ def my_event_handler(event_data): def load(): # Plugin initialization - ev.register_event("my_event", my_event_handler) + kt.register_event("my_event", my_event_handler) log.info("Plugin loaded successfully.") def start(): - # Running plugin processes - ev.call_event("my_event") - ev.call_event("my_event", "Some data", data="some data too") + # Starting plugin processes + kt.call_event("my_event") + kt.call_event("my_event", "Some data", data="some data too") log.info("Plugin started successfully.") @@ -41,15 +47,17 @@ def unload(): log.info("Plugin unloaded successfully.") ``` -* It is recommended to use `open()` after `load()`. Otherwise, use `kt.load()` - creates a file in the `plugin//` folder. -* Creating your own event: `kt.register_event("my_event", my_event_function)` +A more comprehensive example can also be found in [example.py](examples/example.py) + +* It is recommended to use `open()` after `load()`, otherwise use `kt.load()` - It creates a file in the `plugin//` folder. +* Creating your own event: `kt.register_event("my_event", my_event_function)` - * Calling an event: `kt.call_event("my_event")` * Calling an event with data: `kt.call_event("my_event", data, data2=data2)` -* Basic events: _Will write later_ +* Base events: _To be added later_ -## Async Functions +## Async functions -Async support is available. +Async support is available ```python try: @@ -64,17 +72,17 @@ log = kt.log async def my_event_handler(event_data): log.info(f"{event_data}") - + async def load(): # Plugin initialization - ev.register_event("my_event", my_event_handler) + kt.register_event("my_event", my_event_handler) log.info("Plugin loaded successfully.") async def start(): - # Running plugin processes - await ev.call_async_event("my_event") - await ev.call_async_event("my_event", "Some data", data="some data too") + # Starting plugin processes + await kt.call_async_event("my_event") + await kt.call_async_event("my_event", "Some data", data="some data too") log.info("Plugin started successfully.") @@ -84,9 +92,9 @@ async def unload(): ``` -A more extensive example can also be found in [async_example.py](./async_example.py). +A more comprehensive example can also be found in [async_example.py](examples/async_example.py) -* Creating your own event: `kt.register_event("my_event", my_event_function)` (register_event checks for function) +* Creating your own event: `kt.register_event("my_event", my_event_function)` (register_event has a function check) * Calling an async event: `kt.call_async_event("my_event")` * Calling an async event with data: `kt.call_async_event("my_event", data, data2=data2)` -* Basic async events: _Will write later_ \ No newline at end of file +* Base async events: _To be added later_ \ No newline at end of file diff --git a/docs/en/readme.md b/docs/en/readme.md index fdd4d64..df94170 100644 --- a/docs/en/readme.md +++ b/docs/en/readme.md @@ -1,9 +1,10 @@ # Documentation for KuiToi Server -### The documentation is not perfect yet, but it will be one day - -1. Setup and Start server - [here](setup) -2. Plugins and Events system - [here](plugins) -3. MultiLanguage - [here](./multilanguage) -4. KuiToi WebAPI - [here](./web) -5. Something new... +### The documentation is not yet perfect, but someday it will be. + +1. Setup and Launching the Server - [here](./setup) +2. Plugins and Event System - [here](./plugins) +3. Nuances of Working with Lua - [here](./plugins/lua) +4. Multilanguage Support - [here](./multilanguage) +5. KuiToi WebAPI - [here](./web) +6. Something new will be added here soon... \ No newline at end of file diff --git a/docs/readme.md b/docs/readme.md index a9f4cb3..93a6300 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,4 +1,4 @@ # Choose your language -### [English](./en) ### [Русский](./ru) +### [English](./en) (AI translation)