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: 6 months 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 10 years ago)
Default Branch: master
Last Pushed: 2015-12-01T23:32:14.000Z (about 10 years ago)
Last Synced: 2025-03-01T20:02:12.532Z (12 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:

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)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/wavesoft/three-bundles

Awesome Lists containing this project

README