Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wavesoft/three-bundles
THREE Bundles is a set of Require.js plugins that help you bundle and ship THREE.js resources.
https://github.com/wavesoft/three-bundles
Last synced: 13 days ago
JSON representation
THREE Bundles is a set of Require.js plugins that help you bundle and ship THREE.js resources.
- Host: GitHub
- URL: https://github.com/wavesoft/three-bundles
- Owner: wavesoft
- License: gpl-2.0
- Created: 2015-10-25T10:07:55.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2015-12-01T23:32:14.000Z (about 9 years ago)
- Last Synced: 2024-11-13T04:48:32.724Z (2 months ago)
- Language: JavaScript
- Size: 9.19 MB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# THREE Bundles
THREE 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.
In addition it suggests a way of organizing your resources in reusable `bundles` that can be quickly and optimally loaded in your scene.
[Example](https://cdn.rawgit.com/wavesoft/three-bundles/f3348a0ae6d8c2a6fed3c444cd1ecec1ba49f750/examples/hello_world.html)
__Note: Be aware that this is an in-development, early preview version, with many advanced THREE.js loader features missing.__
## Requirements
* __Require.js__
* __THREE.js__ (aliased `three` in require.js)
* __text.js__ (from https://github.com/requirejs/text)
## Installing
You can include THREE Bundles to your Require.js project with the following configuration:
```javascript
require.config({
/**
* (1) Add three-bundles as a package
*/
packages: [
{
'name' : 'three-bundles',
'location' : 'path/to/your/three-bundles/js'
}
],
/**
* (2) Configure three-bundles
*/
threeBundles: {
/**
* Specify the base Url (relative to requireJS' `baseUrl`),
* that threeBundles will use for loading the bundles.
*
* If missing, it will default to requireJS' `baseUrl`
*/
'baseUrl': '../bundles'
},
/**
* (3) (Optionally) Make sure THREE.js is accessible under the name 'three'
*/
paths: {
'three': 'path/to/three.js'
}
})
```
__IMPORTANT__: You must load the `three-bundles` package later in your project in order to activate the bundles functionality.
## Usage
THREE 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.
```javascript
define(["mesh!path/to/mesh.json"], function(mesh) {
...
// Add the mesh to your scene
scene.add( mesh );
...
});
```
Before 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:
```javascript
...
require(["bundle!/path/to/bundle"], function(bundle) {
scene.add( bundle.someBundleSceneObject );
});
...
```
Upon loading a bundle, it's resources can be accessed in absolute or relative path format:
* From within the bundle: `texture!./file.jpg`
* From another bundle: `texture!bundle.name/file.jpg`
## Reference
### Bundle Layout
Each bundle is just a folder with multiple sub-folders, one for each kind of resource. Additionaly, it nas an __entry point__ and __index__ file.
For example:
```
my.bundle
|
+- texture
| |
| +- tex_diffuse.jpg
| `- tex_normal.jpg
+- object
| |
| `- my_object.obj
+- main.js
`- index.js
```
The `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.
The `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.
Upon loading a bundle, all the resources defined in the `index.js` file will be downloaded. Then, the entry point will be downloaded and returned.
### Available Plugins
According to the plugin and the filename extension, a different THREE.js object is created. The following table summarises the available modules:
Plugin Name
Extension
THREE.js Object
geometry!...
.json
THREE.Geometry,
THREE.BufferGeometry
material!...
.json
THREE.Material
mesh!...
.json
THREE.Mesh
.obj
THREE.Mesh
.dae
THREE.Mesh
object!...
.json
THREE.Object3D
shader!...
.shader, .txt
string
texture!...
.jpg, .gif, .png, .bmp
THREE.Texture
.dds
THREE.CompressedTexture
### Dynamic Referencing
It 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:
```javascript
{
"type" : "MeshBasicMaterial",
"color" : 0xffffff,
"map" : "texture!./noise-map.png"
}
```
Specific properties of different kinds of resources will trigger this behaviour. The following table enumerates all of them:
Resource
Properties
material (.json)
map,
alphaMap,
bumpMap,
normalMap,
displacementMap,
specularMap,
envMap,
lightMap,
aoMap,
vertexShader,
fragmentShader
mesh (.json)
geometry,
material
mesh (.obj)
Each material name is assumed to be a reference to a material (without the material! prefix)