{"id":19564284,"url":"https://github.com/ronenness/spritenator","last_synced_at":"2026-03-04T10:03:25.053Z","repository":{"id":57368022,"uuid":"70924252","full_name":"RonenNess/spritenator","owner":"RonenNess","description":"An easy way to turn dom elements into animated sprites using spritesheets!","archived":false,"fork":false,"pushed_at":"2016-10-14T16:05:05.000Z","size":133,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-09T00:36:19.823Z","etag":null,"topics":["animation-sequence","gamedev","html","javascript-library","sprites","spritesheet"],"latest_commit_sha":null,"homepage":null,"language":"HTML","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/RonenNess.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}},"created_at":"2016-10-14T15:42:47.000Z","updated_at":"2024-08-17T13:47:36.000Z","dependencies_parsed_at":"2022-08-23T20:11:03.684Z","dependency_job_id":null,"html_url":"https://github.com/RonenNess/spritenator","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2Fspritenator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2Fspritenator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2Fspritenator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2Fspritenator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RonenNess","download_url":"https://codeload.github.com/RonenNess/spritenator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240823419,"owners_count":19863434,"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":["animation-sequence","gamedev","html","javascript-library","sprites","spritesheet"],"created_at":"2024-11-11T05:21:11.572Z","updated_at":"2026-03-04T10:03:24.829Z","avatar_url":"https://github.com/RonenNess.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Spritenator](img/logo.gif \"Spritenator\")\n\n# Spritenator\n\nSpritenator is a micro lib that turns simple img element into sprite-sheet animations.\n\nNo dependencies, no jQuery, just plug and play! (pun intended)\n\n[Live example](https://ronenness.github.io/spritenator/).\n\n\n## Install\n\nVia bower:\n\n```\nbower install spritenator\n```\n\nVia npm\n\n```\nnpm install spritenator\n```\n\nOr simply download the js files from /dist/ in this repo and include it in a script tag.\n\n## Usage Example\n\nLets start with a basic example.\n\nTo create a sprite, you first need to create an image element inside a div, and use your spritesheet as the image src:\n\n```HTML\n\u003cdiv id=\"sprite\" style=\"width:100px; height:100px;\"\u003e\n    \u003cimg src=\"sprite.png\"\u003e\n\u003c/div\u003e\n```\n\nNow to init the sprite:\n\n```JavaScript\n// first define the different animations in the sprite-sheet (see file example/sprite.png for more info)\n// note: steps goes from top-left corner to bottom right (starting with 0)\nvar animations = {\n    \"idle\": Spritenator.animation({steps: [0,1,2,3,4,5,6,7,8,9], fps: 5}),\n    \"taunt\": Spritenator.animation({steps: [10,11,12,13,14,15,16,17,18,19], fps: 12, next: \"idle\"}),\n    \"hop\": Spritenator.animation({steps: [20,21,22,23,24,25,26,27,28,29], fps: 12}),\n};\n\n// init sprite on the div element\n// note: the \"{x: 10, y: 5}\" param define the spritesheet size: 10 columns and 5 rows of animation steps. \nvar elem = document.getElementById(\"sprite\");\nSpritenator.create(elem, {x: 10, y: 5}, animations);\n\n```\n\n## Spritenator API\n\nAfter seeing a simple example, lets dive into the API.\n\n### Spritenator.animation()\n\nTo create a new sprite you first need to define a dictionary with all the spritesheet animations. \nYou use ```Spritenator.animation()``` to define each animation sequence. \n\nFor example:\n\n```JavaScript\nvar animations = {\n    \"some_anim\": Spritenator.animation({steps: [0,1,2,3,4,5,6], fps: 5, loop: true}),\n};\n```\n\nWill define a sprite with a single animation, \"some_anim\", that will play steps 0-6 in an endless loop with 5 frames per second.\n\nThe function ```Spritenator.animation()``` accept a single dictionary as param, with the following options:\n\n#### steps\n\nA list with the animation sequence steps. \nEvery value in this list is a step index, counted from top-left corner.\n\n#### delays\n\nOptional list of extra delays, in milliseconds, to add to each animation step.\n\nFor example if you want the third step to halt for 1.5 seconds, you can set [0, 0, 1500] as delays (the two 0's in the beginning of the list is to skip step 1 and 2). \n\n#### fps\n\nFrames per seconds, determine the general animation speed (delays, if provided, are added on top of the basic speed).\n\n#### loop\n\nIf true, this animation will play in loops (default to true). If false, animation will play once and stop.\n\n#### next\n\nOptional string or function to determine the next animation to play right after this one ends.\n\nFor example, you can define an animation sequence that will play once and then switch to an animation called \"idle\".\n\n#### startDelay\n\nDelay, in milliseconds, to add to first animation step.\n\n#### endDelay\n\nDelay, in milliseconds, to add to last animation step.\n\n#### onStart\n\nFunction to call whenever animation sequence starts playing.\n\n#### onEnd\n\nFunction to call whenever animation sequence ends.\n\n### Creating Sprites\n\nSprites are the most basic object of Spritenator. \nThey attach to an existing div element and play animation sequences with it, using the internal img tag.\n\nThe function ```Spritenator.create()``` creates a new sprite instance. It requires the following params:\n\n#### element\n\nThe div element to create the sprite from. Must be in the following format:\n\n```HTML\n\u003cdiv id=\"some-id\" style=\"width:100px; height:100px;\"\u003e\n    \u003cimg src=\"sprite.png\"\u003e\n\u003c/div\u003e\n```\n\nWhere ```sprite.png``` is your spritesheet file. Note: the containing div must define sprite size.\n\n#### sheetSize\n\nA dictionary with ```x``` and ```y```, representing the spritesheet size, eg how many columns and rows of animation steps it contains (note: spritesheets are assumed to have the same size for every animation step).\n \n#### animations\n\nThe animations dictionary we defined above, using ```Spritenator.animation()```.\n\n### Retrieving existing sprites\n\nAfter you create a sprite instance you can always get it back from the dom element, using ```Spritenator.get()```:\n\n```JavaScript\n// assuming sprite was init on 'element' before.\nvar element = document.getElementById(\"my-id\");\nvar sprite = Spritenator.get(element);\n```\n\n### Sprite API\n\nOnce you create a new sprite instance, you can use the following sprite API:\n\n#### play (name, forceReset, next)\n\nStart playing an animation sequence.\n\n- name: the name of the animation to play (key from the animations dictionary).\n- forceReset: if true will restart animation even if already playing it.\n- next: can override the animation default 'next' param, and decide which animation to play after this sequence ends (can be a string or a callback).\n\n#### reset function()\n\nReset current animation.\n\n#### current()\n\nGet the name of the animation currently playing.\n\n#### destroy()\n\nDestroy and cleanup this sprite. Note: image element will remain at its current state. \nIf you need to remove the dom elements as well, its your responsibility.\n\n#### speed [float]\n\nSpeed factor you can set to change the speed of all animations in sprite. For example, if you set\n\n```JavaScript\nsprite.speed = 3.0;\n```\n\nAll animations in sprite will play x3 times faster.\n\n#### paused [boolean]\n\nIf true, animation will pause until set to false.\n\n#### step (time)\n\nThis function will advance the animation by a given time factor (in milliseconds).\n\nIt is used internally and normally you should not use it, but it might become handy for some special effects.\n\n## What next\n\nTo learn more about Spritenator please see the [Live Example](https://ronenness.github.io/spritenator/), or you can explore the JavaScript file yourself (its really just one lightweight JS file).\n\n## License\n\nSpritenator is distributed under the MIT license and is free for any personal and / or commercial use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronenness%2Fspritenator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronenness%2Fspritenator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronenness%2Fspritenator/lists"}