{"id":26060655,"url":"https://github.com/twelveiterationmods/kumaapi","last_synced_at":"2025-08-21T20:18:50.754Z","repository":{"id":241738708,"uuid":"807444382","full_name":"TwelveIterationMods/KumaAPI","owner":"TwelveIterationMods","description":"Universal Key Modifier API for multi-loader Minecraft Mods","archived":false,"fork":false,"pushed_at":"2025-03-06T09:43:53.000Z","size":346,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"1.21.4","last_synced_at":"2025-03-06T10:34:58.351Z","etag":null,"topics":["fabricmc-mod","forge-mod","minecraft-mod","neoforge-mod"],"latest_commit_sha":null,"homepage":"https://mods.twelveiterations.com/mc/kuma/","language":"Java","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/TwelveIterationMods.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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},"funding":{"github":"BlayTheNinth","patreon":"BlayTheNinth","open_collective":null,"ko_fi":"BlayTheNinth","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2024-05-29T05:50:03.000Z","updated_at":"2025-03-06T09:43:57.000Z","dependencies_parsed_at":"2024-12-03T17:37:19.291Z","dependency_job_id":"f40cc2d4-94a3-4ece-af04-0502539150b2","html_url":"https://github.com/TwelveIterationMods/KumaAPI","commit_stats":{"total_commits":56,"total_committers":4,"mean_commits":14.0,"dds":0.1785714285714286,"last_synced_commit":"1a253311c68a2e99c1d1154196b7a4470567e7c3"},"previous_names":["twelveiterationmods/kuma","twelveiterationmods/kumaapi"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TwelveIterationMods%2FKumaAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TwelveIterationMods%2FKumaAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TwelveIterationMods%2FKumaAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TwelveIterationMods%2FKumaAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TwelveIterationMods","download_url":"https://codeload.github.com/TwelveIterationMods/KumaAPI/tar.gz/refs/heads/1.21.4","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242564981,"owners_count":20150423,"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":["fabricmc-mod","forge-mod","minecraft-mod","neoforge-mod"],"created_at":"2025-03-08T14:29:39.374Z","updated_at":"2025-03-08T14:29:40.606Z","avatar_url":"https://github.com/TwelveIterationMods.png","language":"Java","funding_links":["https://github.com/sponsors/BlayTheNinth","https://patreon.com/BlayTheNinth","https://ko-fi.com/BlayTheNinth"],"categories":[],"sub_categories":[],"readme":"# Kuma\n\nMinecraft Mod. Universal Key Modifier API for Fabric, NeoForge and Forge.\n\n`kuma-api` is a library mod intended to be included in existing mods, providing an easy API layer for compatible\nkey mappings with multi-loader, context and (multi-) modifier support.\n\nIn the future, I plan to make a companion mod that extends the Controls menu with the ability to manage key mappings\nthat otherwise would not be supported within the given loader, such as key modifiers on Fabric,\nmulti-modifiers on (Neo)Forge, and custom modifiers (like `Space + Click`).\n\n#### Downloads\n\nKuma API is meant to be included as an embedded library. There is no file to download or install as a user.\n\n## Who needs this?\n\nThis library is useful for mod developers targeting both Fabric and (Neo)Forge at once, or for those who wish to use the\nsame API for their key mappings even when depending on more advanced features like multiple modifiers or\ncustom modifier keys. Kuma API is designed to progressively upgrade or fallback to match the capabilities of its\nenvironment.\n\nI created it because both Crafting Tweaks and Inventory Essentials have plenty of modifier-based key mappings that were\ndifficult to properly support across the different mod loaders and repeatedly ran into limitations with the Vanilla\nKeyMapping system.\n\n## How to use as a Mod Developer\n\n1\\. Start by changing your gradle files to have `kuma-api` be embedded in your mod's jar.\n\nAdd the following to your `build.gradle`:\n\n```groovy\nrepositories {\n    maven {\n        url \"https://maven.twelveiterations.com/repository/maven-public/\"\n\n        content {\n            includeGroup \"net.blay09.mods\"\n        }\n    }\n}\n```\n\nWhen defining the dependency below, replace the version with the version you want to depend on.\nKuma API follows a versioning scheme where the major and minor version always match the minor and patch version of\nMinecraft.\nSo for Minecraft 1.20.6, you would depend on 20.6.x where x is the patch version of Kuma API itself.\n\nSpecifically on jarJar dependencies, you should also use a version range to ensure your mod will continue to function\neven if another mod ships a later patch version of Kuma API.\n\nYou can find the latest version for a given Minecraft version\nat https://maven.twelveiterations.com/service/rest/repository/browse/maven-public/net/blay09/mods/kuma-common/\n\nIn your `gradle.properties`:\n\n```ini\nkuma_version = 21.4.5+1.21.4\nkuma_version_range = [21.4,21.5)\n```\n\nFor Common / Mojmap:\n\n```groovy\ndependencies {\n    compileOnly \"net.blay09.mods:kuma-api-common:$kuma_version\"\n}\n```\n\nFor NeoForge:\n\n```groovy\njarJar.enable() // Enable the Jar-in-Jar system\n\ndependencies {\n    jarJar(\"net.blay09.mods:kuma-api-neoforge\") {\n        version {\n            strictly kuma_version_range\n            prefer kuma_version\n        }\n    }\n}\n```\n\nFor Fabric:\n\n```groovy\ndependencies {\n    include modApi(\"net.blay09.mods:kuma-api-fabric:$kuma_version\")\n}\n```\n\nFor Forge:\n\n```groovy\njarJar.enable() // Enable the Jar-in-Jar system. Make sure to put this line *before* the minecraft block!\n\ndependencies {\n    jarJar(group: \"net.blay09.mods\", name: \"kuma-api-forge\", version: kuma_version_range) {\n        jarJar.pin(it, kuma_version)\n    }\n}\n```\n\n2\\. In your mod constructor or initializer, start creating key mappings using `Kuma`.\n\nKuma API takes care of registering the vanilla `KeyMapping`s at the correct time.\nThe method returns a `ManagedKeyMapping` instance that you can use to operate on the key mapping later, be it a\nreal `KeyMapping` or a virtual one.\n\nHere's some examples for creating key mappings:\n\n```java\nclass ExampleMod {\n    public ExampleMod() {\n        // Just a regular key mapping with a single modifier.\n        // Will register as a regular KeyMapping on Forge and NeoForge, and as a virtual key mapping on Fabric.\n        Kuma.createKeyMapping(new ResourceLocation(\"example\", \"example_key_1\"))\n                .withDefault(InputBinding.key(InputConstants.KEY_G, KeyModifiers.of(KeyModifier.CONTROL)))\n                .handleScreenInput((event) -\u003e {\n                    // TODO Add your press logic here\n                    return true;\n                })\n                .build(); // Don't forget to call build() at the end!\n\n        // A key mapping with a fallback binding. \n        // If the environment does not support the binding, it will attempt to use the fallback instead of creating a virtual key mapping,\n        // which means this key would not have a default on Fabric environments.\n        Kuma.createKeyMapping(new ResourceLocation(\"example\", \"example_key_2\"))\n                .withDefault(InputBinding.key(InputConstants.KEY_G, KeyModifiers.of(KeyModifier.CONTROL)))\n                .withFallbackDefault(InputBinding.none())\n                .handleScreenInput((event) -\u003e {\n                    // TODO Add your press logic here\n                    return true;\n                })\n                .build(); // Don't forget to call build() at the end!\n\n        // A key mapping with a custom modifier. These will always result in a virtual key mapping if no fallback binding is provided, since \n        // no mod loader supports them, unless the user also installs the Kuma companion mod.\n        Kuma.createKeyMapping(new ResourceLocation(\"example\", \"example_key_3\"))\n                // We want to use SPACE-CLICK by default. This will not be remappable unless the user installs also installs Kuma (not just Kuma API).\n                .withDefault(InputBinding.mouse(InputConstants.MOUSE_BUTTON_LEFT,\n                        KeyModifiers.ofCustom(InputConstants.getKey(InputConstants.KEY_SPACE, -1))))\n                .handleScreenInput((event) -\u003e {\n                    // TODO Add your press logic here\n                    return true;\n                })\n                .build(); // Don't forget to call build() at the end!\n\n        // A nonsense key mapping just to show off the rest of the methods.\n        Kuma.createKeyMapping(new ResourceLocation(\"example\", \"example_key_4\"))\n                // By default, the category is created based on the resource location above. You can override it.\n                .overrideCategory(\"key.categories.movement\")\n                .withDefault(InputBinding.key(InputConstants.KEY_G,\n                        KeyModifiers.of(KeyModifier.CONTROL, KeyModifier.SHIFT)))\n                .withFallbackDefault(InputBinding.key(InputConstants.KEY_G, KeyModifiers.of(KeyModifier.CONTROL)))\n                .withContext(KeyConflictContext.UNIVERSAL) // This is normally just inferred from the supplied input handlers.\n                 // forceVirtual prevents the mapping from being registered as a vanilla key mapping UNLESS the Kuma companion mod is installed.\n                 // Useful when binding to something like SHIFT or another Vanilla default key, because otherwise the Vanilla key would no longer trigger on Fabric.\n                .forceVirtual()\n                .handleScreenInput((event) -\u003e {\n                    // TODO Add your press logic here\n                    return true;\n                })\n                .handleWorldInput((event) -\u003e {\n                    // TODO Add your press logic here\n                    return true;\n                })\n                .build(); // Don't forget to call build() at the end!\n    }\n}\n```\n\n## Contributing\n\nIf you're interested in contributing to the mod, you can check\nout [issues labelled as \"help wanted\"](https://github.com/TwelveIterationMods/Kuma/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).\n\nWhen it comes to new features, it's best to confer with me first to ensure we share the same vision. You can join us\non [Discord](https://discord.gg/VAfZ2Nau6j) if you'd like to talk.\n\nContributions must be done through pull requests. I will not be able to accept translations, code or other assets\nthrough any other channels.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwelveiterationmods%2Fkumaapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwelveiterationmods%2Fkumaapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwelveiterationmods%2Fkumaapi/lists"}