{"id":18773496,"url":"https://github.com/errorstream/prebut","last_synced_at":"2025-12-13T22:30:13.998Z","repository":{"id":229623009,"uuid":"773633398","full_name":"errorStream/Prebut","owner":"errorStream","description":"A suite of tools for making pre-rendered backgrounds in blender for use in unity.","archived":false,"fork":false,"pushed_at":"2024-04-17T19:53:16.000Z","size":26912,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-29T08:33:38.315Z","etag":null,"topics":["blender","rendering","retro","unity"],"latest_commit_sha":null,"homepage":"https://errorstream.itch.io/prebut-demo","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/errorStream.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2024-03-18T05:42:41.000Z","updated_at":"2024-04-16T19:17:41.000Z","dependencies_parsed_at":"2024-04-17T20:59:42.707Z","dependency_job_id":"f7b75072-8164-471f-b5cf-df4ff9e0dc69","html_url":"https://github.com/errorStream/Prebut","commit_stats":null,"previous_names":["errorstream/prebut"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errorStream%2FPrebut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errorStream%2FPrebut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errorStream%2FPrebut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errorStream%2FPrebut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/errorStream","download_url":"https://codeload.github.com/errorStream/Prebut/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239680982,"owners_count":19679509,"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":["blender","rendering","retro","unity"],"created_at":"2024-11-07T19:34:14.399Z","updated_at":"2025-12-13T22:30:13.915Z","avatar_url":"https://github.com/errorStream.png","language":"C#","readme":"\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ch3 align=\"center\"\u003ePrebut\u003c/h3\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cb\u003e\u003ci\u003ePre\u003c/i\u003e\u003c/b\u003e-rendered \u003cb\u003e\u003ci\u003eB\u003c/i\u003e\u003c/b\u003eackground \u003cb\u003e\u003ci\u003eUt\u003c/i\u003e\u003c/b\u003eilities\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    A suite of tools for making pre-rendered backgrounds in blender for use in unity.\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://errorstream.itch.io/prebut-demo\"\u003e\u003cb\u003eView Demo »\u003c/b\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/errorStream/prebut/releases\"\u003eDownload\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/errorStream/prebut/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/errorStream/prebut/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#whats-inside\"\u003eWhat's inside?\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#who-is-this-for\"\u003eWho is this for?\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e \u003ca href=\"#dependencies\"\u003eDependencies\u003c/a\u003e \u003c/li\u003e\n        \u003cli\u003e\n          \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\n          \u003cul\u003e\u003cli\u003e\u003ca href=\"#blender-add-on\"\u003eBlender Add-on\u003c/a\u003e\u003c/li\u003e\u003c/ul\u003e\n          \u003cul\u003e\u003cli\u003e\u003ca href=\"#unity-package\"\u003eUnity Package\u003c/a\u003e\u003c/li\u003e\u003c/ul\u003e\n        \u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\n          \u003ca href=\"#extra-functionality\"\u003eExtra Functionality\u003c/a\u003e\n          \u003cul\u003e\u003cli\u003e\u003ca href=\"#custom-clear\"\u003eCustom Clear\u003c/a\u003e\u003c/li\u003e\u003c/ul\u003e\n          \u003cul\u003e\u003cli\u003e\u003ca href=\"#orthographic-camera-center-controller\"\u003eOrthographic Camera Center Controller\u003c/a\u003e\u003c/li\u003e\u003c/ul\u003e\n        \u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgments\"\u003eAcknowledgments\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\n![An example scene generated with prebut](Images/zoomed-out.png)\n\nPrebut is a project to demonstrate a workflow for generation and usage\nof pre-rendered backgrounds in unity. This workflow allows the\ncreation visually sophisticated scenes in blender which require a\nnon-realtime rendering approach and allow objects in unity to interact\nwith in realtime.\n\n![Another game which uses this approach](Images/dennis-scrolling-demo.gif)\n\nI'm making this project because I want to explore the artistic avenues\nand technical considerations of pre-rendered backgrounds. I admire the\nstylistic refinement, compositional intentionality, and fullness of\ndetail of PS1 era pre-rendered backgrounds. These seem to be\nconsiderations which have lost emphasis in games since the hardware\nlimitation based motivation for the usage of pre-rendered backgrounds\nwas alleviated, so I decided to explore the potential of this\napproach, while evoking a similar style, using modern tooling, through\nthis project.\n\nThis project works by exporting depth information from your scene in\nblender and using that to specify the depth value in unity, which\nallows objects in unity to move around pre-rendered objects. You can\nthen export simplified colliders from blender to allow accurate\ncollisions with pre-rendered objects.\n\nThis project supports both perspective and orthographic cameras,\nincluding the ability to effectively pan around orthographic\nscenes. My goal with this project was to make it quite flexible and\nminimally interfere with your workflow.\n\n### What's inside?\n\nThis project is composed of three parts; a blender add-on, a unity\npackage, and an explanation of how to use them together.\n\nThe blender add-on provides a panel for exporting data about the\ncurrent scene and for generating a compositor node for feeding\nrendered image data into.\n\nThe Unity package provides a component which takes in the data and\ntextures generated by blender and constructs a pre-rendered background\nsetup in the scene.\n\n### Who is this for?\n\nThis project is for people who are interested in experimenting with\npre-rendered backgrounds in their development projects, but have\nstruggled with getting a working configuration or are looking for a\nsmoother workflow. It is also useful for devs who specialize in 3d\nvisual assets and are looking for unique ways to apply these\ntechniques for their games. This approach is especially useful for\ngames with fixed camera angles (survival horror, point and click\nadventure, visual novel), games with a retro aesthetic, or games with\nan isometric view (grid-based strategy, top down adventure, tower\ndefense, RPG)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Getting Started\n\n### Dependencies\n\n*Note that this project may work on earlier versions of Blender and Unity, these are just the earliest versions I have tested*\n\n- Unity 2020.3 or later\n  - Default render pipeline\n  - 16 bit per channel texture support\n    - Support for this in webgl builds was added later; in 2021.1\n- Blender 4.0.0 or later\n\n\n### Installation\n\n#### Blender Add-on\n\n1. Open Blender Preferences\n2. Click \"Addons\" on the left panel\n2. Click \"Install\"\n3. Navigate to `prebut.py` (under `BlenderAddon` if you cloned the repo, named `prebut-blender-addon-vx.x.x.py` if you got it from releases) and click \"Install Add-On\"\n4. Click the checkbox next to \"Render: Prebut\"\n5. (Optional) Click the hamburger menu in the bottom left and click\n   \"Save Preferences\". This ensures that the add-on will be enabled on\n   subsequent restarts.\n\n#### Unity Package\n\n1. Set up a unity project. Note that this has only been tested with the\n   default render pipeline.\n2. Open the Unity \"Package Manager\" window\n3. Click the plus in the top right\n4. Add the package\n   - If you cloned the repo\n     1. Click \"Add package from disk\"\n     2. Navigate to the Prebut root directory and select the \"package.json\" file\n   - If you downloaded from releases\n     1. Click \"Add Package from Tarball\"\n     2. Navigate to and select the \"prebut-unity-package-vx.x.x.tgz\" file\n   - If you want to install directly from a git url\n     1. Click \"Add Package from git URL\"\n     2. Paste in a git url. This is available from the Code dropdown\n        in the top right. In this case it would be\n        https://github.com/errorStream/Prebut.git\n     3. Click \"Add\"\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\nNote that this workflow is quite explicit to make sure it works the\nfirst time, feel free to vary it up once you understand what is going\non.\n\n1. Make the blender assets\n    1. Build a scene in blender. \n    2. Open the Prebut panel in the 3D viewport or the node editor\n    3. Click \"Enable Depth Layer\" to enable rendering the depth pass (this\n       is not needed if this pass is already enabled)\n    4. Configure a directory to save the generated assets to in \"Export Directory\"\n    5. Click \"Export Data\" (This saves relevant data about your scene to\n       your export directory. Click this again if you change camera\n       settings)\n    6. Click \"Configure Export Node\" (The add-on should henceforth send\n       all relevant configurations to this node on render, but you can\n       always click it manually to update the node)\n    7. In the compositing node editor, connect `Render Layers/Image` to\n       `Prebut Texture Export/Image` and `Render Layers/Depth` to `Prebut\n       Texture Export/Depth`. You can add any compositing nodes you want\n       between `Render Layers/Image` and `Prebut Texture Export/Image` to\n       change the look.\n    8. (Optional) Toggle `Properties \u003e Render \u003e Film \u003e Transparent` on\n       to have color texture terminate at edge of visible content for\n       specifying a clear color in Unity.\n    9. Render image. (Make sure you are on a consistent frame,\n       otherwise it will change the outputted files name.)\n    10. Export simplified version of the scene for use in unity. \n       1. Move camera and main lights to a separate collection if they\n          aren't already, henceforth called \"Shared\"\n       2. Make a collection with simplified meshes which will act as the\n          colliders for the detailed objects you have in your scene,\n          henceforth called \"Colliders\"\n       3. Make it so only Shared and Colliders are Visible\n       4. Click `File \u003e Export \u003e FBX`\n       5. Toggle on `Include \u003e Limit to \u003e Visible Objects`\n       6. Navigate to Export Directory\n       7. Click \"Export FBX\"\n2. Make the Unity scene\n   1. Move the generated files into Unity\n   2. Apply presets to pre-rendered color and depth textures\n       1. Select pre-rendered color texture\n       2. Click the preset button in the top right of the inspector\n          - If your color texture has alpha set \"Alpha Source\" to\n            \"Input Texture Alpha\" and \"Alpha is Transparency\" to True\n       3. Click \"PreRenderedColorTexture\"\n       4. Do the same with the pre-rendered depth texture and \"PreRenderedDepthTexture\"\n   3. Add the setup component to the scene\n      1. Make a root game object named \"Setup\"\n      2. Add the component `Prebut/Setup Pre-Rendered Background`\n      3. Set the scene field to the prefab for the exported FBX file to \"Scene\"\n      4. Set the exported color texture, depth texture, and extra data to the corresponding fields\n      5. Set a background layer (This should be a layer which is not seen by any other cameras)\n      6. If your scene is orthographic you can check \"Add Orthographic\n         Camera Center Controller\" to allow panning around your scene.\n      7. Set a background color, which is what content outside the\n         visible part of the color texture gets cleared to.\n      8. Click \"Setup\"\n          - The other setting can be left default for now\n          - When you make a change to any of the referenced data,\n            click \"Setup\" again to update the configuration\n            \nThat should be all you need to do. Hit play then you can move a 3D\nobject around the scene to see it interact with the pre-rendered\nparts. Select \"Setup\" to see colliders to get an idea of where\neverything is.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Extra Functionality\n\nThese are chunks of functionality which are not strictly necessary for\nthe core goal of the system, but they are generally useful enough\nwhen it comes to this approach that I deem it prudent to include them.\n\n#### Custom Clear\n\nThis piece of functionality gives the ability to clear the background\nwith a scrolling repeating pattern. This is a common stylistic tool\nused for this approach historically, so I decided to give it official\nsupport. This effect is demonstrated in [the\ndemo](https://errorstream.itch.io/prebut-demo).\n\n![Animation showing the effect](Images/prebut-demo-scroll-bg.gif)\n\nOnce you have a scene with `Prebut/Setup Pre-Rendered Background` component\nin it, follow these steps to add custom clearing.\n\n1. Add a game object called \"BackgroundClear\"\n2. Add the component `Prebut/Background Clear`. All settings are\n   optional.\n3. Add the game object to a layer which only contains this object and\n   is not seen by any cameras. Henceforth, called the \"Clear Layer\"\n4. In the `Prebut/Setup Pre-Rendered Background` component toggle\n   \"Should Clear Colors\" to False and add the clear layer to hidden\n   layers, then click \"Setup\"\n\nThis component should print warnings on play if there are settings in\nthe current scene which interfere with it, but that should be enough\nto work.\n\n#### Orthographic Camera Center Controller\n\nA common approach with this technique when using an orthographic\ncamera is zooming in on and panning around a large pre-rendered\nscene. It is not trivial to keep the depth and color camera and 3D\nscene camera in sync, so to facilitate this; this project has the\n\"Orthographic Camera Center Controller\" component. This is generated\nautomatically by the `Prebut/Setup Pre-Rendered Background` component\nif the pre-rendered scene was generated with an orthographic camera\nand \"Add Orthographic Camera Center Controller\" is checked.\n\nThe usage is simple. Set Center to the position in world space which\nyou want the view to center on. Set Zoom to the zoom level you\nwant. The camera will automatically move to the appropriate location\nto center that point and adjust its zoom level.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- ROADMAP --\u003e\n## Roadmap\n\n- [x] Perspective Backgrounds\n- [x] Orthographic Backgrounds\n- [x] Orthographic Panning\n- [x] Scrolling Clear\n- [ ] Lower Minimum Version\n- [ ] Panning across multiple background textures\n- [ ] Pre-rendered midground and foreground entities\n\nSee the [open issues](https://github.com/errorStream/Prebut/issues)\nfor a full list of proposed features (and known issues).\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nIf you have a suggestion that would make this better, please fork the\nrepo and create a pull request. You can also simply open an issue with\nthe tag \"enhancement\".\n\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the MIT License. See `LICENSE.txt` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nErrorStream - [itch.io profile](https://errorstream.itch.io) - errorstream@amequus.com\n\nProject Link: [https://github.com/errorStream/prebut](https://github.com/errorStream/prebut)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Acknowledgments\n\n- [Pre-Rendered Backgrounds\n  Aesthetics](https://twitter.com/prbg_aesthetics) for aggregating so\n  many examples of this medium, and inspiring me to understand it.\n- [SpookyFM/DepthCompositing: Depth Compositing Demo in Unity and\n  Blender](https://github.com/SpookyFM/DepthCompositing/) for giving\n  me some starting intuitions for understanding this approach.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferrorstream%2Fprebut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferrorstream%2Fprebut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferrorstream%2Fprebut/lists"}