diff --git a/.github/workflows/docs_pages.yml b/.github/workflows/docs_pages.yml new file mode 100644 index 0000000..0abe2ea --- /dev/null +++ b/.github/workflows/docs_pages.yml @@ -0,0 +1,21 @@ +name: docs + +on: + push: + branches: + - main + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: | + pip install mkdocs + pip install "mkdocstrings[python]" + pip install mkdocs-material + pip install mkdocs-callouts + mkdocs gh-deploy --force \ No newline at end of file diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index 8bca609..0000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,7 +0,0 @@ -include: - - project: GothicMultiplayerTeam/templates - file: [squirrel-module.yml] - -variables: - PROJECT_NAME: ${CI_PROJECT_NAME} - VERSION: "0.1" \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index cac8cea..a80a16f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -66,6 +66,8 @@ file(GLOB_RECURSE SOURCE "src/*.h" "src/*.cpp" + "src/events/*.h" + "src/events/*.cpp" ) # Linking directories diff --git a/docs/defaultEvents/onBan.md b/docs/defaultEvents/onBan.md new file mode 100644 index 0000000..4593f39 --- /dev/null +++ b/docs/defaultEvents/onBan.md @@ -0,0 +1,27 @@ +# `event` onBan +!!! note + If serial/mac/ip/name indexes doesn't exist, then the parameters has not been specified when ban was added. + If timestamp doesn't exist, then ban was permanent. + +This event is triggered when new ban is being added. + +## Parameters +* `dict` **kwargs**: + * `str` **mac**: MAC address of the banned player. + * `str` **ip**: IP address of the banned player. + * `str` **serial**: serial of the banned player. + * `str` **name**: nickname of the banned player. + * `int` **timestamp**: timestamp when the ban expires. + +## Usage +```python +import g2o +from datetime import datetime + +@g2o.event('onBan') +def onBan(**kwargs): + print(f'Player {kwargs['name']} has been banned.') + if ('timestamp' in kwargs): + banExpires = datetime.fromtimestamp(kwargs['timestamp']) + print(f'Ban expires at {banExpires}') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onExit.md b/docs/defaultEvents/onExit.md new file mode 100644 index 0000000..a52b53f --- /dev/null +++ b/docs/defaultEvents/onExit.md @@ -0,0 +1,15 @@ +# `event` onExit +This event is triggered when server is going to shut down. +You can use it, to save some data before closing up, or do something else. + +## Parameters +No parameters. + +## Usage +```python +import g2o + +@g2o.event('onExit') +def onExitEvt(**kwargs): + print('Bye') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onInit.md b/docs/defaultEvents/onInit.md new file mode 100644 index 0000000..775edd1 --- /dev/null +++ b/docs/defaultEvents/onInit.md @@ -0,0 +1,14 @@ +# `event` onInit +This event is triggered when server successfully starts up. + +## Parameters +No parameters. + +## Usage +```python +import g2o + +@g2o.event('onInit') +def onInitEventHandler(**kwargs): + print('Called onInit event') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onTick.md b/docs/defaultEvents/onTick.md new file mode 100644 index 0000000..9f843ac --- /dev/null +++ b/docs/defaultEvents/onTick.md @@ -0,0 +1,14 @@ +# `event` onTick +This event is triggered in every server main loop iteration. + +## Parameters +No parameters. + +## Usage +```python +import g2o + +@g2o.event('onTick') +def onTickEvt(**kwargs): + print('Tock') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onTime.md b/docs/defaultEvents/onTime.md new file mode 100644 index 0000000..fe63a81 --- /dev/null +++ b/docs/defaultEvents/onTime.md @@ -0,0 +1,20 @@ +# `event` onTime +This event is triggered each time when game time minute passes. + +## Parameters +* `dict` **kwargs**: + * `int` **day**: the current ingame day. + * `int` **hour**: the current ingame hour. + * `int` **min**: the current ingame minutes. + +## Usage +```python +import g2o + +@g2o.event('onTick') +def onTickEvt(**kwargs): + day = kwargs['day'] + hour = kwargs['hour'] + mins = kwargs['min'] + print(f'Current time: Day {day}, Hour {hour}, Min {mins}') +``` \ No newline at end of file diff --git a/docs/defaultEvents/onUnban.md b/docs/defaultEvents/onUnban.md new file mode 100644 index 0000000..2b6192f --- /dev/null +++ b/docs/defaultEvents/onUnban.md @@ -0,0 +1,23 @@ +# `event` onUnban +!!! note + If serial/mac/ip/name indexes doesn't exist, then the parameters has not been specified when ban was added. + If timestamp doesn't exist, then ban was permanent. + +This event is triggered when ban with specified info is being removed. + +## Parameters +* `dict` **kwargs**: + * `str` **mac**: MAC address of the banned player. + * `str` **ip**: IP address of the banned player. + * `str` **serial**: serial of the banned player. + * `str` **name**: nickname of the banned player. + * `int` **timestamp**: timestamp when the ban expires. + +## Usage +```python +import g2o + +@g2o.event('onUnban') +def onUnban(**kwargs): + print(f'Player {kwargs['name']} has been unbanned.') +``` \ No newline at end of file diff --git a/docs/docs/assets/logo.png b/docs/docs/assets/logo.png deleted file mode 100644 index b1a7447..0000000 Binary files a/docs/docs/assets/logo.png and /dev/null differ diff --git a/docs/docs/index.md b/docs/docs/index.md deleted file mode 100644 index 1ab2f5c..0000000 --- a/docs/docs/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Home - -An example README that you can replace with your own content! \ No newline at end of file diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css deleted file mode 100644 index 492b119..0000000 --- a/docs/docs/stylesheets/extra.css +++ /dev/null @@ -1,7 +0,0 @@ -:root { - --md-primary-fg-color: #8191ff; -} - -.md-header { - background-color: #232323; -} \ No newline at end of file diff --git a/docs/events/addEvent.md b/docs/events/addEvent.md new file mode 100644 index 0000000..a93b05c --- /dev/null +++ b/docs/events/addEvent.md @@ -0,0 +1,2 @@ +# `function` addEvent +::: g2o.events.addEvent \ No newline at end of file diff --git a/docs/events/callEvent.md b/docs/events/callEvent.md new file mode 100644 index 0000000..207cd08 --- /dev/null +++ b/docs/events/callEvent.md @@ -0,0 +1,2 @@ +# `function` callEvent +::: g2o.events.callEvent \ No newline at end of file diff --git a/docs/events/event.md b/docs/events/event.md new file mode 100644 index 0000000..915b3ad --- /dev/null +++ b/docs/events/event.md @@ -0,0 +1,2 @@ +# `function` event +::: g2o.events.event \ No newline at end of file diff --git a/docs/events/removeEventHandler.md b/docs/events/removeEventHandler.md new file mode 100644 index 0000000..c993332 --- /dev/null +++ b/docs/events/removeEventHandler.md @@ -0,0 +1,2 @@ +# `function` removeEventHandler +::: g2o.events.removeEventHandler \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..ad08ae1 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +# Blank \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml deleted file mode 100644 index 298a997..0000000 --- a/docs/mkdocs.yml +++ /dev/null @@ -1,37 +0,0 @@ -site_name: Squirrel Template Module - Docs -repo_url: https://gitlab.com/GothicMultiplayerTeam/modules/squirrel-template -repo_name: Squirrel Template Module -edit_uri: "" -site_dir: "public" - -extra_css: - - stylesheets/extra.css - -extra: - version: - provider: mike - -markdown_extensions: - - admonition - - attr_list - - pymdownx.tabbed - - pymdownx.highlight - - pymdownx.superfences - -theme: - name: material - logo: assets/logo.png - icon: - repo: fontawesome/brands/gitlab - palette: - - media: "(prefers-color-scheme: light)" - scheme: default - toggle: - icon: material/eye-outline - name: Switch to dark mode - - - media: "(prefers-color-scheme: dark)" - scheme: slate - toggle: - icon: material/eye - name: Switch to light mode diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 01b75d6..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -mkdocs==1.5.3 -mkdocs-material==9.5.12 -mike==2.0.0 \ No newline at end of file diff --git a/g2o/events.py b/g2o/events.py index b5a48f6..d8dea51 100644 --- a/g2o/events.py +++ b/g2o/events.py @@ -1,16 +1,84 @@ eventList = {} -def callEvent(name : str, **args : dict): - if name in eventList: - for event in eventList[name]: - event['function'](**args) +def callEvent(evtName : str, **kwargs : dict): + """ + This function will notify (call) every handler bound to specified event. + Original: [callEvent](https://gothicmultiplayerteam.gitlab.io/docs/0.3.0/script-reference/shared-functions/event/callEvent/) + + ## Declaration + ```python + def callEvent(evtName : str, **kwargs : dict) + ``` + + ## Parameters + * `str` **name**: the name of the event + * `**dict` **kwargs**: the variable number of arguments. + + ## Usage + ```python + import g2o + + g2o.addEvent('testEvt') + + @g2o.event('testEvt') + def onTestEvent(**kwargs): + print(f'{kwargs['name']} called my beautiful test event') + + g2o.callEvent('testEvt', name = 'Diego') + ``` + """ + if evtName in eventList: + for event in eventList[evtName]: + event['function'](**kwargs) def addEvent(name): + """ + This function will register a new event with specified name. + Events can be used to notify function(s) when something will happen, like player joins the server, etc. + Original: [addEvent](https://gothicmultiplayerteam.gitlab.io/docs/0.3.0/script-reference/shared-functions/event/addEvent/) + + ## Declaration + ```python + def addEvent(name) + ``` + + ## Parameters + * `str` **name**: the name of the event + + ## Usage + ```python + import g2o + + g2o.addEvent('testEvt') + ``` + """ if not name in eventList: eventList[name] = [] def event(name : str, priority : int = 9999): + """ + This function will bind function to specified event. + Original: [addEventHandler](https://gothicmultiplayerteam.gitlab.io/docs/0.3.0/script-reference/shared-functions/event/addEventHandler/) + + ## Declaration + ```python + def event(name : str, priority : int = 9999) + ``` + + ## Parameters + * `str` **name**: the name of the event + * `int` **priority**: the function priority. The lower the value, the sooner the function/handler will be called. + + ## Usage + ```python + import g2o + + @g2o.event('onInit') + def onInitEventHandler(**kwargs): + print('Called onInit event') + ``` + """ def inlineEvt(func): if not name in eventList: pass @@ -20,7 +88,30 @@ def event(name : str, priority : int = 9999): return func return inlineEvt -def removeEventHandler(name : str, func : int): +def removeEventHandler(name : str, func : function): + """ + This function will unbind function from specified event. + Original: [removeEventHandler](https://gothicmultiplayerteam.gitlab.io/docs/0.3.0/script-reference/shared-functions/event/removeEventHandler/) + + ## Declaration + ```python + def removeEventHandler(name : str, func : function) + ``` + + ## Parameters + * `str` **name**: the name of the event + * `function` **func**: the reference to a function which is currently bound to specified event. + + ## Usage + ```python + import g2o + + @g2o.event('onTime') + def onTimeEvt(**kwargs): + print('Calling only once') + g2o.removeEventHandler('onTime', onTimeEvt) + ``` + """ if not name in eventList: pass @@ -28,7 +119,7 @@ def removeEventHandler(name : str, func : int): if item['function'] == func: del eventList[name][index] -## registering all events +## registering default events addEvent('onInit') addEvent('onExit') diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..103fec0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,57 @@ +site_name: PyG2O + +markdown_extensions: + - nl2br + - admonition + - pymdownx.details + - pymdownx.superfences + - sane_lists + +plugins: + - mkdocstrings + - search + - callouts + +repo_url: https://github.com/AURUMVORXX/PyG2O.git + +nav: + - Home: index.md + - Events: + - General: + - onInit: defaultEvents/onInit.md + - onExit: defaultEvents/onExit.md + - onTick: defaultEvents/onTick.md + - onTime: defaultEvents/onTime.md + - onBan: defaultEvents/onBan.md + - onUnban: defaultEvents/onUnban.md + - Functions: + - Events: + - event: events/event.md + - removeEventHandler: events/removeEventHandler.md + - addEvent: events/addEvent.md + - callEvent: events/callEvent.md + +theme: + name: material + features: + - search.suggest + - search.highlight + - content.tabs.link + - content.code.annotation + - content.code.copy + icon: + repo: fontawesome/brands/gitlab + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/eye-outline + name: Switch to dark mode + + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/eye + name: Switch to light mode + + primary: black \ No newline at end of file