{"id":16352202,"url":"https://github.com/bugthesystem/natura","last_synced_at":"2025-03-21T00:31:08.469Z","repository":{"id":43680872,"uuid":"422557252","full_name":"bugthesystem/natura","owner":"bugthesystem","description":"A simple, efficient spring animation library for smooth, natural motion in Rust","archived":false,"fork":false,"pushed_at":"2023-08-18T12:18:32.000Z","size":732,"stargazers_count":67,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-20T05:57:34.917Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/bugthesystem.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":"2021-10-29T11:56:52.000Z","updated_at":"2024-09-14T00:54:02.000Z","dependencies_parsed_at":"2024-04-27T08:03:33.244Z","dependency_job_id":"480d5404-a0ac-4323-99e0-0f6010481a79","html_url":"https://github.com/bugthesystem/natura","commit_stats":null,"previous_names":["bugthesystem/natura","ziyasal/natura"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bugthesystem%2Fnatura","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bugthesystem%2Fnatura/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bugthesystem%2Fnatura/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bugthesystem%2Fnatura/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bugthesystem","download_url":"https://codeload.github.com/bugthesystem/natura/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717362,"owners_count":20498282,"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":[],"created_at":"2024-10-11T01:25:18.406Z","updated_at":"2025-03-21T00:31:08.132Z","avatar_url":"https://github.com/bugthesystem.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Natura ![](misc/natura-vegeta.png)\nAn opinionated, simple and efficient spring animation library for smooth, natural motion in Rust\n\n![](misc/demo.gif)\n\n## Usage\n\nNatura is framework-agnostic and works well in 2D and 3D contexts. Simply call [`Spring::new`](https://github.com/ziyasal/natura/blob/main/natura/src/spring.rs#L138) with your settings to initialize and [`update`](https://github.com/ziyasal/natura/blob/main/natura/src/spring.rs#L171) on each frame to animate.\n\nFor details, see the [examples](/examples)\n\n### Examples\n\n#### Example with [2D engine `coffee`](https://github.com/hecrj/coffee)\n`cargo run -p coffee-2d`  \n\n#### Example with [`Bevy Engine`](https://github.com/bevyengine/bevy)\n`cargo run -p bevy-simple`  \n\n**Enable Plugin:**\n\n```rust\nuse bevy_natura::{NaturaAnimationBundle, NaturaAnimationPlugin};\n\n// omitted for brevity\n .add_plugin(NaturaAnimationPlugin::new(\n            DeltaTime(60.0),\n            AngularFrequency(6.0),\n            DampingRatio(0.7),\n        ))\n```\n\nPlease see usage [here](https://github.com/ziyasal/natura/blob/main/examples/bevy-simple/src/main.rs#L44)\n\n#### Simple example\n\n`cargo run -p simple`\n\n**Code:**\n\n```rust\n\n// Where we want to animate it.\nconst TARGET_X: f64 = 50.0;\nconst TARGET_Y: f64 = 100.0;\n\nfn main() {\n    let mut sprite = Sprite::default();\n \n    // initialize a spring with frame-rate, angular frequency, and damping values.\n    let mut spring = Spring::new(DeltaTime(natura::fps(60)), AngularFrequency(6.0), 0.5);\n\n    loop {\n        let (sprite_x, sprite_x_velocity) = spring.update(sprite.x, sprite.x_velocity, TARGET_X);\n        sprite.x = sprite_x;\n        sprite.x_velocity = sprite_x_velocity;\n\n        let (sprite_y, sprite_y_velocity) = spring.update(sprite.y, sprite.y_velocity, TARGET_Y);\n        sprite.y = sprite_y;\n        sprite.y_velocity = sprite_y_velocity;\n\n        sleep(Duration::from_millis(10000));\n\n        // use new position here on every frame\n        println!(\n            \"Sprite x:{}, y:{}, x_vel:{}, y_vel:{}\",\n            sprite.x, sprite.y, sprite.x_velocity, sprite.y_velocity\n        )\n    }\n}\n```\n\n\n## Settings\n\n`Spring::new` takes three values:\n\n* **Time Delta:** the time step to operate on. Game engines typically provide\n  a way to determine the time delta, however if that's not available you can\n  simply set the framerate with the included [`fps(u64)`](https://github.com/ziyasal/natura/blob/main/natura/src/spring.rs#L105) utility function. Make\n  the framerate you set here matches your actual framerate.\n* **Angular Velocity:** this translates roughly to the speed. Higher values are\n  faster.\n* **Damping Ratio:** the springiness of the animation, generally between `0`\n  and `1`, though it can go higher. Lower values are springier. For details,\n  see below.\n\n## Damping Ratios\n\nThe damping ratio affects the motion in one of three different ways depending\non how it's set.\n\n### Under-Damping\n\nA spring is under-damped when its damping ratio is less than `1`. An\nunder-damped spring reaches equilibrium the fastest, but overshoots and will\ncontinue to oscillate as its amplitude decays over time.\n\n### Critical Damping\n\nA spring is critically-damped the damping ratio is exactly `1`. A critically\ndamped spring will reach equilibrium as fast as possible without oscillating.\n\n### Over-Damping\n\nA spring is over-damped the damping ratio is greater than `1`. An over-damped\nspring will never oscillate, but reaches equilibrium at a slower rate than\na critically damped spring.\n\n## Acknowledgements\n\nThis library is a fairly straightforward port of [Ryan Juckett][juckett]’s\nexcellent damped simple harmonic oscillator originally writen in C++ in 2008\nand published in 2012. [Ryan’s writeup][writeup] on the subject is fantastic.\n\n[juckett]: https://www.ryanjuckett.com/\n[writeup]: https://www.ryanjuckett.com/damped-springs/\n\n## License\n\n[UNLICENSE](https://github.com/ziyasal/pmecs/blob/main/LICENSE)\n\n\u003e _This crate is developed to be part of Λ.R.Ξ.N.Λ 2D game engine._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbugthesystem%2Fnatura","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbugthesystem%2Fnatura","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbugthesystem%2Fnatura/lists"}