{"id":15722564,"url":"https://github.com/astrochili/defold-kinematic-walker","last_synced_at":"2025-05-05T21:15:55.894Z","repository":{"id":40001097,"uuid":"489664512","full_name":"astrochili/defold-kinematic-walker","owner":"astrochili","description":"Kinematic character controller extension for Defold","archived":false,"fork":false,"pushed_at":"2024-04-01T21:41:57.000Z","size":469,"stargazers_count":53,"open_issues_count":11,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-05T21:15:48.329Z","etag":null,"topics":["3d","character","defold","kinematic"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/astrochili.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-05-07T12:15:05.000Z","updated_at":"2025-04-23T12:45:25.000Z","dependencies_parsed_at":"2023-01-28T00:01:07.350Z","dependency_job_id":"1562360b-dd48-443b-802b-f054f8e4bc4b","html_url":"https://github.com/astrochili/defold-kinematic-walker","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-kinematic-walker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-kinematic-walker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-kinematic-walker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrochili%2Fdefold-kinematic-walker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astrochili","download_url":"https://codeload.github.com/astrochili/defold-kinematic-walker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252577025,"owners_count":21770721,"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":["3d","character","defold","kinematic"],"created_at":"2024-10-03T22:08:24.594Z","updated_at":"2025-05-05T21:15:55.861Z","avatar_url":"https://github.com/astrochili.png","language":"Lua","funding_links":["https://buymeacoffee.com/astrochili"],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"![logo](https://user-images.githubusercontent.com/4752473/175769046-bbf9f71c-c970-4921-a27f-d56361ce0e53.png)\n\n# Kinematic Walker\n\n[![Release](https://img.shields.io/github/v/release/astrochili/defold-kinematic-walker.svg?include_prereleases=\u0026sort=semver\u0026color=blue)](https://github.com/astrochili/defold-kinematic-walker/releases)\n[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/astrochili/defold-kinematic-walker/blob/master/LICENSE)\n[![Website](https://img.shields.io/badge/website-gray.svg?\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxOCIgaGVpZ2h0PSIxNiIgZmlsbD0ibm9uZSIgdmlld0JveD0iMCAwIDE4IDE2Ij48Y2lyY2xlIGN4PSIzLjY2IiBjeT0iMTQuNzUiIHI9IjEuMjUiIGZpbGw9InVybCgjYSkiLz48Y2lyY2xlIGN4PSI4LjY2IiBjeT0iMTQuNzUiIHI9IjEuMjUiIGZpbGw9InVybCgjYikiLz48Y2lyY2xlIGN4PSIxMy42NSIgY3k9IjE0Ljc1IiByPSIxLjI1IiBmaWxsPSJ1cmwoI2MpIi8+PHBhdGggZmlsbD0idXJsKCNkKSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNNy42MyAxLjQ4Yy41LS43IDEuNTUtLjcgMi4wNSAwbDYuMjIgOC44MWMuNTguODMtLjAxIDEuOTctMS4wMyAxLjk3SDIuNDRhMS4yNSAxLjI1IDAgMCAxLTEuMDItMS45N2w2LjIxLTguODFaIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiLz48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImEiIHgxPSIyLjQxIiB4Mj0iMi40MSIgeTE9IjEzLjUiIHkyPSIxNiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNGRDhENDIiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGOTU0MUYiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0iYiIgeDE9IjcuNDEiIHgyPSI3LjQxIiB5MT0iMTMuNSIgeTI9IjE2IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHN0b3Agc3RvcC1jb2xvcj0iI0ZEOEQ0MiIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iI0Y5NTQxRiIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJjIiB4MT0iMTIuNCIgeDI9IjEyLjQiIHkxPSIxMy41IiB5Mj0iMTYiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBzdG9wLWNvbG9yPSIjRkQ4RDQyIi8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjRjk1NDFGIi8+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9ImQiIHgxPSIuMDMiIHgyPSIuMDMiIHkxPSIuMDMiIHkyPSIxMi4yNiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIHN0b3AtY29sb3I9IiNGRkU2NUUiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRkM4MzAiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48L3N2Zz4=)](https://astronachos.com/)\n[![Mastodon](https://img.shields.io/badge/mastodon-gray?\u0026logo=mastodon)](https://mastodon.gamedev.place/@astronachos)\n[![Twitter](https://img.shields.io/badge/twitter-gray?\u0026logo=twitter)](https://twitter.com/astronachos)\n[![Telegram](https://img.shields.io/badge/telegram-gray?\u0026logo=telegram)](https://t.me/astronachos)\n[![Buy me a coffee](https://img.shields.io/badge/buy_me_a_coffee-gray?\u0026logo=buy%20me%20a%20coffee)](https://buymeacoffee.com/astrochili)\n\n📼 Also in this series:\n- 🎥 [Operator](https://github.com/astrochili/defold-operator)\n- 🏗️ [TrenchFold](https://github.com/astrochili/defold-trenchfold)\n- 🎄 [Illumination](https://github.com/astrochili/defold-illumination)\n- 🚧 [Blockout Textures](https://github.com/astrochili/blockout-textures)\n\n## Overview\n\nThis is a tweakable kinematic character controller suitable for 3D games made with [Defold](https://defold.com). When you wouldn't like to use a dynamic body and prefer to have more control over the movement.\n\nAlthough not all the collision cases are handled perfect at the moment, you can [avoid problems](#troubleshooting) by providing valid and smooth collision geometry of your level. The geometry in the demo is not smooth exclusively for stress testing purposes.\n\nReady to use with [🎥 Operator](https://github.com/astrochili/defold-operator/) or you own camera controller.\n\n🎮 [Play HTML5 demo](https://astronachos.com/defold/kinematic-walker).\n\n💬 [Discuss on the forum](https://forum.defold.com/t/kinematic-walker-character-movement-controller-for-3d-games/71160/).\n\n## Features\n\n- [x] Collision resolving with level geometry.\n- [x] Walking and running.\n- [x] Jumping and crouching.\n- [x] Climbing slopes and curbs.\n- [x] Smooth acceleration and deceleration.\n- [x] Internal control with key bindings.\n- [x] External manual control with messages.\n- [x] Spectator mode.\n- [ ] Request by [adding an issue or contribute](https://github.com/astrochili/defold-kinematic-walker/issues).\n\n## Install\n\nAdd link to the zip-archive of the latest version of [defold-kinematic-walker](https://github.com/astrochili/defold-kinematic-walker/releases) to your Defold project as [dependency](http://www.defold.com/manuals/libraries/).\n\n## Project Settings\n\nThe following settings in the `game.project` file are recommended for the walker to work correctly:\n\n```ini\n[physics]\ntype = 3D\nuse_fixed_timestep = 1\nmax_fixed_timesteps = 1\n\n[display]\nupdate_frequency = 60\n\n[engine]\nfixed_update_frequency = 60\n```\n\n## Quick Start\n\nAdd the `dummy.collection` collection to your scene. It's already composed collection of the player with capsule collision objects and models to test hypotheses and adjust things for your needs.\n\nMake sure you set up the camera correctly or connect [Operator](#operator). The `dummy.script` can integrate it automatically, so just fill in the url in the `operator` property.\n\n## Advanced Start\n\n### Minimal setup\n\n1. Add a gameobject `body` to your character's gamoobject and attach the `body.script` component to it.\n\n2. Add the `collision_standing` collision object with the capsule shape to the `body` gameobject. Set type to `Kinematic` and switch locked rotation to `true`. The position anchor must be on the floor.\n\n2. Add `walker.script` to your character's gameobject and configure its script properties in the editor.\n\n### Crouching\n\nTo allow crouching add the `collision_crouching` collision object with the capsule shape with the same collision properties as the `collision_standing` but with a lower height. Then set the [`is_crouching_allowed`](#is_crouching_allowed) to `true`.\n\n### Camera\n\nTo follow your camera gameobject rotation:\n\n```lua\n  msg.post(walker_url, hash 'follow_camera_rotation', { camera = camera_url })\n```\n\nTo automatically move the camera up and down when standing and crouching add an empty gameobject `eyes` in the walker gameobject and use it to attach your camera. Then set the [`eyes_switching`](#eyes_switching) to `true`.\n\n### Operator\n\nTo use [Operator](https://github.com/astrochili/defold-operator/) as the camera controller:\n\n```lua\n  msg.post(operator_url, hash 'follow_point', { object = eyes_url })\n  msg.post(walker_url, hash 'follow_camera_rotation', { camera = operator_url })\n```\n\n### Controls\n\nTo customize controls just change [`internal_control`](#internal_control-1) key bindings or post [`manual_control`](#manual_control) messages to control the movement manually.\n\n## Walker Properties\n\n### observer\n\nThe `url`  where to send the walker events. Usually it's your character script.\n\n### spectator_mode\n\nActivates the spectator mode during initialization. In this mode you can fly without the gravity applying.\n\n### spectator_clipping\n\nResolves the collisions in the spectator mode. If you disable this option, you can fly through walls.\n\n### internal_control\n\nEnables internal control with default key bindings during initialization.\n\n### normal_speed\n\nNormal speed of walking. Units per second.\n\n### shift_speed\n\nAlternative speed of walking is activated with the [`input.shift`](#internal_control-1). Units per second.\n\nIf you want to run by default and walk only with the shift input set this property less than [`normal_speed`](#normal_speed).\n\n### acceleration\n\nHow much units of velocity should be changed per second to get a greather velocity. Use your [`normal_speed`](#normal_speed) and [`shift_speed`](#shift_speed) as references.\n\n- `10` - if the `normal_speed` is `5`, then the time required to accelerate from the zero velocity to the walking velocity will be `0.5` seconds.\n- `0` - _don't use if you want to move the walker._\n\n### deceleration\n\nHow much units of velocity should be changed per second to get a lower velocity. Use your `normal_speed` and `shift_speed` as references.\n\n- `20` - if the `normal_speed` is `5`, then the time required to decelerate from the walking velocity to the zero velocity will be `0.25` seconds.\n- `0` - _don't use otherwise you will never stop the walker._\n\n### stair_height\n\nMaximum height of the stair to climb.\n\n- `0` - ignore any stairs.\n- `0.3` - automatically moves up on surfaces no higher than `0.3`.\n\n### stair_angle\n\nMaximum deviation angle in degrees of the stair surface to climb.\n\nAllowed values are from `0` to `30` degrees, because after `30` it's too unstable.\n\n- `0` - only horizontal stairs will be handled.\n- `15` - stairs with angle from `-15` and up to `15` degrees will be handled.\n\n### jump_power\n\nSpeed of the jump impulse in units per second. Applies immediately to `y` of the current velocity.\n\n- `10` - jump immediately up with `10` units per second speed.\n\n### anti_bunny_time\n\nSeconds required to stay on the ground before the next jump.\n\n- `0.2` - a little delay before the next jump.\n\n### air_control\n\nHow much is possible to change the moving direction in the air.\n\n- `0` - where it jumped, that's where it fall.\n- `0.3` - a little control over the direction of the fall.\n- `1` - a full control of horizontal moving in the air.\n\n### climbing_angle\n\nThe angle of slopes which are available for climbing.\n\nAllowed value is from `0` up to `90` degrees.\n\n- `0` - any slope will be as a wall.\n- `46` - allow to climb slopes up to `46` degrees.\n\nUse a value that will never be used in the level geometry to avoid persistence mistakes.\n\n### slope_speed_factor\n\nHow much the angle of the slope affects the walker speed.\n\nThe calculation comes from the fact that a 45 degree slope is -50% speed on the uphill and +50% speed on the downhill. Then this effect is multiplied by this factor.\n\n- `0` - the speed always is the same.\n- `0.5` - half of the effect applies.\n\n### gravity\n\nThe force of gravity when there is no ground under the walker. Units per second.\n\n- `vmath.vector3(0, -8, 0)` - a falling gravity with 8 units per second speed.\n\nThe `x` or `z` gravity values also should work but has not been tested enough.\n\n### gravity_acceleration\n\nHow much units of velocity should be changed per second to reach the [`gravity`](#gravity) velocity.\n\n- `3` - if the `gravity.y` is `-6`, then the time required to accelerate from the zero velocity to the gravity velocity is `2` seconds.\n\n### sensor_length\n\nThe sensor length to check the ground, ceiling and slopes. Minimum value is `0.05` because of the Bullet physics [collision margin](https://forum.defold.com/t/using-a-dae-mesh-for-collision/69434/3).\n\n### is_crouching_allowed\n\nAllows to crouch. Be sure that the `collision_crouching` is set.\n\n### collision_standing\n\nThe `url` of the collision object with a standing capsule shape.\n\n### collision_crouching\n\nThe `url` of the collision object with a crouching capsule shape.\n\nIs optional if you don't plan to allow crouch.\n\n### eyes_switching\n\nAnimates the [`eyes`](#eyes) gameobject position up and down when standing and crouching.\n\n### eyes\n\nThe `url` of a gameobject for the camera attachment. Its position will be animated when the [`eyes_switching`](#eyes_switching) is `true`.\n\nIs optional if you don't plan to switch the camera position.\n\n### eyes_switch_duration\n\nDuration of the [`eyes`](#eyes) gameobject position animation when crouching and standing.\n\n## Incoming Messages\n\n### debug\n\nEnable or disable the debug mode. It draws some debug lines to understand what happens.\n\n```lua\nmsg.post(walker_url, hash 'debug', { is_enabled = true } )\n```\n\n### spectator_mode\n\nEnable or disable the [spectator mode](#spectator_mode).\n\n```lua\nmsg.post(walker_url, hash 'spectator_mode', { is_enabled = true } )\n```\n\n### collision_mask\n\nUnfortunately, there is no way to get your collision object mask automatically in Defold at the moment. So if you use a mask other than `default` in [`collision_standing`](#collision_standing) and [`collision_crouching`](#collision_crouching), please provide it with this message during initialization.\n\n```lua\nmsg.post(walker_url, hash 'collision_mask', { hash 'default', hash 'solid' } )\n```\n\n### follow_camera_rotation\n\nFollow the camera object rotation to apply it on the walker rotation.\n\n```lua\nmsg.post(walker_url, hash 'follow_camera_rotation', { camera = camera_url })\n```\n\n### unfollow_camera_rotation\n\nStop to follow the camera object rotation.\n\n```lua\nmsg.post(walker_url, hash 'unfollow_camera_rotation')\n```\n\n### internal_control\n\nConfigure internal controls. Set action identifiers or disable the internal control at all.\n\n- `is_enabled` - enanbles or disables internal control.\n- `bindings.forward` - forward moving action id.\n- `bindings.backward` - backward moving action id.\n- `bindings.left` - left strafing action id.\n- `bindings.right` - right strafing action id.\n- `bindings.jump` - jumping action id.\n- `bindings.crouch` - crouching action id.\n- `bindings.shift` - alternative walking speed action id.\n\n```lua\nlocal bindings = {\n    forward = hash 'key_w',\n    backward = hash 'key_s',\n    left = hash 'key_a',\n    right = hash 'key_d',\n    jump = hash 'key_space',\n    crouch = hash 'key_c',\n    shift = hash 'key_lshift'\n}\n\nlocal message = {\n    is_enabled = true,\n    bindings = bindings\n}\n\nmsg.post(walker_url, hash 'internal_control', message)\n```\n\n### manual_control\n\nManually control movement of the walker. The structure is similar with [bindings](#internal_control-1) but all the values must be `bool` or `nil`.\n\n```lua\nlocal input = {\n    forward = true,\n    left = true,\n    crouch = true,\n}\n\nmsg.post(walker_url, hash 'manual_control', input)\n```\n\n### teleport\n\nMove the walker instantly to another position. Since `go.set_position()` is used inside the walker script for its own purposes, use this message to change the position.\n\n```lua\nmsg.post(walker_url, hash 'teleport', { position = vmath.vector3() } )\n```\n\n### pause\n\nEnables or disables the update and collision resolving functions.\n\n```lua\nmsg.post(walker_url, hash 'pause', { is_paused = true })\n```\n\nUseful in HTML5 builds when the web browser tab loses the focus, check the [example](example/player.script).\n\n## Outgoing Messages\n\n### walker_moving\n\n- `direction` - a normalized direction of the movement.\n- `speed` - speed in the units per second.\n- `is_grounded` - standing on the ground or not.\n\nSends to the [`observer`](#observer) when speed of the walker is greather than zero.\n\n### walker_standing\n\nSends to the [`observer`](#observer) when the walker has stood up.\n\n### walker_crouching\n\nSends to the [`observer`](#observer) when the walker has crouched down.\n\n### walker_jumping\n\nSends to the [`observer`](#observer) when the walker has jumped.\n\n### walker_falling\n\n- `height` - the height of the fall.\n\nSends to the [`observer`](#observer) when the walker has fell down on the ground.\n\nThe counter starts from the highest visited point in the air.\n\n### walker_trigger_enter\n\nForwards the [`trigger_response`](https://defold.com/ref/beta/physics/#trigger_response) to the [`observer`](#observer) when the walker has entered a trigger.\n\n### walker_trigger_exit\n\nForwards the [`trigger_response`](https://defold.com/ref/beta/physics/#trigger_response) to the [`observer`](#observer) when the walker has left a trigger.\n\n### object_post_movement\n\n- `position` - the actual position of the walker.\n- `correction` - the last position correction.\n\nSends to the [`observer`](#observer) and the following [`camera`](#follow_camera_rotation) post movement corrections after collision resolving in the `on_message` function.\n\n\u003e Used by [Operator](https://github.com/astrochili/defold-operator/) to update the camera position without lags.\n\n### ground_normal\n\n- `normal` - the ground normal or nil.\n\nSends to the following [`camera`](#follow_camera_rotation) the current ground normal.\n\n\u003e Used by [Operator](https://github.com/astrochili/defold-operator/) to align the camera to the ground slope.\n\n## Troubleshooting\n\n### Stairs\n\nThe current handling of stairs is more suitable for climbing on curbs. Don't use the stairs as is, better to use a slope collision object.\n\n### Internal geometry\n\nTo avoid stucking along the objects, try to remove any internal unused collision geometry.\n\nUsing of planes as collision objects along the wall is preferable to boxes to avoid collisions with the joints of these boxes. Keep the collision geometry as simple as possible.\n\n### Fall into a gorge\n\nPlace a horizontal hidden collision object at the bottom of the gorge so that there is something to stand on, otherwise the walker may get stuck.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrochili%2Fdefold-kinematic-walker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastrochili%2Fdefold-kinematic-walker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrochili%2Fdefold-kinematic-walker/lists"}