{"id":34734273,"url":"https://github.com/skybaks/pyplanet-cup_manager","last_synced_at":"2025-12-25T03:26:09.645Z","repository":{"id":39902564,"uuid":"453081247","full_name":"skybaks/pyplanet-cup_manager","owner":"skybaks","description":"Competition Management Plugin for Trackmania Pyplanet","archived":false,"fork":false,"pushed_at":"2024-08-09T22:03:51.000Z","size":362,"stargazers_count":10,"open_issues_count":10,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-16T21:28:05.984Z","etag":null,"topics":["maniaplanet","pyplanet","trackmania"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skybaks.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-28T13:39:47.000Z","updated_at":"2025-04-24T07:49:40.000Z","dependencies_parsed_at":"2023-10-11T00:51:34.187Z","dependency_job_id":"32242fe8-9ab0-4dd8-b320-9dce65ea929e","html_url":"https://github.com/skybaks/pyplanet-cup_manager","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/skybaks/pyplanet-cup_manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skybaks%2Fpyplanet-cup_manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skybaks%2Fpyplanet-cup_manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skybaks%2Fpyplanet-cup_manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skybaks%2Fpyplanet-cup_manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skybaks","download_url":"https://codeload.github.com/skybaks/pyplanet-cup_manager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skybaks%2Fpyplanet-cup_manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28018096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["maniaplanet","pyplanet","trackmania"],"created_at":"2025-12-25T03:26:06.912Z","updated_at":"2025-12-25T03:26:09.636Z","avatar_url":"https://github.com/skybaks.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cup Manager\r\n\r\nA plugin for [PyPlanet](https://pypla.net/).\r\n\r\nThis plugin will handle hosting a cup competition in Trackmania, Maniaplanet, and Shootmania. It provides a competition\r\nhost with the following:\r\n\r\n* Manage mode scripts and settings to ensure consistent competitions\r\n* Record player score results and sum totals across multiple maps\r\n* Provide player placement status information and podium results\r\n* Use result totals to pay planets to players in batch\r\n* Export results in multiple formats including Csv and Discord\r\n\r\nThe following games and modes have been tested and shown to have some level of functionality. In general, this plugin\r\nwill work with any script mode which supports the scores callback.\r\n\r\n* Trackmania - Timeattack, Rounds, Laps, MedalAttack, Speedtrap\r\n* Maniaplanet - Timeattack, Rounds, Laps\r\n* Shootmania - Melee, Elite, Royal, Siege, Infection, Combo\r\n\r\n\r\n# Cup Manager Setup and Usage\r\n\r\n**Contents**\r\n* [Setting up with a dedicated server](./readme.md#setting-up-with-a-dedicated-server)\r\n    * [Set up Pyplanet](./readme.md#set-up-pyplanet)\r\n    * [Install the plugin](./readme.md#install-the-plugin)\r\n* [Customizing the cup configuration](./readme.md#customizing-the-cup-configuration)\r\n    * [Create, Load, or Edit a Cup Configuration](./readme.md#create-load-or-edit-a-cup-configuration)\r\n        * [Edit the Current Config](./readme.md#edit-the-current-config)\r\n        * [Load a Config File](./readme.md#load-a-config-file)\r\n        * [Download a Config File](./readme.md#download-a-config-file)\r\n        * [Create a New Config](./readme.md#create-a-new-config)\r\n    * [Create a Cup Configuration File Manually](./readme.md#create-a-cup-configuration-file-manually)\r\n        * [Cup Config File: Names](./readme.md#cup-config-file-names)\r\n        * [Cup Config File: Presets](./readme.md#cup-config-file-presets)\r\n        * [Cup Config File: Payouts](./readme.md#cup-config-file-payouts)\r\n    * [Cup Configuration Location](./readme.md#cup-configuration-location)\r\n* [Running a cup as server admin](./readme.md#running-a-cup-as-server-admin)\r\n    * [Admin quick reference](./readme.md#admin-quick-reference)\r\n    * [Set up before the cup map starts](./readme.md#set-up-before-the-cup-map-starts)\r\n        * [Start the cup logic](./readme.md#start-the-cup-logic)\r\n            * [Update the cup edition](./readme.md#update-the-cup-edition)\r\n            * [Update the cup map count](./readme.md#update-the-cup-map-count)\r\n        * [Choose the mode script and settings preset](./readme.md#choose-the-mode-script-and-settings-preset)\r\n        * [Choose a specific score sorting mode](./readme.md#choose-a-specific-score-sorting-mode)\r\n    * [During the cup](./readme.md#during-the-cup)\r\n        * [Add or remove maps from the active cup](./readme.md#add-or-remove-maps-from-the-active-cup)\r\n        * [Notify the cup logic of cup end](./readme.md#notify-the-cup-logic-of-cup-end)\r\n        * [Reset the mode script and settings](./readme.md#reset-the-mode-script-and-settings)\r\n    * [After the cup](./readme.md#after-the-cup)\r\n        * [Export the cup results](./readme.md#export-the-cup-results)\r\n        * [Pay planets to the winners](./readme.md#pay-planets-to-the-winners)\r\n* [Plugin operations as a player](./readme.md#plugin-operations-as-a-player)\r\n    * [Player quick reference](./readme.md#player-quick-reference)\r\n\r\n# Setting up with a dedicated server\r\n\r\n## Set up Pyplanet\r\n\r\nThis plugin runs from within the Pyplanet server controller. You will need to have pyplanet configured and working\r\nbefore starting to set up this plugin.\r\n\r\nPyplanet has a very robust set of documentation and extremely helpful directions on how to get it set up. Go to:\r\nhttps://pypla.net/\r\n\r\n## Install the plugin\r\n\r\nRun the command to install the latest version of the plugin.\r\n\r\n```\r\npython -m pip install --upgrade pyplanet-cup-manager\r\n```\r\n\r\nThen you will need to add the plugin to your \"settings\\apps.py\". Add the following to the list of apps to load:\r\n\r\n```\r\n\"skybaks.cup_manager\",\r\n```\r\n\r\n# Customizing the cup configuration\r\n\r\nThe plugin contains the means to customize to fit your competition's needs through the `//cup config` command. This\r\nallows customization of the `//cup on \u003cname\u003e` command and enables further automation in cup execution.\r\n\r\nThe recommended way to customize to meet your cup's needs is through the in-server UI. However, the configuration can\r\nalso be created through a Json formatted text file and loaded from your dedicated server location or downloaded from a\r\nUrl.\r\n\r\n## Create, Load, or Edit a Cup Configuration\r\n\r\nCommands quick reference:\r\n\r\n```\r\n//cup config\r\n//cup config load \u003cfilename\u003e\r\n//cup config download \u003curl\u003e\r\n//cup config new \u003cfilename\u003e\r\n```\r\n\r\n### Edit the Current Config\r\n\r\nTo edit the currently loaded config file, use the following command:\r\n\r\n```\r\n//cup config\r\n```\r\n\r\nThis will launch the config editing UI where you can make changes and the press \"Save\" to commit those changes.\r\n\r\nOn the editing window there are 3 tabs at the top, a sidebar on the left, and configuration options in the main body.\r\nEach tab controls the following:\r\n\r\n* Names: Configure cup name, map count, settings presets, and more\r\n* Presets: Set up mode script + script settings presets which can be executed by name or linked to a cup via the Names\r\n    tab\r\n* Payouts: Create planets payout schemes which can be accessed from the cup results scoreboard or linked to a cup via\r\n    the Names tab\r\n\r\nFor each tab, a new instance of cup, preset, or payout can be created or deleted using the +/- buttons on the top of\r\nthe left sidebar.\r\n\r\n### Load a Config File\r\n\r\nTo load a different config file, use the following command:\r\n\r\n```\r\n//cup config load \u003cfilename\u003e\r\n```\r\n\r\nThis will unload the current config file and load the specified one, if it exists.\r\n\r\n### Download a Config File\r\n\r\nTo download a config file, use the following command:\r\n\r\n```\r\n//cup config download \u003curl\u003e\r\n```\r\n\r\nThis will download the all the text at the given Url and create a new config file. For example, if downloading a file\r\nfrom Github, make sure to use the raw link so that it only downloads the Json file contents. When it comes to the name\r\nof the new config file, the last part of the given Url will be used. For example, if the Url was\r\n`https://raw.githubusercontent.com/skybaks/pyplanet-cup_manager/master/settings/cup_manager_config.json` then the\r\nfilename would be set to \"cup_manager_config.json\".\r\n\r\n### Create a New Config\r\n\r\n\u003e When starting the plugin for the first time it is not necessary to use this command. The plugin already creates a new\r\n\u003e config file for you by default.\r\n\r\nTo create a new config file, use the following command:\r\n\r\n```\r\n//cup config new \u003cfilename\u003e\r\n```\r\n\r\nThis will create a new config file with some default settings, and then open the editing UI.\r\n\r\n## Create a Cup Configuration File Manually\r\n\r\nThe cup configuration file is a Json formatted text file with a specific structure. See\r\n[cup_manager_config](./settings/cup_manager_config.json) for an example.\r\n\r\nThe base level of the config file contains three elements like so:\r\n\r\n```jsonc\r\n{\r\n    \"names\": {},\r\n    \"presets\": {},\r\n    \"payouts\": {}\r\n}\r\n```\r\n\r\n### Cup Config File: Names\r\n\r\nThe \"names\" config contains the names of the cups which you are going to run from the plugin as well as any additional\r\ninformation tying these cups to any presets or payouts which are also defined in the config file.\r\n\r\n```jsonc\r\n{\r\n    \"my_cup\": {\r\n        \"name\": \"My Cup\"\r\n    },\r\n    \"my_other_cup\": {\r\n        \"name\": \"My Other Cup\"\r\n    }\r\n}\r\n```\r\n\r\nThe most simple instantiation of a named cup is defined with only a \"name\" attribute that will be the display name of\r\nthe cup. In the example above, the key names \"my_cup\" and \"my_other_cup\" are the ID names that would be used with the\r\n`//cup on \u003cID\u003e` command to start the cup from in game.\r\n\r\n```jsonc\r\n{\r\n    \"my_cup\": {\r\n        \"name\": \"My Cup\",\r\n\r\n        /* [Optional]\r\n            Use preset_on and preset_off fields to link starting and stopping the cup to automatically trigger a\r\n            settings preset. You can define one or the other or both.\r\n            - preset_on is equivalent to running \"//cup setup \u003cpreset\u003e\" immediately after starting the cup\r\n            - preset_off is equivalent to running \"//cup setup \u003cpreset\u003e\" immediately after the cup ends\r\n        */\r\n        \"preset_on\": \"my_rounds_preset\",\r\n        \"preset_off\": \"my_timeattack_preset\",\r\n\r\n        /* [Optional]\r\n            Use map_count to predefine the number of maps the cup will be played on. This is equivalent to running\r\n            \"//cup mapcount \u003cmap_count\u003e\" right after you start the cup.\r\n        */\r\n        \"map_count\": 7,\r\n\r\n        /* [Optional]\r\n            Use payout to predefine the payout config this cup will be using. The value entered in this field should\r\n            match the ID name of a payout defined in this config file.\r\n            Predefining the payout here will make it easier to access from the results and will make it appear in the\r\n            exported results.\r\n        */\r\n        \"payout\": \"my_payout\",\r\n\r\n        /* [Optional]\r\n            Use scoremode to force the type of score behavior for the cup. This is equivalent to running\r\n            \"//cup scoremode \u003cscore_mode\u003e\" after starting a cup. If included the field should be set to one of the\r\n            scoremode IDs found when running \"//cup scoremode\"\r\n        */\r\n        \"scoremode\": \"score_mode_mixed\"\r\n    }\r\n}\r\n```\r\n\r\nShown above are the additional optional fields which can be added to further customize a defined cup. Each is\r\ndocumented in the attached comment.\r\n\r\n### Cup Config File: Presets\r\n\r\nThe presets section of the config file allows you to define a preset mode script and settings. Each preset that you\r\ndefine can be invoked using the `//cup setup \u003cpreset\u003e` command.\r\n\r\n```jsonc\r\n{\r\n    \"my_preset\": {\r\n\r\n        /*\r\n            The aliases section of the preset defines shorthand names that can be used with the \"//cup setup\" command\r\n            instead of the full preset identifier.\r\n            In the case of this current example preset, each of the following commands could be used to activate:\r\n            - //cup setup my_preset\r\n            - //cup setup mp\r\n            - //cup setup 1\r\n        */\r\n        \"aliases\": [ \"mp\", \"1\" ],\r\n\r\n        /*\r\n            The script field contains the name of the mode script to be used with this preset along with what game it\r\n            is associated with. Since script filenames can differ between games, this is designed to allow for preset\r\n            reuse. You are only required to define at least one script.\r\n            The available game names are:\r\n            - tm        -\u003e Used for Maniaplanet\r\n            - tmnext    -\u003e Used for Trackmania (2020)\r\n            - sm        -\u003e Used for Shootmania\r\n        */\r\n        \"script\": {\r\n            \"tm\": \"Rounds.Script.txt\",\r\n            \"tmnext\": \"Trackmania/TM_Rounds_Online.Script.txt\"\r\n        },\r\n\r\n        /*\r\n            This field is used to define settings that will be applied to the mode script when the preset is activated.\r\n            Define any number of script settings along with the value you want to be applied.\r\n        */\r\n        \"settings\": {\r\n            \"S_FinishTimeout\": 10,\r\n            \"S_PointsLimit\": 240,\r\n            \"S_PointsRepartition\": \"15,12,10,8,6,4,3,3,3,2,2,2,1\"\r\n        }\r\n    },\r\n\r\n    \"my_other_preset\": {\r\n        \"aliases\": [],\r\n        \"script\": {\r\n            \"tmnext\": \"Trackmania/TM_TimeAttack_Online.Script.txt\"\r\n        },\r\n        \"settings\": {\r\n            \"S_TimeLimit\": 360,\r\n        }\r\n    }\r\n}\r\n```\r\n\r\nShown above is an example of two presets with comments used to document each of the sub-fields. Any number of presets\r\ncan be defined in the config file.\r\n\r\nThe identifiers \"my_preset\" and \"my_other_preset\" are simply examples and your presets can use whatever identifier\r\nnames that are meaningful to you. These identifiers are also what would be used for the \"preset_on\" or \"preset_off\"\r\nfields in the names config.\r\n\r\n### Cup Config File: Payouts\r\n\r\nThe payouts section of the config file is used to define a award scheme for planets. In games which support planets,\r\nthe defined payouts can be accessed from the cup results to pay the winning players in batch.\r\n\r\n```jsonc\r\n{\r\n    /*\r\n        In this case, \"my_payout\" can be whatever name you would like to use to identify the payout by. The numbers in\r\n        this array define the payment scheme in order where the first element would be given the highest ranked player.\r\n    */\r\n    \"my_payout\": [ 500, 250, 100 ],\r\n\r\n    \"my_other_payout\": [6000, 1000, 500, 200, 100, 50]\r\n}\r\n```\r\n\r\nShown above is an example of payouts annotated with comments. The names of the payouts shown here \"my_payout\" and\r\n\"my_other_payout\" are custom and you can define your payouts with any names that are meaningful to you. These names are\r\nthe identifiers for the payouts and would also be used along with the \"payout\" field in the names config.\r\n\r\n## Cup Configuration Location\r\n\r\nThe default location for saving and loading cup configuration json files is `UserData/Maps/MatchSettings` under the\r\ndedicated server.\r\nThis value can be changed by adding `CUP_MANAGER_CONFIG_PATH` to your pyplanet settings file. However, it is\r\nrecommended in most instances to stick with the defaults.\r\n\r\n\r\n# Running a cup as server admin\r\n\r\n## Admin quick reference\r\n\r\nQuick reference of all commands that *might* be relevant to a cup admin. Read below for more specific usage information.\r\n\r\n```\r\n-- Before Cup --\r\n//cup on \u003ccup_name\u003e\r\n//cup edition \u003cedition_number\u003e\r\n//cup mapcount \u003cmap_count\u003e\r\n//cup setup \u003ccup_settings_preset\u003e\r\n//cup scoremode \u003ccup_scoremode_id\u003e\r\n\r\n-- During Cup --\r\n//cup edit\r\n\r\n-- Last Cup Map --\r\n//cup off\r\n//cup setup \u003cta_settings_preset\u003e\r\n\r\n-- After Cup --\r\n/cup results\r\n/cup matches\r\n```\r\n\r\n## Set up before the cup map starts\r\n\r\nThe expected use cases for this plugin are competitions in Rounds or Laps modes. The server is most likely starting in\r\nTimeAttack mode before the cup. This is good because Pyplanet and the dedicated server provide the most consistent\r\nresults from the \"setup\" command when you switch from one mode script to another.\r\n\r\n### Start the cup logic\r\n\r\nActivating the cup logic tells the plugin that it should pay special attention to next map(s) and adds some special\r\nprintouts to keep players updated on maps and scores.\r\n\r\nIf you have defined named cups in the \"local.py\" under CUP_MANAGER_NAMES, you can use them now by entering the key\r\nname as an argument to the command:\r\n\r\n```\r\n//cup on \u003ccup_key_name\u003e\r\n```\r\n\r\nIf you dont have any named cups defined you can run an anonymous cup by simply entering the command:\r\n\r\n```\r\n//cup on\r\n```\r\n\r\n#### Update the cup edition\r\n\r\nThe plugin will automatically look up the edition of the last time you ran a cup with this key name and set the current\r\nedition to 1 + last edition. Sometimes that isnt correct so you can change that with the following command.\r\n\r\n```\r\n//cup edition \u003cedition_number\u003e\r\n```\r\n\r\n#### Update the cup map count\r\n\r\nIf you know how many maps will be in your cup you can set the cup map count. This enables the plugin to print out\r\ninformational messages at the start of each cup map that say \"map X of Y\". Additionally, when the final map is reached\r\nthe plugin will automatically end the cup for you by running the internal eqivalent of the `//cup off` command.\r\n\r\n```\r\n//cup mapcount \u003cmap_count\u003e\r\n```\r\n\r\nIf you dont want to deal with the auto-end logic then you can set the map count to 0 and the cup will run until you\r\nstop it.\r\n\r\n### Choose the mode script and settings preset\r\n\r\n\u003e This step is not necessary if you are using the `//cup on` command with a defined \"preset_on\" field in the local.py\r\n\r\nIf you are not using the `//cup on` command, or there is no preset linked automatically to your cup, or you want to use a\r\ndifferent preset than the cup default, you can change that using this setup command.\r\n\r\n```\r\n//cup setup \u003cpreset_name\u003e\r\n```\r\n\r\nIf you dont remember the name of the preset, run this command instead and you will be able to pick from all the\r\ndefined presets:\r\n\r\n```\r\n//cup setup\r\n```\r\n\r\n### Choose a specific score sorting mode\r\n\r\n\u003e This step is completely optional and only should be used when your cup needs score sorting logic not covered in the\r\n\u003e default behaviors.\r\n\r\nThe plugin has automatic detection built in for most common mode scripts in Trackmania and Maniaplanet as well as some\r\ngeneric fallback sorting modes which should cover a large variety of cases. However, you may still be interested in\r\nusing a specific sorting mode for your cup. In that case use the command following command to set it:\r\n\r\n```\r\n//cup scoremode \u003cscoremode_id\u003e\r\n```\r\n\r\nIf you dont know the name of the mode, run the following command instead and it will open a window you can use the pick\r\nthe sorting mode you want.\r\n\r\n```\r\n//cup scoremode\r\n```\r\n\r\n## During the cup\r\n\r\n### Add or remove maps from the active cup\r\n\r\nIf for any reason there was some problem and you need to include or exclude a scored map from the cup results you can\r\nusing this command:\r\n\r\n```\r\n//cup edit\r\n```\r\n\r\nThis will open a window showing the scored maps that are currently included in the cup. From the far left column you\r\ncan click to add or remove maps.\r\n\r\n### Notify the cup logic of cup end\r\n\r\n\u003e This step is not necessary if you told the plugin your map count\r\n\r\nIf you are not using a defined map count you will manually need to tell the plugin when the cup has reached the final\r\nmap.\r\n\r\n```\r\n//cup off\r\n```\r\n\r\n### Reset the mode script and settings\r\n\r\n\u003e This step is not necessary if you are using `//cup on` with a defined \"preset_off\" field\r\n\r\nAfter the cup is over you want to immediately switch back to the mode the server was playing before the cup started.\r\nThis is most likely TimeAttack. On the final cup map run the command:\r\n\r\n```\r\n//cup setup \u003cpreset\u003e\r\n```\r\n\r\nWith the TimeAttack preset so that the map immediately following the cup will return to TimeAttack mode.\r\n\r\n## After the cup\r\n\r\n### Export the cup results\r\n\r\nAfter the cup is over you can use the export window to get the cup results in a variety of formats. If you ran the cup\r\nusing the `//cup on` command then you can get to the results window using the command:\r\n\r\n```\r\n/cup results\r\n```\r\n\r\nFrom the results window click the \"Export\" button, then modify the settings as you desire copy the text to your\r\nclipboard.\r\n\r\nIf you did not use the `//cup on` command to run the cup you can still access cup results. Use the command:\r\n\r\n```\r\n/cup matches\r\n```\r\n\r\nTo open a view of all previous matches. Use the leftmost checkboxes to select all cup maps then click the \"Sum Sel.\"\r\nbutton to view the summed results for all the selected maps. From there you can click the \"Export\" button and follow\r\nthe same steps as above to export the results via your clipboard.\r\n\r\n### Pay planets to the winners\r\n\r\nIf you are in a game that supports paying players planets and you have defined some payout schemes in your local.py\r\nfile, you can pay players based on the cup results. Follow the instructions above to get to the cup results either\r\nusing `/cup results` or `/cup matches`, then click the button \"Payout\" to open the payout window.\r\n\r\n# Plugin operations as a player\r\n\r\n## Player quick reference\r\n\r\n```\r\n/cup results\r\n/cup cups\r\n/cup matches\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskybaks%2Fpyplanet-cup_manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskybaks%2Fpyplanet-cup_manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskybaks%2Fpyplanet-cup_manager/lists"}