{"id":23076726,"url":"https://github.com/antzgames/godot-universal-settings-plugin","last_synced_at":"2025-04-03T12:24:32.672Z","repository":{"id":265981610,"uuid":"895093665","full_name":"antzGames/Godot-Universal-Settings-Plugin","owner":"antzGames","description":"A versatile, renderer-aware settings screen for Godot 4.3 that seamlessly adapts across all renderers and HTML web builds.  This plugin simplifies user settings management by saving and reloading configurations for graphics, audio settings, and keybinds, ensuring a consistent experience across platforms.","archived":false,"fork":false,"pushed_at":"2024-12-06T02:45:33.000Z","size":36242,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-09T01:44:52.224Z","etag":null,"topics":["addon","godot","godot-engine","godot4","plugin","settings"],"latest_commit_sha":null,"homepage":"","language":"GDScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antzGames.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":"2024-11-27T14:48:14.000Z","updated_at":"2025-01-09T14:37:16.000Z","dependencies_parsed_at":"2024-12-01T23:29:02.910Z","dependency_job_id":null,"html_url":"https://github.com/antzGames/Godot-Universal-Settings-Plugin","commit_stats":null,"previous_names":["antzgames/godot-universal-settings-plugin"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antzGames%2FGodot-Universal-Settings-Plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antzGames%2FGodot-Universal-Settings-Plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antzGames%2FGodot-Universal-Settings-Plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antzGames%2FGodot-Universal-Settings-Plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antzGames","download_url":"https://codeload.github.com/antzGames/Godot-Universal-Settings-Plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246999616,"owners_count":20866937,"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","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":["addon","godot","godot-engine","godot4","plugin","settings"],"created_at":"2024-12-16T09:56:46.356Z","updated_at":"2025-04-03T12:24:32.638Z","avatar_url":"https://github.com/antzGames.png","language":"GDScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Godot Universal Settings Plugin\n\nA versatile, renderer-aware settings screen for Godot 4.3 that seamlessly adapts across all renderers \nand HTML web builds.\n\nThis plugin simplifies user settings management by saving and reloading configurations for graphics, audio settings, and keybinds, ensuring a consistent experience across platforms.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/e6a93658-f99d-4f48-8c93-b955ec0ce274\" width=\"640\"\u003e\n\nNote: This is a BETA version. It should be tested thoroughly to assess its suitability for your needs.\n\n## Table of Contents\n\n- [Features](#features)\n- [Supported Settings](#supported-settings)\n  -\t[Graphics Settings](#graphics-settings)\n  - [Audio Settings](#audio-settings)\n- [Supported Settings by Renderer](#supported-settings-by-renderer)\n- [Why Use This Plugin](#why-use-this-plugin)\n- [Installation](#installation)\n- [How to Use](#how-to-use)\n  - [Show Me a Complete Step-by-Step Example](#show-me-a-complete-step-by-step-example)\n- [How to Apply a Theme](#how-to-apply-a-theme)\n- [Audio Bus Configuration](#audio-bus-configuration)\n- [Configuring Default Settings and Dropdowns](#configuring-default-settings-and-dropdowns)\n- [Keybinds](#keybinds)\n- [How to Delete My Saved Settings](#how-to-delete-my-saved-settings)\n- [Demos Included](#demos-included)\n- [Sponza Demo](#sponza-demo)\n- [Video Tutorial](#video-tutorial)\n- [More Settings Planned?](#more-settings-planned)\n- [Attribution And License](#attribution-and-license)\n\n## Features\n\n**Persistent Settings**: Saves user graphics, audio preferences, and keybinds, reloading them on game startup.\n\n**One-Line Integration**: A single function call to display the settings screen.\n\n**Renderer Awareness**: Automatically adapts to the current renderer, ensuring feature compatibility (more on this [below](#supported-settings-by-renderer)).\n\n**Platform Agnostic**: Works out-of-the-box with HTML/Web builds, mobile, and desktop platforms.\n\n**Customizable Themes**: Supports applying themes to the settings screen, with 4 themes included in the demo project.\n\n**Demo Included**: Comes with a sample project featuring the Godot 3D plush to showcase functionality.\n\n## Supported Settings\n\n### Graphics Settings\n\nThe following graphics options are dynamically adjusted based on the renderer:\n\n- Monitor Selection\n- Window Mode: Fullscreen/Windowed\n- Window Resolution Selection\n- Anti-Aliasing: MSAA (None, 2X, 4X, 8X)\n- 3D Scaling Mode: Bilinear, FSR 1.0, FSR 2.2\n- 3D Scaling Amount\n- FXAA\n- TAA\n- VSync\n\n### Audio Settings\n\nThe plugin supports adjusting and saving the volume of up to 4 audio buses. The plugin includes four predefined audio bus names:\n\n- Master\n- Music\n- SFX\n- Voice\n\nThe `Master` bus is mandatory, but if you do not have the remaining audio buses (Music, SFX, Voice) configured in your project, the plugin will automatically not show them in the settings screen.  There is more information about audio settings and configuring audio buses [below](#audio-bus-configuration).\n\n## Supported Settings by Renderer\n\nHere is a table of the supported settings based on the renderer:\n\n\u003cimg src=\"https://github.com/user-attachments/assets/3fa70c81-26e3-479a-a59b-15c105f5c1fa\" width=\"640\"\u003e\n\nMobile renderer's `Monitor Selection`, `Window/Fullscreen Mode`, `Window Resolution` and `VSync` settings not supported if running on Android or iOS, otherwise it is supported.\n\nAlso, some developers use Compatibility mode to export to Android and iOS, and technically I should also disable `Monitor Selection`, `Window/Fullscreen Mode`, `Window Resolution` and `VSync` settings on Compatibility mode as well.  This is on my TODO list.\n\n## Why Use This Plugin\n\n**Seamless Exporting**:\nNo code modifications are required when exporting to HTML/Web or mobile platforms. The settings screen works consistently across all build targets.\n\n**Dynamic Feature Adaptation**:\nCertain features may not be available on all renderers. This plugin automatically adjusts the settings screen, enabling or disabling features as needed based on the current renderer.\n\n**Ease of Integration**:\nBeing a plugin, it provides a ready-to-use settings screen with just one line of code. Applying themes is equally simple and efficient.\n\n## Installation\n\n**Option 1**: Use this repository as a project template.  Best for beginners.\n\n1. Download or clone this repository.\n2. Start creating a new game by making a new scene.\n3. Set your new scene as the main scene.\n\n**Option 2**: Use as a plugin only.\n\n1. Download or clone this repository.  (Godot AssetLib coming soon)\n2. Copy the this repository's `addons/universal_settings_plugin` folder into your Godot project under `res://addons/universal_settings_plugin/`.\n3. Enable the plugin in the Project Settings under the Plugins tab.\n4. See `Audio bus configuration` section [below](#audio-bus-configuration) to name your audio bus names correctly.\n\n## How to Use \n\n1. Enable the plugin as described [above](#installation).\n2. Call the settings screen with the following code:\n```gdscript\nUniversalSettings.show_screen()\n```\n3. Change any setting you like.  Changes are applied in real time.\n4. Clicking `Save` on the settings screen will save the settings and hide the settings screen.\n\n### Show Me a Complete Step-by-Step Example\n\n1. Create a new Godot project.\n2. Enable the plugin as described [above](#installation).\n3. Create a scene.  \n4. Attach a script to it. \n5. Add the following code to the script:\n\n```gdscript\nfunc _ready() -\u003e void:\n\tpass\n\t\nfunc _input(event: InputEvent) -\u003e void:\n\tif event.is_action_released(\"ui_accept\"):\n\t\tUniversalSettings.show_screen()\n```\t\n\n6. Run your scene.\n7. Pressing `SPACE` or `ENTER` will bring up the settings screen.\n8. Clicking `Save` will save your settings.\n\n## How to Apply a Theme\n\nYou have the ability to apply a theme to the settings screen.  The plugin can load any theme based \non the path you provide. To apply a theme:\n\n```gdscript\nUniversalSettings.set_theme_to(\"res://path/to/theme/mytheme.tres\")\n```\nYou can also change the size of tab container by providing a `Vector2` to the function call:\n\n```gdscript\nUniversalSettings.set_theme_to(\"res://path/to/theme/mytheme.tres\", Vector2(550,510))\n```\nYou can also assign a self modulate color to the tab container:\n\n```gdscript\nUniversalSettings.set_theme_to(\"res://path/to/theme/mytheme.tres\", Vector2(550,510), Color.BLUE)\n```\n\nThe demo project has examples on how to apply themes, tab container size, and tab container color.\n\n## Audio Bus Configuration\n\nUnfortunately, I am not dynamically querying the audio buses from the project because it complicates keeping the saved settings in sync with changes to the project's audio buses information.  I might do it in the future.\n\nThis means you have 3 options.\n\n### Option 1: Do Nothing\n\nEspecially good choice for a newly created projects.  Doing nothing means that only the `Master` bus volume control will show up on the settings menu.  If this is all you need, you do not have to do anything, ever.\n\n### Option 2: Configure Your Audio Bus Names to Match the Plugin\n\nRight now the plugin supports the `Master` audio bus and 3 additional audio buses, and they **need** to be called Music, SFX, and Voice \u003e **IF you do not want to modify the plugin**.\n\nThis is the easiest approach.  Just configure your audio buses to the following:\n\n\u003cimg src=\"https://github.com/user-attachments/assets/c4493891-5441-4c5b-b3d5-c99bfb5ef00f\" width=\"511\"\u003e\n\n### Option 3: Update Plugin for Custom Audio Bus Names\n\nThe other option is to update the name of the audio bus right in the plugin scene.  This can be done in the Inspector of the editor.\n\nTo change the name of the plugin's audio bus follow these instructions:\n\n1. Open the `universal_settings_menu.tscn` scene in the `res://addons/universal_settings/scenes/` folder.\n2. Expand the nodes until you see the `Audio` TabBar node.\n3. Expand all the `Audio` TabBar children.\n4. You should see a node structure as shown in the image below.\n5. Select `VoiceSlider` node as this is most likely the audio bus name you will want to change.\n6. Change `Bus Name` property in the Inspector to the name of your audio bus.\n\nKeep in mind if the plugin does not find your bus with the name you provided, then it will:\n\n- show an warning in the console telling you the bus name was not found.\n- disables this audio bus. This means you will no longer see this audio bus in the settings screen.\n- however the plugin will still work.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/5e4711e6-7590-48ed-81f5-589eddaa323f\" width=\"582\"\u003e\n\n## Configuring Default Settings and Dropdowns\n\n### Default Settings\n\nThere is an very important file named `settings_data_resource.gd` that extends `Resource`, located in the `config` directory of the plugin.\n\nThis file has 2 purposes:\n\n- stores default values of all settings, and used when the game is run for the first time without settings being saved.\n- used as a template for the settings save file.\n\nWhen a save file does not exist or cannot be found, then the plugin will look at this file for the default settings.\n\nThe source code of this file is well documented, so if you need to change the default settings on the first time a user plays your game this is the file you need to modify.\n\n**Keep in mind that the default settings in this file will supersede any project settings.**\n\n### Dropdowns\n\nThe only way to modify the dropdowns is by updating the dictionaries in the plugin's main script:\n\n`iniversal_settings_menu.gd`\n\nYou most likely want to modify the window resolutions dictionary:\n\n```gdscript\n# You can modify these window resolutions to your liking, \n# but there must to be at least ONE entry.\n# Make sure your default resolution is set in the settings_data_resource.gd file\n@export var resolutions : Dictionary = {\n  \"1280x720\"  :  Vector2i(1280, 720),  # index 0\n  \"1440x810\"  :  Vector2i(1440, 810),  # index 1\n  \"1600x900\"  :  Vector2i(1600, 900),  # index 2\n  \"1920x1080\" :  Vector2i(1920, 1080)} # index 3\n```\n\nFeel free to modify the resolutions, but make sure you set the correct index for the default in the `settings_data_resource.gd` file.\n\n### Keybinds\n\nKeybinds allow you to set and persist new keyboard and mouse buttons assignments for each of the custom actions set in your `Project` \u003e `Project Settings` \u003e `Input Map` configuration.\n\nHere are the limitations:\n- Up to 10 actions can be displayed in the keybind tab.\n- Only one event per action is stored.\n- Only keyboard and mouse button events supported.\n- No controller/gamepad support.\n\nUsing keybinds requires you to configure the actions in the plugin.  You must match your  `Project` \u003e `Project Settings` \u003e `Input Map` configuration with the plugin as show below:\n\n\u003cimg src=\"https://github.com/user-attachments/assets/5815d0eb-8009-4570-9b6d-1366a596b030\" width=\"640\"\u003e\n\nSee this video for a demonstration and more information: https://youtu.be/Di7lJP5SvnI\n\n## How to Delete My Saved Settings\n\nIf you want to delete your saved settings on desktop:\n\n`Project` \u003e `Open User Data Folder` \u003e `game_data` \u003e `settings_dataXXX.tres`\n\nThe XXX is the `application/config/version` of your project.\n\nThis makes it easy to force a reset of any saved settings on previous game versions of your user install base by just incrementing the version in your project.  \n\nTo delete saved settings on HTML/Web builds, purge local browser storage. These instructions are browser-specific.\n\n## Demos Included\n\n**Godot 3D Plush Test**:\n\nThis is a dynamic 3D scene with the Godot 3D plush model with a collection of boxes raining down.\n\nThis is a good demo to show how to change the theme, tab container size, and color of the settings screen:\n\n```gdscript\n# If no theme is set then the default Godot theme is used,\n# but you can easily change themes... pick one!\nUniversalSettings.set_theme_to(\"res://demo/assets/themes/clashy/clashy.tres\", Vector2(550,510), Color(1,1,1,0.5))\n#UniversalSettings.set_theme_to(\"res://demo/assets/themes/windows_10_light/theme.tres\", Vector2(550, 345), Color(0,0.471,0.831,0.5))\n#UniversalSettings.set_theme_to(\"res://demo/assets/themes/windows_10_dark/theme.tres\", Vector2(550, 345), Color(1,1,1,0.5))\n#UniversalSettings.set_theme_to(\"res://demo/assets/themes/kenney/kenneyUI.tres\")\n```\n\n**Blank Scene**:\n\nThis is an ultra minimalist demo of the plugin.  Its only 4 lines of code!\n\nIt uses the default theme of the project.\n\nYou will need to set this scene as `Set as Main Scene` in the editor to run this demo.\n\n```gdscript\nfunc _ready() -\u003e void:\n\tUniversalSettings.show_screen()\n\t\nfunc _input(event: InputEvent) -\u003e void:\n\tif event.is_action_released(\"ui_accept\"): UniversalSettings.show_screen()\n```\t\n\u003cimg src=\"https://github.com/user-attachments/assets/114033a0-5471-4452-895b-de59fb46fe12\" width=\"572\"\u003e\n\n## Sponza Demo\n\nI have added this plugin to the godot-sponza-4 demo in a fork at:\n\nhttps://github.com/antzGames/godot-sponza-4\n\nThis projects makes it easier to notice how the MSAA, FSR 1.0, FSR 2.2, TAA, FXAA, and 3D scaling settings affect the scene and FPS.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/cfd21884-0f00-4cd8-972a-468db8a79e28\" width=\"640\"\u003e\n\n## Video Tutorial\n\nYouTube video showing the an overview of the alpha release:\n\nhttps://youtu.be/li1fdAOqewk\n\nYouTube video showing the keybind features and limitations:\n\nhttps://youtu.be/Di7lJP5SvnI\n\n## More Settings Planned?\n\nThe `Forward+` renderer has many more graphics settings that are available.  They include:\n\n- SSR\n- SSAO\n- SSIL\n- SDFGI\n- Volumetric Fog\n\nAdding these settings to this plugin should be easy, as all I need to do is make them visible only when the renderer is set to `Forward+`.  This might be available in the future.\n\nThere are some quality settings that are supported across all renderers that could be supported in this plugin.  They are:\n\n- Shadow resolution (unfortunately if you change the shadow resolution you need to tweak `shadow_bias`)\n- Shadow Filtering (direction and positional)\n- Model quality (`mesh_lod_threshold`)\n\n## Attribution And License\n\nModels:\n\n- Godot 3D plush: https://fr3nkd.gumroad.com/l/vhfvy\n\nThemes:\n\n- Godot Windows 10 Themes: https://github.com/mr-dreich/Godot-Windows-10-Theme\n- Godot Clashy theme: https://github.com/wadlo/Themey\n- Kenney UI Theme: Kenney's UI Pack: https://kenney.nl/assets/ui-pack\n\nLicense:\n\nThis plugin is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantzgames%2Fgodot-universal-settings-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantzgames%2Fgodot-universal-settings-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantzgames%2Fgodot-universal-settings-plugin/lists"}