Skip to content

Commit 60e365a

Browse files
mrdoobmrdoob
authored
Merge pull request #13975 from takahirox/MMDLoaderV2
MMDLoader clean up and document
2 parents c3de325 + dc2eda6 commit 60e365a

File tree

10 files changed

+2529
-1995
lines changed

10 files changed

+2529
-1995
lines changed

‎docs/examples/animations/MMDAnimationHelper.html‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<base href="../../" />
6+
<script src="list.js"></script>
7+
<script src="page.js"></script>
8+
<link type="text/css" rel="stylesheet" href="page.css" />
9+
</head>
10+
<body>
11+
<h1>[name]</h1>
12+
13+
<p class="desc"> A animation helper for <a href="http://www.geocities.jp/higuchuu4/index_e.htm"><em>MMD</em></a> resources. <br /><br />
14+
[name] handles animation of MMD assets loaded by [page:MMDLoader] with MMD special features as IK, Grant, and Physics.
15+
</p>
16+
17+
<h2>Example</h2>
18+
19+
<code>
20+
// Instantiate a helper
21+
var helper = new THREE.MMDAnimationHelper();
22+
23+
// Load MMD resources and add to helper
24+
new THREE.MMDLoader().loadWithAnimation(
25+
'models/mmd/miku.pmd',
26+
'models/mmd/dance.vmd',
27+
function ( mmd ) {
28+
29+
helper.add( mmd.mesh, {
30+
animation: mmd.animation,
31+
physics: true
32+
} );
33+
34+
scene.add( mesh );
35+
36+
new THREE.AudioLoader().load(
37+
'audios/mmd/song.mp3',
38+
function ( buffer ) {
39+
40+
var listener = new THREE.AudioListener();
41+
var audio = new THREE.Audio( listener )
42+
.setBuffer( buffer );
43+
44+
listener.position.z = 1;
45+
46+
scene.add( audio );
47+
scene.add( listener );
48+
49+
}
50+
51+
);
52+
53+
}
54+
);
55+
56+
function render() {
57+
58+
helper.update( clock.getDelta() );
59+
renderer.render( scene, camera );
60+
61+
}
62+
</code>
63+
64+
[example:webgl_loader_mmd]<br />
65+
[example:webgl_loader_mmd_pose]<br />
66+
[example:webgl_loader_mmd_audio]<br />
67+
68+
<br />
69+
<hr>
70+
71+
<h2>Constructor</h2>
72+
73+
<h3>[name]( [param:Object params] )</h3>
74+
<p>
75+
[page:Object params] — (optional)<br />
76+
<ul>
77+
<li> [page:Boolean sync] - Whether animation durations of added objects are synched. Default is true.</li>
78+
<li> [page:Number afterglow] - Default is 0.0.</li>
79+
<li> [page:Boolean resetPhysicsOnLoop] - Default is true.</li>
80+
</ul>
81+
</p>
82+
<p>
83+
Creates a new [name].
84+
</p>
85+
86+
<h2>Properties</h2>
87+
88+
<h3>[property:Audio audio]</h3>
89+
<p>An [page:Audio] added to helper.</p>
90+
91+
<h3>[property:Camera camera]</h3>
92+
<p>An [page:Camera] added to helper.</p>
93+
94+
<h3>[property:Array meshes]</h3>
95+
<p>An array of [page:SkinnedMesh] added to helper.</p>
96+
97+
<h3>[property:WeakMap objects]</h3>
98+
<p>A [page:WeakMap] which holds animation stuffs used in helper for objects added to helper. For example, you can access [page:AnimationMixer] for an added [page:SkinnedMesh] with "helper.objects.get( mesh ).mixer"</p>
99+
100+
101+
<h2>Methods</h2>
102+
103+
<h3>[method:MMDAnimationHelper add]( [param:Object3D object], [param:Object params] )</h3>
104+
<p>
105+
[page:Object3D object] — [page:SkinnedMesh], [page:Camera], or [page:Audio]<br />
106+
[page:Object params] — (optional)<br />
107+
<ul>
108+
<li>[page:AnimationClip animation] - an [page:AnimationClip] or an array of [page:AnimationClip] set to object. Only for [page:SkinnedMesh] and [page:Camera]. Default is undefined.</li>
109+
<li>[page:Boolean physics] - Only for [page:SkinnedMesh]. A flag whether turn on physics. Default is true.</li>
110+
<li>[page:Number delayTime] - Only for [page:Audio]. Default is 0.0.</li>
111+
</ul>
112+
</p>
113+
<p>
114+
Add an [page:SkinnedMesh], [page:Camera], or [page:Audio] to helper and setup animation. The anmation durations of added objects are synched.
115+
If camera/audio has already been added, it'll be replaced with a new one.
116+
</p>
117+
118+
<h3>[method:MMDAnimationHelper enable]( [param:string key], [param:Boolean enabled] )</h3>
119+
<p>
120+
[page:string key] — Allowed strings are 'animation', 'ik', 'grant', 'physics', and 'cameraAnimation'.<br />
121+
[page:Boolean enabled] — true is enable, false is disable<br />
122+
</p>
123+
<p>
124+
Enable/Disable an animation feature
125+
</p>
126+
127+
<h3>[method:MMDAnimationHelper pose]( [param:SkinnedMesh mesh], [param:Object vpd], [param:Object params] )</h3>
128+
<p>
129+
[page:SkinnedMesh mesh] — [page:SkinnedMesh] which changes the posing. It doesn't need to be added to helper.<br />
130+
[page:Object vpd] — VPD content obtained by [page:MMDLoader].loadVPD<br />
131+
[page:Object params] — (optional)<br />
132+
<ul>
133+
<li>[page:Boolean resetPose] - Default is true.</li>
134+
<li>[page:Boolean ik] - Default is true.</li>
135+
<li>[page:Boolean grant] - Default is true.</li>
136+
</ul>
137+
</p>
138+
<p>
139+
Changes the posing of [page:SkinnedMesh] as VPD content specifies.
140+
</p>
141+
142+
<h3>[method:MMDAnimationHelper remove]( [param:Object3D object] )</h3>
143+
<p>
144+
[page:Object3D object] — [page:SkinnedMesh], [page:Camera], or [page:Audio]<br />
145+
</p>
146+
<p>
147+
Remove an [page:SkinnedMesh], [page:Camera], or [page:Audio] from helper.
148+
</p>
149+
150+
<h3>[method:MMDAnimationHelper update]( [param:Nummber delta] )</h3>
151+
<p>
152+
[page:Number delta] — number in second<br />
153+
</p>
154+
<p>
155+
Advance mixer time and update the animations of objects added to helper
156+
</p>
157+
158+
<h2>Source</h2>
159+
160+
[link:https://github.com/mrdoob/three.js/blob/master/examples/js/animation/MMDAnimationHelper.js examples/js/animation/MMDAnimationHelper.js]
161+
</body>
162+
</html>

‎docs/examples/loaders/MMDLoader.html‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<base href="../../" />
6+
<script src="list.js"></script>
7+
<script src="page.js"></script>
8+
<link type="text/css" rel="stylesheet" href="page.css" />
9+
</head>
10+
<body>
11+
[page:Loader] &rarr;
12+
<h1>[name]</h1>
13+
14+
<p class="desc"> A loader for <a href="http://www.geocities.jp/higuchuu4/index_e.htm"><em>MMD</em></a> resources. <br /><br />
15+
[name] creates Three.js Objects from MMD resources as PMD, PMX, VMD, and VPD files.
16+
You can easily handle MMD special features, as IK, Grant, and Physics, with [page:MMDAnimationHelper].<br /><br />
17+
18+
If you want raw content of MMD resources, use .loadPMD/PMX/VMD/VPD methods.
19+
20+
<h2>Example</h2>
21+
22+
<code>
23+
// Instantiate a loader
24+
var loader = new THREE.MMDLoader();
25+
26+
// Load a MMD model
27+
loader.load(
28+
// path to PMD/PMX file
29+
'models/mmd/miku.pmd',
30+
// called when the resource is loaded
31+
function ( mesh ) {
32+
33+
scene.add( mesh );
34+
35+
},
36+
// called when loading is in progresses
37+
function ( xhr ) {
38+
39+
console.log( ( xhr.loaded / xhr.total * 100 ) + '% loaded' );
40+
41+
},
42+
// called when loading has errors
43+
function ( error ) {
44+
45+
console.log( 'An error happened' );
46+
47+
}
48+
);
49+
</code>
50+
51+
[example:webgl_loader_mmd]<br />
52+
[example:webgl_loader_mmd_pose]<br />
53+
[example:webgl_loader_mmd_audio]<br />
54+
55+
<br />
56+
<hr>
57+
58+
<h2>Constructor</h2>
59+
60+
<h3>[name]( [param:LoadingManager manager] )</h3>
61+
<p>
62+
[page:LoadingManager manager] — The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].
63+
</p>
64+
<p>
65+
Creates a new [name].
66+
</p>
67+
68+
<h2>Properties</h2>
69+
70+
71+
<h2>Methods</h2>
72+
73+
<h3>[method:null load]( [param:String url], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )</h3>
74+
<p>
75+
[page:String url] — A string containing the path/URL of the <em>.pmd</em> or <em>.pmx</em> file.<br />
76+
[page:Function onLoad] — A function to be called after the loading is successfully completed.<br />
77+
[page:Function onProgress] — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, that contains .[page:Integer total] and .[page:Integer loaded] bytes.<br />
78+
[page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives error as an argument.<br />
79+
</p>
80+
<p>
81+
Begin loading PMD/PMX model file from url and fire the callback function with the parsed [page:SkinnedMesh] containing [page:BufferGeometry] and an array of [page:MeshToonMaterial].
82+
</p>
83+
84+
<h3>[method:null loadAnimation]( [param:String url], [param:Object3D object], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )</h3>
85+
<p>
86+
[page:String url] — A string or an array of string containing the path/URL of the <em>.vmd</em> file(s).If two or more files are specified, they'll be merged.<br />
87+
[page:Object3D object] — [page:SkinnedMesh] or [page:Camera]. Clip and its tacks will be fitting to this object.<br />
88+
[page:Function onLoad] — A function to be called after the loading is successfully completed.<br />
89+
[page:Function onProgress] — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, that contains .[page:Integer total] and .[page:Integer loaded] bytes.<br />
90+
[page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives error as an argument.<br />
91+
</p>
92+
<p>
93+
Begin loading VMD motion file(s) from url(s) and fire the callback function with the parsed [page:AnimatioinClip].
94+
</p>
95+
96+
<h3>[method:null loadWithAnimation]( [param:String modelUrl], [param:String vmdUrl], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )</h3>
97+
<p>
98+
[page:String modelUrl] — A string containing the path/URL of the <em>.pmd</em> or <em>.pmx</em> file.<br />
99+
[page:String vmdUrl] — A string or an array of string containing the path/URL of the <em>.vmd</em> file(s).<br />
100+
[page:Function onLoad] — A function to be called after the loading is successfully completed.<br />
101+
[page:Function onProgress] — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, that contains .[page:Integer total] and .[page:Integer loaded] bytes.<br />
102+
[page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives error as an argument.<br />
103+
</p>
104+
<p>
105+
Begin loading PMD/PMX model file and VMD motion file(s) from urls and fire the callback function with an [page:Object] containing parsed [page:SkinnedMesh] and [page:AnimationClip] fitting to the [page:SkinnedMesh].
106+
</p>
107+
108+
<h3>[method:MMDLoader setCrossOrigin]( [param:String crossOrigin] )</h3>
109+
<p>
110+
[page:String crossOrigin] — The crossOrigin string to implement CORS for loading the url from a different domain that allows CORS.
111+
</p>
112+
113+
114+
<h2>Source</h2>
115+
116+
[link:https://github.com/mrdoob/three.js/blob/master/examples/js/loaders/MMDLoader.js examples/js/loaders/MMDLoader.js]
117+
</body>
118+
</html>

‎docs/list.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -337,6 +337,10 @@ var list = {
337337

338338
"Examples": {
339339

340+
"Animations": {
341+
"MMDAnimationHelper": "examples/animations/MMDAnimationHelper"
342+
},
343+
340344
"Controls": {
341345
"OrbitControls": "examples/controls/OrbitControls"
342346
},
@@ -350,6 +354,7 @@ var list = {
350354
"Loaders": {
351355
"BabylonLoader": "examples/loaders/BabylonLoader",
352356
"GLTFLoader": "examples/loaders/GLTFLoader",
357+
"MMDLoader": "examples/loaders/MMDLoader",
353358
"MTLLoader": "examples/loaders/MTLLoader",
354359
"OBJLoader": "examples/loaders/OBJLoader",
355360
"OBJLoader2": "examples/loaders/OBJLoader2",

0 commit comments

Comments
 (0)