{"id":13676397,"url":"https://github.com/Antoshidza/NSprites","last_synced_at":"2025-04-29T07:32:07.869Z","repository":{"id":41413853,"uuid":"466501361","full_name":"Antoshidza/NSprites","owner":"Antoshidza","description":"Unity DOTS Sprite Rendering Package","archived":false,"fork":false,"pushed_at":"2024-10-20T16:40:08.000Z","size":177,"stargazers_count":538,"open_issues_count":1,"forks_count":42,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-11-11T18:41:13.898Z","etag":null,"topics":["2d","dots","ecs","entities","entity-component-system","package","performance","rendering","sprites","unity","unity-ecs","unity3d"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Antoshidza.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-03-05T16:05:26.000Z","updated_at":"2024-11-10T12:31:43.000Z","dependencies_parsed_at":"2024-04-16T19:37:30.052Z","dependency_job_id":"1d4e5323-d4a0-4769-a35e-8000fb685c19","html_url":"https://github.com/Antoshidza/NSprites","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Antoshidza%2FNSprites","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Antoshidza%2FNSprites/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Antoshidza%2FNSprites/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Antoshidza%2FNSprites/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Antoshidza","download_url":"https://codeload.github.com/Antoshidza/NSprites/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251455889,"owners_count":21592256,"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":["2d","dots","ecs","entities","entity-component-system","package","performance","rendering","sprites","unity","unity-ecs","unity3d"],"created_at":"2024-08-02T13:00:25.310Z","updated_at":"2025-04-29T07:32:07.517Z","avatar_url":"https://github.com/Antoshidza.png","language":"C#","readme":"# NSprites - Unity DOTS Sprite Rendering Package\nThis framework provides sprite rendering system compatible with Entities package (unity ECS). [Changelog](https://github.com/Antoshidza/NSprites/wiki/Changelog)\n\nBasically it sync whatever entity component you want with GPU data to perform instanced rendering. As a result all entities with same Material can be rendered with single drawcall.\n\n\u003cimg src=\"https://user-images.githubusercontent.com/19982288/203323912-3f0aec5a-543d-4145-bf8f-42e07af2d124.gif\" width=\"700\"/\u003e\n\n## Features\n* Using power of :boom:**DOTS**:boom: + instancing to render numerous of sprites\n* Using any public to you per-entity blittable component as shader instanced property\n* Data update strategies to avoid unnecessary CPU load\n* Edit-time rendering (subscene only)\n\n## Basic API\n**For more detailed information please read [project's wiki](https://github.com/Antoshidza/NSprites/wiki)** :blue_book:\n```csharp\n// registrate components as properties at assembly level anywhere in project\n[assembly: InstancedPropertyComponent(typeof(WorldPosition2D), \"_pos2D\")]\n[assembly: InstancedPropertyComponent(typeof(SpriteColor), \"_color\")]\n```\n```csharp\n// registrate render with ID, Material, capacity data and set of properties\nif (!SystemAPI.ManagedAPI.TryGetSingleton\u003cRenderArchetypeStorage\u003e(out var renderArchetypeStorage))\n    return;\n// don't registrate same renderID\nrenderArchetypeStorage.RegisterRender\n(\n    renderID,\n    material,   // material with [Enable GPU Instancing] enabled and shader supporting instancing\n    bounds      // bounds in which sprites will be visible. For example new Bounds(Vector3.zero, Vector3.one * float.MaxValue)\n    null,       // override for MaterialPropertyBlock if needed\n    128,        // initial ComputeBuffers capacity\n    128,        // minimal capacity step for ComputeBuffers\n    \"_pos2D\",   // world 2D position property\n    \"_color\"    // color property\n);\n```\n```csharp\n// initialize sprite entity with all needed components for rendering\nentityManager.AddSpriteRenderComponents(spriteEntity, renderID);\n// WorldPosition2D and SpriteColor are example client's components\nentityManager.AddComponentData(spriteEntity, new WorldPosition2D { Value = /*your value here*/ });          \nentityManager.AddComponentData(spriteEntity, new SpriteColor { Value = Color.White });\n\n// or from baker\nprivate class Baker : Baker\u003cSpriteAuthoring\u003e\n{\n    public override void Bake(SpriteAuthoring authoring)\n    {\n        AddComponent(new WorldPosition2D { Value = new float2(authoring.transform.position.x, authoring.transform.position.y) });\n        AddComponent(new SpriteColor { Value = Color.White });\n        this.AddSpriteComponents(authoring.RenderID); // Render ID is client defined unique per-render archetype int. You can define it manually or for example use Material's instance ID or whatever else.\n    }\n}\n```\nAlso shader you're using should be compatible with instancing. Check my [example shader gist](https://gist.github.com/Antoshidza/387bf4a3a3efd62c8ca4267e800ad3bc). The main idea is to use `StructuredBuffer\u003cT\u003e _propertyName`. Though it is possible to use instanced properties with ShaderGraph, so you may try your option. For local example shader main part can look like:\n```hlsl\n// ...\n#if defined(UNITY_PROCEDURAL_INSTANCING_ENABLED)\nStructuredBuffer\u003cint\u003e _propertyPointers;\nStructuredBuffer\u003cfloat4\u003e _color;\n#endif\n// ...\nVaryings UnlitVertex(Attributes attributes, uint instanceID : SV_InstanceID)\n{\n    // ...    \n#if defined(UNITY_PROCEDURAL_INSTANCING_ENABLED)\n    int propPointer = _propertyPointers[instanceID]; // this is internal package property to point right data during component sync\n    float4 color = _color[propPointer];\n#else\n    //fallback if somehow instancing failed\n    float4 color = float4(1,1,1,1);\n#endif\n    // ...\n}\n```\n\n## How it works\n[`SpriteRenderingSystem`](https://github.com/Antoshidza/NSprites/blob/main/Rendering/Systems/SpriteRenderingSystem.cs) sync registered entity components with [ComputeBuffers](https://docs.unity3d.com/ScriptReference/ComputeBuffer.html) to send data to GPU and then renders entities with [`Graphics.DrawMeshInstancedProcedural`](https://docs.unity3d.com/ScriptReference/Graphics.DrawMeshInstancedProcedural.html). System also controls how ComputeBuffers reallocates if capacity exceeds. Sprites are simple entities with no limits of what components you use.\n\n## Check [Foundation](https://github.com/Antoshidza/NSprites-Foundation)\nNSprites doesn't provide anything except rendering and managing data for it. Though you can implement anything you want on top of it. Also I want to share some foundation project where you can find examples and maybe even useful tools to work with this package. Foundation provides such things as sorting / culling / animation / 2D transforms / basic data authoring and registration.\n\n## Check sample project - [Age of Sprites](https://github.com/Antoshidza/Age-of-Sprites)\nThis sample project covers basics of rendering with NSprites. Use it to get a main idea of how stuff can be implemented but not as production-ready solutions.\n\n![RomeGIf](https://user-images.githubusercontent.com/19982288/204523105-7cabb122-954c-4fb0-97bc-becb27d2d2b9.gif)\n\n## Games created with NSprites\n### [Reconquista](https://store.steampowered.com/app/3222680/Reconquista/?beta=0)\n\u003cimg src=\"https://github.com/user-attachments/assets/d104eb90-e031-4b4a-abcc-637d157da757\" width=\"48%\"/\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/e4b2bfdb-a8b9-490a-899f-2dedbac91bbe\" width=\"48%\"/\u003e\n\n## Installation\n### Requirements\n* Unity 2022.2+\n* Entities v1.0.0-pre.65+\n\n### [Compatibility](https://github.com/Antoshidza/NSprites/wiki/Compatibility)\nThere is few things we should care when talking about using NSprites in real projects. Since this package uses **GPU instancing**\nand `ComputeBuffer` on CPU side with `StructuredBuffer\u003cT\u003e` on GPU side (in shader) to send sprites data, we need platform and Graphics API support\nthis two.\n\n| **Graphics API**                     | **Description**                                             |\n|:-------------------------------------|:------------------------------------------------------------|\n| Direct3D11                           | :warning: partially supported                               |\n| Direct3D12                           | :white_check_mark: supported                                |\n| Vulkan                               | :white_check_mark: supported                                |\n| OpenGLCore                           | :warning: partially supported                               |\n| OpenGLES3                            | :warning: partially supported |\n\n| **Platform** | **Description**                                             |\n|:-------------|:------------------------------------------------------------|\n| PC           | :white_check_mark: supported                                |\n| WebGL        | :no_entry: unsupported                                      |\n| Android      | :grey_question: not fully checked                           |\n| iOS          | :question: not checked                                      |\n\n### [Install via Package Manager](https://docs.unity3d.com/2021.3/Documentation/Manual/upm-ui-giturl.html)\n* Window -\u003e Package Manager -\u003e + button -\u003e Add package from git url\n* Paste `https://github.com/Antoshidza/NSprites.git`\n### Install via git submodule\n* `cd` to your project's `/Packages` folder\n* git submodule https://github.com/Antoshidza/NSprites.git\n\n## Support :+1: Contribute :computer: Contact :speech_balloon:\nI wish this project will be helpful for any ECS early adopters! So feel free to send bug reports / pull requests, start discussions / critique, those all are **highly** appreciated!\nYou can contact with my [discord account](https://www.discordapp.com/users/219868910223228929) / join [discord server](https://discord.gg/rvxrHEFx8n)!\nAlso there is a [thread](https://forum.unity.com/threads/1-0-3-nsprites-sprite-rendering-package.1367463/) on unity dots forum!\n\nPreferred way to send support: [BOOSTY](https://boosty.to/tonymax/donate)\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/antoshidzamax)\n","funding_links":["https://www.buymeacoffee.com/antoshidzamax"],"categories":["Game-Design-Tool","Open Source Repositories"],"sub_categories":["DOTS"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAntoshidza%2FNSprites","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAntoshidza%2FNSprites","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAntoshidza%2FNSprites/lists"}