{"id":19989619,"url":"https://github.com/wavesoft/three-bundles","last_synced_at":"2025-08-24T19:07:30.665Z","repository":{"id":142484017,"uuid":"44904774","full_name":"wavesoft/three-bundles","owner":"wavesoft","description":"THREE Bundles is a set of Require.js plugins that help you bundle and ship THREE.js resources.","archived":false,"fork":false,"pushed_at":"2015-12-01T23:32:14.000Z","size":9632,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-01T20:02:12.532Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wavesoft.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":"2015-10-25T10:07:55.000Z","updated_at":"2015-10-25T10:18:29.000Z","dependencies_parsed_at":"2023-03-13T22:30:16.825Z","dependency_job_id":null,"html_url":"https://github.com/wavesoft/three-bundles","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoft%2Fthree-bundles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoft%2Fthree-bundles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoft%2Fthree-bundles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoft%2Fthree-bundles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wavesoft","download_url":"https://codeload.github.com/wavesoft/three-bundles/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241430321,"owners_count":19961635,"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":[],"created_at":"2024-11-13T04:48:44.910Z","updated_at":"2025-03-01T21:50:10.101Z","avatar_url":"https://github.com/wavesoft.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# THREE Bundles\n\n\u003cimg src=\"https://github.com/wavesoft/three-bundles/raw/master/doc/icon.png\" align=\"left\" alt=\"THREE Bundles\" /\u003e\n\nTHREE Bundles is a [Require.js](http://requirejs.org/) package that provides dynamic content loading for various [THREE.js](http://threejs.org/) resources. It offers a simple mechanism for addressing and loading them through Require.js as native dependencies.\n\nIn addition it suggests a way of organizing your resources in reusable `bundles` that can be quickly and optimally loaded in your scene.\n\n[Example](https://cdn.rawgit.com/wavesoft/three-bundles/f3348a0ae6d8c2a6fed3c444cd1ecec1ba49f750/examples/hello_world.html)\n\n__Note: Be aware that this is an in-development, early preview version, with many advanced THREE.js loader features missing.__\n\n## Requirements\n\n * __Require.js__\n * __THREE.js__ (aliased `three` in require.js)\n * __text.js__ (from https://github.com/requirejs/text)\n\n## Installing \n\nYou can include THREE Bundles to your Require.js project with the following configuration:\n\n```javascript\nrequire.config({\n\n    /**\n     * (1) Add three-bundles as a package\n     */\n    packages: [\n        {\n            'name'      : 'three-bundles',\n            'location'  : 'path/to/your/three-bundles/js'\n        }\n    ],\n\n    /**\n     * (2) Configure three-bundles\n     */\n    threeBundles: {\n        /**\n         * Specify the base Url (relative to requireJS' `baseUrl`),\n         * that threeBundles will use for loading the bundles.\n         *\n         * If missing, it will default to requireJS' `baseUrl`\n         */\n        'baseUrl': '../bundles'\n    },\n\n    /**\n     * (3) (Optionally) Make sure THREE.js is accessible under the name 'three'\n     */\n    paths: {\n        'three': 'path/to/three.js'\n    }\n\n})\n```\n\n__IMPORTANT__: You must load the `three-bundles` package later in your project in order to activate the bundles functionality.\n\n## Usage\n\nTHREE Bundles provide a set of Require.js plug-ins for loading various THREE.js resources. You only need to add the dependency, and the appropriate object will be created for you.\n\n```javascript\ndefine([\"mesh!path/to/mesh.json\"], function(mesh) {\n    ...\n    // Add the mesh to your scene\n    scene.add( mesh );\n    ...\n});\n```\n\nBefore accessing the resources of a bundle you need first to load it. In order to load a bundle's entry point, including all the resources you should use the `bundle!path/to/bundle` plugin:\n\n```javascript\n    ...\n    require([\"bundle!/path/to/bundle\"], function(bundle) {\n        scene.add( bundle.someBundleSceneObject );\n    });\n    ...\n```\n\nUpon loading a bundle, it's resources can be accessed in absolute or relative path format:\n\n * From within the bundle: `texture!./file.jpg`\n * From another bundle: `texture!bundle.name/file.jpg`\n\n## Reference\n\n### Bundle Layout\n\nEach bundle is just a folder with multiple sub-folders, one for each kind of resource. Additionaly, it nas an __entry point__ and __index__ file.\n\nFor example:\n\n```\nmy.bundle\n |\n +- texture\n |   |\n |   +- tex_diffuse.jpg\n |   `- tex_normal.jpg\n +- object\n |   |\n |   `- my_object.obj\n +- main.js\n `- index.js\n```\n\nThe `index.js` file enumerates all the resources in the bundle and is automatically generated using the [tools/update-index.py](https://github.com/wavesoft/three-bundles/blob/master/tools/update-index.py) script.\n\nThe `main.js` is the entry point of the bundle, which is used to deliver the core logic of the bundle. I no such logic is required, an empty placeholder can be used instead.\n\nUpon loading a bundle, all the resources defined in the `index.js` file will be downloaded. Then, the entry point will be downloaded and returned.\n\n### Available Plugins\n\nAccording to the plugin and the filename extension, a different THREE.js object is created. The following table summarises the available modules:\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003cth\u003ePlugin Name\u003c/th\u003e\n        \u003cth\u003eExtension\u003c/th\u003e\n        \u003cth\u003eTHREE.js Object\u003c/th\u003e\n    \u003ctr/\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ctt\u003egeometry!\u003c/tt\u003e...\u003c/td\u003e\n        \u003ctd\u003e.json\u003c/td\u003e\n        \u003ctd\u003e\n            \u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Core/Geometry\"\u003eTHREE.Geometry\u003c/a\u003e\u003c/code\u003e,\n            \u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Core/BufferGeometry\"\u003eTHREE.BufferGeometry\u003c/a\u003e\u003c/code\u003e\n        \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ctt\u003ematerial!\u003c/tt\u003e...\u003c/td\u003e\n        \u003ctd\u003e.json\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Materials/Material\"\u003eTHREE.Material\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd rowspan=\"3\"\u003e\u003ctt\u003emesh!\u003c/tt\u003e...\u003c/td\u003e\n        \u003ctd\u003e.json\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Objects/Mesh\"\u003eTHREE.Mesh\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e.obj\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Objects/Mesh\"\u003eTHREE.Mesh\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e.dae\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Objects/Mesh\"\u003eTHREE.Mesh\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ctt\u003eobject!\u003c/tt\u003e...\u003c/td\u003e\n        \u003ctd\u003e.json\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Core/Object3D\"\u003eTHREE.Object3D\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ctt\u003eshader!\u003c/tt\u003e...\u003c/td\u003e\n        \u003ctd\u003e.shader, .txt\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd rowspan=\"2\"\u003e\u003ctt\u003etexture!\u003c/tt\u003e...\u003c/td\u003e\n        \u003ctd\u003e.jpg, .gif, .png, .bmp\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Textures/Texture\"\u003eTHREE.Texture\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e.dds\u003c/td\u003e\n        \u003ctd\u003e\u003ccode\u003e\u003ca target=\"_blank\" href=\"http://threejs.org/docs/#Reference/Textures/CompressedTexture\"\u003eTHREE.CompressedTexture\u003c/a\u003e\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n### Dynamic Referencing\n\nIt is also possible to depend on other resources without explicitly requesting them through a `request` method. For example, a material can depend on one or more textures, just by putting the texture name in the appropriate `map` property. For example:\n\n```javascript\n{\n    \"type\"  : \"MeshBasicMaterial\",\n    \"color\" : 0xffffff,\n    \"map\"   : \"texture!./noise-map.png\"\n}\n```\n\nSpecific properties of different kinds of resources will trigger this behaviour. The following table enumerates all of them:\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003cth\u003eResource\u003c/th\u003e\n        \u003cth\u003eProperties\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003ematerial (\u003ctt\u003e.json\u003c/tt\u003e)\u003c/td\u003e\n        \u003ctd\u003e\n            \u003ccode\u003emap\u003c/code\u003e,\n            \u003ccode\u003ealphaMap\u003c/code\u003e,\n            \u003ccode\u003ebumpMap\u003c/code\u003e,\n            \u003ccode\u003enormalMap\u003c/code\u003e,\n            \u003ccode\u003edisplacementMap\u003c/code\u003e,\n            \u003ccode\u003especularMap\u003c/code\u003e,\n            \u003ccode\u003eenvMap\u003c/code\u003e,\n            \u003ccode\u003elightMap\u003c/code\u003e,\n            \u003ccode\u003eaoMap\u003c/code\u003e,\n            \u003ccode\u003evertexShader\u003c/code\u003e,\n            \u003ccode\u003efragmentShader\u003c/code\u003e\n        \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003emesh (\u003ctt\u003e.json\u003c/tt\u003e)\u003c/td\u003e\n        \u003ctd\u003e\n            \u003ccode\u003egeometry\u003c/code\u003e,\n            \u003ccode\u003ematerial\u003c/code\u003e\n        \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003emesh (\u003ctt\u003e.obj\u003c/tt\u003e)\u003c/td\u003e\n        \u003ctd\u003e\n            Each material \u003ccode\u003ename\u003c/code\u003e is assumed to be a reference to a material (without the \u003cem\u003ematerial!\u003c/em\u003e prefix)\n        \u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavesoft%2Fthree-bundles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwavesoft%2Fthree-bundles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavesoft%2Fthree-bundles/lists"}