{"id":19346742,"url":"https://github.com/lume/animation-loop","last_synced_at":"2025-04-23T05:30:59.234Z","repository":{"id":57180180,"uuid":"131185650","full_name":"lume/animation-loop","owner":"lume","description":"Easily make and manage animation loops.","archived":false,"fork":false,"pushed_at":"2022-09-07T16:31:26.000Z","size":52,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-05-22T08:20:37.181Z","etag":null,"topics":["3d","3d-graphics","animation","animation-functions","animation-loop","custom-elements","game-dev","graphics","lume","threejs","web-components","webgl"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lume.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-26T16:54:50.000Z","updated_at":"2024-04-05T12:19:45.000Z","dependencies_parsed_at":"2022-09-14T03:31:23.860Z","dependency_job_id":null,"html_url":"https://github.com/lume/animation-loop","commit_stats":null,"previous_names":["trusktr/animation-loop"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lume%2Fanimation-loop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lume%2Fanimation-loop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lume%2Fanimation-loop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lume%2Fanimation-loop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lume","download_url":"https://codeload.github.com/lume/animation-loop/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223909960,"owners_count":17223592,"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","3d-graphics","animation","animation-functions","animation-loop","custom-elements","game-dev","graphics","lume","threejs","web-components","webgl"],"created_at":"2024-11-10T04:12:11.912Z","updated_at":"2024-11-10T04:12:12.781Z","avatar_url":"https://github.com/lume.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nanimation-loop\n==============\n\nEasily make and manage animation loops.\n\n#### `npm install animation-loop --save`\n\n`animation-loop` lets you create animation loops that contain \"animation\nfunctions\" that are called repeatedly in order to animate something. This is a\ncommon thing that any application with animated graphics will want to do.\n\nBasic usage\n-----------\n\n### Animation functions\n\nIn the following sample, a loop is created, and an \"animation function\" is\nadded which will be called repeatedly, in sync with the browser's render loop\n(using `requestAnimationFrame` internally).\n\n```js\nimport AnimationLoop from 'animation-loop'\n\nconst loop = new AnimationLoop\n\nloop.addAnimationFn( ( deltaTime, elapsedTime ) =\u003e {\n\n    console.log( deltaTime, elapsedTime )\n\n})\n\nloop.start()\n```\n\nIt is useful to know the amount of time that passed since the last call of the\nanimation function, and sometimes also useful to know the total elapsed time.\nThese numbers are useful in animating properties of objects such as position,\nrotation, scale, etc.\n\nTo remove an animation loop, there are a few ways to do it.\n\n#### Return `false`\n\nJust return `false` from an animation function to remove it from the loop.\n\nIn this sample, the `console.log` outputs will stop after 5 seconds:\n\n```js\nimport AnimationLoop from 'animation-loop'\n\nconst loop = new AnimationLoop\n\nloop.addAnimationFn( ( deltaTime, elapsedTime ) =\u003e {\n\n    console.log( deltaTime, elapsedTime )\n\n    return !( elapsedTime \u003e 5 )\n\n})\n\nloop.start()\n```\n\n#### By reference\n\nIn this sample, the `console.log` outputs will stop after 5 seconds:\n\n```js\nimport AnimationLoop from 'animation-loop'\n\nconst loop = new AnimationLoop\n\nconst animationFunction = ( deltaTime, elapsedTime ) =\u003e {\n\n    console.log( deltaTime, elapsedTime )\n\n    if ( elapsedTime \u003e 5 ) {\n        loop.removeAnimationFn( animationFunction )\n    }\n\n}\n\nloop.addAnimationFn( animationFunction )\n\nloop.start()\n```\n\n### Base functions\n\nWhen there are no animations, we don't want to redraw the scene, so we can keep\nCPU usage at 0%. This is where \"base functions\" come in.\n\nWe can add base functions to the loop, and then it will only called if the loop\nhas existing animation functions, otherwise base functions will not be executed\nif there are no animation functions, even if the base functions are not removed\nfrom the loop.\n\nThese are useful for adding certain tasks that always need to be executed after\nthe tick of an animation loop, while keeping CPU usage at 0% when there are no\nanimation functions.\n\nFor example, if we are using Three.js for rendering, then we generally always\nwant to call `renderer.render(scene, camera)` after we've modified anything in\na scene.\n\nIn the following sample, we will tell our animation loop how to redraw a scene\nany time that we animate something with an animation function, by adding a base\nfunction that describes how to redraw. Suppose we have references to a Three.js\n`mesh`, `scene`, `camera`, and `renderer`. We will make the `mesh` move back\nand forth based on a sine wave for 5 seconds, after which the animation loop\nwill be removed and CPU usage will go to 0%:\n\n```js\nimport AnimationLoop from 'animation-loop'\n\n// ... create scene, mesh, camera, and renderer ...\n\nconst loop = new AnimationLoop\n\nloop.addAnimationFn( ( deltaTime, elapsedTime ) =\u003e {\n\n    mesh.position = 10 * Math.sin( elapsedTime )\n\n    return !( elapsedTime \u003e 5 )\n\n})\n\nloop.addBaseFn( () =\u003e {\n    renderer.render(scene, camera)\n})\n\nloop.start()\n```\n\nAfter the animation completed, the base function was not removed: it still\nremains in the loop. At a future point in time, we can add a new animation\nfunction to animate the `mesh` again, and it will simply work, and when\nfinished, the animation function is removed and CPU use goes back to 0%. This\ntime we animation rotation:\n\n```js\n// The loop is already started, so time is still elapsing (though CPU is still at 0% use)\n\n// ... 5 seconds have passed after the previous animation function was removed ...\n\nloop.addAnimationFn( ( deltaTime, elapsedTime ) =\u003e {\n\n    mesh.rotation = 10 * Math.sin( elapsedTime )\n\n    return !( elapsedTime \u003e 15 )\n\n})\n\n// no need to add the base function again, it is already added to our loop.\n```\n\nWhat happened overall is we created a loop, started it (it tracks time), added\nthe first animation function to animate `position` for 5 seconds, let 5 seconds\npass, then added another animation function to animate `rotation`. During both\nanimations, the base function handled redrawing of our scene. Between 5 and 10\nseconds, nothing was happening so CPU use was at 0%, between 10 and 15 seconds\nthe second animation was in play and using CPU, and finally after 15 seconds\nthe second animation ended and CPU went back to 0%.\n\nTODO\n----\n\n- [ ] Explain other parts of the API, `ChildAnimationLoop`s with child time\n  frames, and usage patterns.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flume%2Fanimation-loop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flume%2Fanimation-loop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flume%2Fanimation-loop/lists"}