Description
Skills & States
A library to create and manage skills and states. A skill can be an action like a super-high jump, a damaging aura or a passive one like a stat boost. A state is the same thing but temporary and with no need to unlock it before applying it.
Doesn't provide any base skill.
Contains partially AI-generated tests, docs, and code (manually reviewed and humanly engineered)
Here's the documentation.
Here some examples of how to register a skill:
skills.register_skill("example_mod:counter", {
name = "Counter",
description = "Counts. You can use it every 2s.",
sounds = {
cast = {name = "ding", pitch = 2}
},
cooldown = 2,
data = {
counter = 0
},
cast = function(self)
self.data.counter = self.data.counter + 1
print(self.pl_name .. " is counting: " .. self.data.counter)
end
})
skills.register_skill("example_mod:heal_over_time", {
name = "Heal Over Time",
description = "Restores a heart every 3 seconds for 30 seconds.",
loop_params = {
cast_rate = 3,
duration = 30
},
sounds = {
cast = {name = "heart_added"},
bgm = {name = "angelic_music"}
},
cast = function(self)
local player = self.player
player:set_hp(player:get_hp() + 2)
end
})
skills.register_skill("example_mod:boost_physics", {
name = "Boost Physics",
description = "Multiplies the speed and the gravity x1.5 for 3 seconds.",
loop_params = {
duration = 3
},
sounds = {
start = {name = "speed_up"},
stop = {name = "speed_down"}
},
physics = {
operation = "multiply",
speed = 1.5,
gravity = 1.5
}
})
skills.register_skill("example_mod:set_speed", {
name = "Set Speed",
description = "Sets speed to 3.",
passive = true,
data = {
original_speed = {}
},
on_start = function(self)
local player = self.player
self.data.original_speed = player:get_physics_override().speed
player:set_physics_override({speed = 3})
end,
on_stop = function(self)
self.player:set_physics_override({speed = self.data.original_speed})
end
})
Releases
2026-05-07 02:14 UTC
2.1.2
- feat(entities): add state support to expiring entities
- docs: restructure and clarify developer documentation (closes #38)
- test(build): improve test output capture and result detection
- refactor(blocking): unify skill/state blocking API with filter field (closes #37)
- Added translation using Weblate
- fix(physics): clamp near-zero factors
- fix(registration): preserve is_layer
- fix(monoids): key branches by ref
- fix(lifecycle): stop entries on death
- fix(stop): guard deferred HUD cleanup
- fix(database): flush unregistered entries
- fix(lifecycle): stop states on leave
- fix(stop): cancel pending jobs
- fix(registration): allow empty base layers
- fix(dynamic): clear nested keys on removal
- fix(start): reject duplicate HUD names
- chore: trim comments
- fix(dynamic): isolate resolver entries per instance
- fix(utils): return a sorted active-skill stack
- feat: add Lua code style checker and integrate into CI/CD
- fix: oopsie doopsie, CI wasn't installing py3
- feat: auto-default cast_rate to 0 when can_cast is set on looped skills and add validation to reject unknown keys in def tables
- fix(cast): move dtime calculation before can_cast check and stop looped skill on can_cast failure
- fix(database): clean up stale skill-to-state entries during player import
- Added experimental AGENTS.md for AI agents to follow when interacting with the codebase
- Removed flow section from AGENTS.md
2026-04-09 02:14 UTC
2.1.1
- Added translation using Weblate (Dutch)
- .tr -> .po
- fix: update min_minetest_version to 5.10
- refactor: enhance userdata handling in data table
2026-01-19 02:15 UTC
2.1.0
- Fixed some typos in DOCS
- Improved docs for for_each_player_in_db()
- Translated using Weblate
- Automatic testing CI and some fixes along the way
- Improved expiring entities handling: it was conflicting with mods like mtobjid
- docs: add README for Docker test harness setup and usage
- docs: add __last_start_timestamp parameter to skill function documentation
- add is_running method to skill metatable
- fix: prevent duplicate layer application in register_skill function
- Bring the types in!
-
- new field: loop_params.extend_duration_on_restart
- ...I forgot DOCS
- refactor: enhance type definitions with DynamicValue support in LoopParams and SoundSpec
- CRASHFIX: dynamic values in physics were crashing when iterating the dynamic table + better dynamic varargs handling
2025-09-29 02:15 UTC
2.0.1
- Fix typo in documentation regarding custom user-defined parameters naming convention
- Added some logs and fixed dynamic properties metatable overriding skills original metatable
- Removing states from DB in case they got saved from previous versions of mods
- Oops, last commit didn't work
2025-08-03 02:12 UTC
2.0
No release notes
All releases
Threads
New thread
Information
Provides
skills
Dependencies
- Required
-
lib_chatcmdbuilder
- Optional
-
mtt
player_monoids
Information
- Type
- Mod
- Technical Name
- skills
- Languages
-
English, Deutsch, Español, Français, Magyar, Italiano, Polski, Português do Brasil, Русский
- License
-
GPL-3.0-only
- Maintenance State
- Actively Developed
- Added
- 2022-11-13 23:34 UTC
- Maintainers
-
giov4
Used By
Long overdue
I recall how much I wanted a skills library when I was working on a mod of mine last year. I also wondered back then how it was possible that no one had ever thought about creating something useful like a mod that allowed you to easily introduce skills in your game. Because it's something that basically every genre might need. RPG, FPS, MOBA, you name it. I also recall how I ended up throwing in the towel because I couldn't focus on yet another mod to maintain. So I renounced.
...until now! Thanks for what you're doing :)
Underrated
I was searching for simple skills and found an api but i was curious and opened the docs and code. Wow 😮 This seems very well designed, idk why no other mods seem to use it on cdb but it seems very flexible and customizable. Other "skills" framework are kinda ridicoulous in comparison, even though they usually are not as generalistic. But it also allows states in a very simple way re-using the same mechanism so double wow. Good job, maybe I'll use it for some mods with my friends! The only downside is that it doesn't provide any default things but it's a sensible choice if this only aims to be a core library
Good job!
Well.... This mod is very similar to those moba games you know and it's very beautiful to tell the truth bro.