{"id":16209935,"url":"https://github.com/annulusgames/scenesystem","last_synced_at":"2026-03-06T16:33:54.086Z","repository":{"id":179791222,"uuid":"664108933","full_name":"annulusgames/SceneSystem","owner":"annulusgames","description":"Provides efficient and versatile scene management functionality for Unity","archived":false,"fork":false,"pushed_at":"2023-07-24T02:47:57.000Z","size":336,"stargazers_count":116,"open_issues_count":0,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-30T11:50:21.934Z","etag":null,"topics":["scene","unity"],"latest_commit_sha":null,"homepage":"","language":"C#","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/annulusgames.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":"2023-07-09T00:00:55.000Z","updated_at":"2025-06-26T09:13:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"d4c7a042-6975-4b49-b90a-712844bda0d3","html_url":"https://github.com/annulusgames/SceneSystem","commit_stats":null,"previous_names":["annulusgames/scenesystem","yn01dev/scenesystem","yn01-dev/scenesystem","nuskey8/scenesystem"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/annulusgames/SceneSystem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FSceneSystem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FSceneSystem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FSceneSystem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FSceneSystem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/annulusgames","download_url":"https://codeload.github.com/annulusgames/SceneSystem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FSceneSystem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30185529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T14:42:24.748Z","status":"ssl_error","status_checked_at":"2026-03-06T14:42:14.925Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["scene","unity"],"created_at":"2024-10-10T10:34:16.742Z","updated_at":"2026-03-06T16:33:49.075Z","avatar_url":"https://github.com/annulusgames.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Scene System\n Provides efficient and versatile scene management functionality for Unity.\n\n\u003cimg src=\"https://github.com/AnnulusGames/SceneSystem/blob/main/Assets/SceneSystem/Documentation~/Header.png\" width=\"800\"\u003e\n\n[![license](https://img.shields.io/badge/LICENSE-MIT-green.svg)](LICENSE)\n\n[日本語版READMEはこちら](README_JP.md)\n\n## Overview\nScene System is a library that provides functions related to scene management in Unity.\nThis library includes an API for loading scenes and a function that enables scene settings on the editor.\n\n### Features\n* API for multi-functional scene management that extends SceneManager\n* Add SceneReference that can set scene reference on Inspector\n* LoadingScreen component for easy implementation of loading screens\n* SceneContainer for efficient multi-scene management\n* Supports coroutines and async/await\n* Support UniRx/UniTask\n\n## Setup\n\n### Requirement\n* Unity 2019.4 or higher\n\n### Install\n1. Open the Package Manager from Window \u003e Package Manager\n2. \"+\" button \u003e Add package from git URL\n3. Enter the following to install\n   * https://github.com/AnnulusGames/SceneSystem.git?path=/Assets/SceneSystem\n\n\nor open Packages/manifest.json and add the following to the dependencies block.\n\n```json\n{\n    \"dependencies\": {\n        \"com.annulusgames.scene-system\": \"https://github.com/AnnulusGames/SceneSystem.git?path=/Assets/SceneSystem\"\n    }\n}\n```\n\n### Namespace\nWhen using Scene System, add the following line at the beginning of the file.\n\n```cs\nusing AnnulusGames.SceneSystem;\n```\n\n## Scenes\nScene System provides Scenes class as an alternative to Unity's SceneManager.\nScenes class is implemented as a wrapper class for SceneManager and provides richer functionality than a normal SceneManager.\n\nTo load/unload a scene, write as follows.\n\n``` cs\nusing UnityEngine;\nusing UnityEngine.SceneManagement;\nusing AnnulusGames.SceneSystem;\n\nvoid Example()\n{\n    // load the scene with BuildSettings Index\n    Scenes.LoadSceneAsync(0);\n    // load scene by scene name\n    Scenes.LoadSceneAsync(\"SceneName\", LoadSceneMode.Additive);\n    // synchronous loading is also possible\n    Scenes.LoadScene(0);\n\n    // unload the scene at Index of BuildSettings\n    Scenes.UnloadSceneAsync(0);\n    // unload scene by scene name\n    Scenes.UnloadSceneAsync(\"SceneName\");\n    // synchronous unloading is also possible\n    Scenes.UnloadScene(0);\n}\n```\n\nIt is also possible to load/unload multiple scenes simultaneously.\n\n``` cs\n// load multiple scenes simultaneously (LoadSceneMode is Addictive only)\nScenes.LoadScenesAsync(\"Scene1\", \"Scene2\", \"Scene3\");\n\n// unload multiple scenes simultaneously\nScenes.UnloadScenesAsync(\"Scene1\", \"Scene2\");\n```\n\nFor LoadScenesAsync only, you can set the behavior of loading multiple scenes by setting LoadMultiSceneMode.\n\n``` cs\n// load multiple scenes simultaneously\nScenes.LoadScenesAsync(LoadMultiSceneMode.Parallel, \"Scene1\", \"Scene2\", \"Scene3\");\n\n// load multiple scenes one by one\nScenes.LoadScenesAsync(LoadMultiSceneMode.Sequential, \"Scene1\", \"Scene2\");\n```\n\n### Events\nAs with a normal SceneManager, it is possible to acquire timings such as scene loading with events.\n\n``` cs\nScenes.onSceneLoaded += (scene, loadSceneMode) =\u003e\n{\n    Debug.Log(scene.name + \" loaded\");\n};\n\nScenes.onSceneUnLoaded += scene =\u003e\n{\n    Debug.Log(scene.name + \" unloaded\");\n};\n\nScenes.onActiveSceneChanged += (current, next) =\u003e\n{\n    Debug.Log($\"active scene changed from {current.name} to {next.name}\");\n};\n```\n\nAlso, by passing a class that implements ILoadSceneCallbackReceiver, it is possible to process these events collectively.\n\n``` cs\nusing UnityEngine;\nusing UnityEngine.SceneManagement;\nusing AnnulusGames.SceneSystem;\n\npublic class Example : MonoBehaviour, ILoadSceneCallbackReceiver\n{\n    void Start()\n    {\n        Scenes.AddCallbackReceiver(this);\n    }\n\n    void ILoadSceneCallbackReceiver.OnActiveSceneChanged(Scene current, Scene next)\n    {\n        Debug.Log($\"active scene changed from {current.name} to {next.name}\");\n    }\n\n    void ILoadSceneCallbackReceiver.OnLoad(Scene scene, LoadSceneMode loadSceneMode)\n    {\n        Debug.Log(scene.name + \"loaded\");\n    }\n\n    void ILoadSceneCallbackReceiver.OnUnload(Scene scene)\n    {\n        Debug.Log(scene.name + \"unloaded\");\n    }\n}\n```\n\n## SceneReference\nBy using SceneReference, it becomes possible to edit Scene assets on the Inspector.\n\n``` cs\nusing UnityEngine;\nusing AnnulusGames.SceneSystem;\n\npublic class SceneReferenceExample : MonoBehaviour\n{\n    public SceneReference sceneReference;\n\n    void Load()\n    {\n        // can be used as an argument for LoadScene\n        Scenes.LoadScene(sceneReference);\n\n        // get scene asset file path from assetPath\n        Debug.Log(sceneReference.assetPath);\n    }\n}\n```\n\n\u003cimg src=\"https://github.com/AnnulusGames/SceneSystem/blob/main/Assets/SceneSystem/Documentation~/img1.png\" width=\"420\"\u003e\n\n## LoadSceneOperationHandle\nAll asynchronous methods in the Scene System have a structure called LoadSceneOperationHandle as a return value.\nBy using LoadSceneOperationHandle, it is possible to wait for transitions, enable scenes, etc.\n\n### Wait for the process to complete\nUse onCompleted to wait for the completion of processing in a callback.\n\n``` cs\nvar handle = Scenes.LoadSceneAsync(\"SceneName\");\nhandle.onCompleted += () =\u003e\n{\n     Debug.Log(\"completed\");\n};\n```\n\nTo wait in a coroutine, use the ToYieldInteraction method.\n\n``` cs\nvar handle = Scenes.LoadSceneAsync(\"SceneName\");\nyield return handle.ToYieldInteraction();\n```\n\nTo wait with async/await, use the ToTask method.\n\n``` cs\nvar handle = Scenes.LoadSceneAsync(\"SceneName\");\nawait handle.ToTask();\n```\n\n### Get Progress\nIt is also possible to get the progress from the LoadSceneOperationHandle.\n\n``` cs\nvar handle = Scenes.LoadSceneAsync(\"SceneName\");\n\n// get the progress as a float between 0 and 1\nvar progress = handle.Progress;\n\n// get if completed\nvar isDone = handle.IsDone;\n```\n\n### Activate Scene\nBy using the AllowSceneActivation method, it is possible to adjust the timing of scene loading completion.\nHere is an example of using AllowSceneActivation inside a coroutine.\n\n``` cs\nvar handle = Scenes.LoadSceneAsync(\"SceneName\");\n\n// set allowSceneActivation to false\nhandle.AllowSceneActivation(false);\n\n// wait until progress reaches 0.9 (loading is complete)\nyield return new WaitWhile(() =\u003e handle.Progress \u003c 0.9f);\n\n// set allowSceneActivation to true\nhandle.AllowSceneActivation(true);\n\n// wait until the scene is activated\nyield return handle.ToYieldInteraction();\n```\n\nRegarding the behavior of Progress and IsDone values when AllowSceneActivation is set to false, it conforms to Unity's allowSceneActivation.\nhttps://docs.unity3d.com/2019.4/Documentation/ScriptReference/AsyncOperation-allowSceneActivation.html\n\n## Loading Screen\nScene System provides the LoadingScreen component as a function to display the loading screen.\n\n\u003cimg src=\"https://github.com/AnnulusGames/SceneSystem/blob/main/Assets/SceneSystem/Documentation~/img2.png\" width=\"500\"\u003e\n\nYou can create your own loading screen by customizing the LoadingScreen component.\n\n### Settings\n#### Skip Mode\nSet the behavior when loading is completed.\n\n| SkipMode         | Behavior                                                                    |\n| ---------------- | --------------------------------------------------------------------------- |\n| Instant Complete | Activates the next scene immediately after loading completes.               |\n| Any Key          | Activates the next scene when any key is pressed after loading is complete. |\n| Manual           | After loading is complete, manually activate the next scene from Script.    |\n\nIf set to Manual, the next scene can be enabled by calling AllowCompletion().\n\n``` cs\nLoadingScreen loadingScreen;\nloadingScreen.AllowCompletion();\n```\n\n#### Minimum Loading Time\nSet the minimum amount of time it takes to load.\nEven if the loading of the scene is completed, it is possible to pretend that the loading is being performed for the set time.\n\n#### Destroy On Completed\nIf set to true, automatically remove the object after the scene transition is complete.\n\n#### On Loading\nCalled every frame while the scene is loading.\n\n#### On Load Completed\nCalled when the scene has finished loading. The scene is not activated at this point.\n\n#### On Completed\nCalled when the scene is activated.\n\n### Loading Screen Implementation\nTo use the loading screen created with LoadingScreen component, use the WithLoadingScreen method. This method is defined as an extension method of LoadSceneOperationHandle and can be used for any asynchronous method of the Scene System.\n\n``` cs\nusing UnityEngine;\nusing AnnulusGames.SceneSystem;\n\npublic sealed class LoadingScreenSample : MonoBehaviour\n{\n     public LoadingScreen loadingScreenPrefab;\n\n     public void Load()\n     {\n         // generate a prefab for the loading screen and set it to DontDestroyOnLoad\n         var loadingScreen = Instantiate(loadingScreenPrefab);\n         Don't DestroyOnLoad(loadingScreen);\n\n         // pass the loadingScreen generated by WithLoadingScreen\n         Scenes.LoadSceneAsync(\"SceneName\")\n             .WithLoadingScreen(loadingScreen);\n     }\n}\n```\n\nNote: Do not call AllowSceneActivation on a LoadSceneOperationHandle that has a LoadingScreen set. Since it manipulates allowSceneActivation on the LoadingScreen side, it may cause unexpected behavior.\n\n### Extend LoadingScreen\nIt is also possible to create your own class by inheriting from LoadingScreen.\n\n``` cs\nusing UnityEngine;\nusing AnnulusGames.SceneSystem;\n\npublic class CustomLoadingScreen : LoadingScreen\n{\n    public override void OnCompleted()\n    {\n        Debug.Log(\"completed\");\n    }\n\n    public override void OnLoadCompleted()\n    {\n        Debug.Log(\"load completed\");\n    }\n\n    public override void OnLoading(float progress)\n    {\n        Debug.Log(\"loading...\");\n    }\n}\n```\n\n### Sample\nA loading screen implementation sample using LoadingScreen is available and can be installed from Package Manager/Samples.\nPlease refer to it when you actually create a loading screen.\n\n\u003cimg src=\"https://github.com/AnnulusGames/SceneSystem/blob/main/Assets/SceneSystem/Documentation~/img3.png\" width=\"500\"\u003e\n\n## SceneContainer\nWhen adopting a project structure that uses multiple scenes in Unity, it is necessary to implement the transition of multiple scenes in some way. Scene System provides the SceneContainer class as a function for performing such complex scene transitions.\n\n### Create a container\nWhen using SceneContainer, first create a new container with SceneContainer.Create().\n\n``` cs\n// create a new container\nvar container = SceneContainer.Create();\n```\n\nRegister a scene to be loaded/unloaded at runtime with the Register method.\n\n``` cs\n// pass the key associated with the scene to the first argument, and the scene name and scene buildIndex to the second argument\ncontainer.Register(\"Page1\", \"Sample1A\");\ncontainer.Register(\"Page1\", \"Sample1B\");\n\ncontainer.Register(\"Page2\", \"Sample2\");\n```\n\nRegister a scene that exists permanently at runtime with the RegisterPermanent method.\n\n``` cs\n// pass the scene name and scene buildIndex as arguments\ncontainer.RegisterPermanent(\"Permanent1\");\ncontainer.RegisterPermanent(\"Permanent2\");\n```\n\nFinally call the Build method. Calling this method will enable the container and load the scene registered with RegisterPermanent at the same time.\nThis process is asynchronous and can be waited for in the same way as a normal scene load.\n\n``` cs\n// build the container\nvar handle = container.Build();\n\n// wait for completion\nyield return handle.ToYieldInteraction();\n```\n\n### Scene transition using containers\nUse the Push method to perform scene transitions with SceneContainer.\nThe history of scenes is stacked, and it is possible to return to the previous scene by calling the Pop method.\n\n``` cs\n// transition to the scene associated with the registered key\nvar handle = container.Push(\"Page1\");\nyield return handle.ToYieldInteraction();\n\n// return to previous scene\nhandle = container.Pop();\nyield return handle.ToYieldInteraction();\n```\n\nBy calling the ClearStack method, you can reset the history and unload any scenes you have loaded with push.\n\n``` cs\nvar handle = container.ClearStack();\n```\n\nYou can also call Release to destroy the container and unload all scenes, including persistent scenes.\n``` cs\nvar handle = container.Release();\n```\n\n## Scene System + UniRx\nBy introducing UniRx, it becomes possible to observable events related to scene loading.\n\nTo get scene loading/unloading events and active scene switching events as IObservable, write as follows.\n\n``` cs\nusing AnnulusGames.SceneSystem;\nusing UniRx;\n\nvoid Example()\n{\n    Scenes.OnSceneLoadedAsObservable().Subscribe(x =\u003e\n    {\n        var scene = x.scene;\n        var loadSceneMode = x.loadSceneMode;\n\n        Debug.Log(\"scene loaded\");\n    });\n\n    Scenes.OnSceneUnloadedAsObservable().Subscribe(scene =\u003e\n    {\n        Debug.Log(\"scene unloaded\");\n    });\n\n    Scenes.OnActiveSceneChangedAsObservable().Subscribe(x =\u003e\n    {\n        var current = x.current;\n        var next = x.next;\n\n        Debug.Log(\"active scene changed\");\n    });\n}\n```\n\nIt is also possible to get SceneContainer events as IObservable.\n\n``` cs\nSceneContainer container;\n\nvoid Example()\n{\n    container.OnBeforePushAsObservable().Subscribe(x =\u003e\n    {\n        Debug.Log(\"Current: \" + x.current + \" Next: \" + x.next);\n    });\n\n    container.OnAfterPushAsObservable().Subscribe(x =\u003e\n    {\n        Debug.Log(\"Current: \" + x.current + \" Next: \" + x.next);\n    });\n\n    container.OnBeforePopAsObservable().Subscribe(x =\u003e\n    {\n        Debug.Log(\"Current: \" + x.current + \" Next: \" + x.next);\n    });\n\n    container.OnAfterPopAsObservable().Subscribe(x =\u003e\n    {\n        Debug.Log(\"Current: \" + x.current + \" Next: \" + x.next);\n    });\n}\n```\n\n## Scene System + UniTask\nBy introducing UniTask, it becomes possible to wait for LoadSceneOperationHandle with UniTask.\n\nUse ToUniTask to convert the LoadSceneOperationHandle to a UniTask.\n\n``` cs\nusing AnnulusGames.SceneSystem;\nusing Cysharp.Threading.Tasks;\n\nasync UniTaskVoid ExampleAsync()\n{\n    await Scenes.LoadAsync(\"SceneName\").ToUniTask();\n}\n```\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannulusgames%2Fscenesystem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fannulusgames%2Fscenesystem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannulusgames%2Fscenesystem/lists"}