Project

General

Profile

Programmers Guide » History » Version 23

Jordi Rovira, 11/27/2017 11:01 AM

1 21 Jordi Rovira
<h1>Programming Guide</h1>
2 20 Jordi Rovira
3 9 Jordi Rovira
<p>{{toc}}</p>
4 1 Jordi Rovira
5 7 Jordi Rovira
<h1>Architecture</h1>
6 4 Jordi Rovira
7 17 Jordi Rovira
<h2>Unreal Engine modules</h2>
8 4 Jordi Rovira
9 2 Jordi Rovira
<p>The system is structured as an Unreal plugin with two additional Unreal modules: one for the editor and one for the runtime. These modules use external libraries for the Mutable runtime, which is a standalonw library with no dependencies.</p>
10 1 Jordi Rovira
11 3 Jordi Rovira
<p><img alt="" data-rich-file-id="5" src="/system/rich/rich_files/rich_files/000/000/005/original/Mutable-Architecture-768x808.png" style="height: 606px; width: 576px;" /></p>
12 2 Jordi Rovira
13 7 Jordi Rovira
<h2>Folder Structure</h2>
14 2 Jordi Rovira
15 10 Jordi Rovira
<table border="0" cellpadding="0" cellspacing="0" style="width:100%;">
16 10 Jordi Rovira
	<tbody>
17 10 Jordi Rovira
		<tr>
18 11 Jordi Rovira
			<td style="width: 420px; height: 411px;"><img alt="" data-rich-file-id="4" src="/system/rich/rich_files/rich_files/000/000/004/original/Mutable-Unreal-Folder-Structure-1.png" style="width: 420px; height: 411px;" /></td>
19 10 Jordi Rovira
			<td style="vertical-align: top;">
20 10 Jordi Rovira
			<p>This is the basic folder structure of an Unreal Engine game that uses Mutable. The hierarchy only shows the relevant folders for Mutable source code.</p>
21 1 Jordi Rovira
22 10 Jordi Rovira
			<p>&nbsp;</p>
23 1 Jordi Rovira
24 23 Jordi Rovira
			<p>The folder &ldquo;source&rdquo; is optional (and by default not included with all licenses) and it contains the source code of the standalone runtime and tools libraries. These are already included in the &ldquo;lib&rdquo; folder as precompiled binaries for each supported platform, with the required headers in the &ldquo;include&rdquo; folder.</p>
25 23 Jordi Rovira
			&nbsp;
26 10 Jordi Rovira
27 10 Jordi Rovira
			<p>The &ldquo;source&rdquo; folder may also contain the source code for the standalone tools for Mutable. These tools are not required for normal Mutable usage but they can be very helpful to&nbsp;debug and profile your project.</p>
28 10 Jordi Rovira
			</td>
29 23 Jordi Rovira
			<td style="vertical-align: top;">&nbsp;</td>
30 10 Jordi Rovira
		</tr>
31 10 Jordi Rovira
	</tbody>
32 10 Jordi Rovira
</table>
33 2 Jordi Rovira
34 12 Jordi Rovira
<h2>Engine changes</h2>
35 12 Jordi Rovira
36 12 Jordi Rovira
<p>Most of Mutable happens in the plugin described above. However, there are some changes that are required in the engine and tools, than cannot be done from a plugin. These are a small set of changes (usually a handful of lines) and they affect the following files:</p>
37 12 Jordi Rovira
38 12 Jordi Rovira
<ul>
39 12 Jordi Rovira
	<li>To add an additional cook step to build the CustomizableObject assets:
40 12 Jordi Rovira
	<ul>
41 13 Jordi Rovira
		<li>Engine/Source/Editor/UnrealEd/Private/Commandlets/CookCommandlet.cpp</li>
42 12 Jordi Rovira
	</ul>
43 12 Jordi Rovira
	</li>
44 12 Jordi Rovira
	<li>To add some texture streaming tweaks for mutable textures:
45 12 Jordi Rovira
	<ul>
46 12 Jordi Rovira
		<li>/Engine/Source/Runtime/<wbr />CoreUObject/Public/<wbr />Serialization/BulkData.h</li>
47 12 Jordi Rovira
		<li>/Engine/Source/Runtime/<wbr />CoreUObject/Private/<wbr />Serialization/BulkData.cpp</li>
48 12 Jordi Rovira
		<li>/Engine/Source/Runtime/<wbr />Engine/Private/Texture2D.cpp</li>
49 12 Jordi Rovira
		<li>/Engine/Source/Runtime/<wbr />Engine/Private/<wbr />TextureDerivedData.cpp</li>
50 12 Jordi Rovira
	</ul>
51 12 Jordi Rovira
	</li>
52 12 Jordi Rovira
	<li>To extend some worker thread stack size:
53 12 Jordi Rovira
	<ul>
54 12 Jordi Rovira
		<li>/Engine/Source/Runtime/<wbr />Launch/Private/<wbr />LaunchEngineLoop.cpp</li>
55 12 Jordi Rovira
	</ul>
56 12 Jordi Rovira
	</li>
57 12 Jordi Rovira
</ul>
58 12 Jordi Rovira
59 12 Jordi Rovira
<p>We aim at reducing the number of this engine changes as our development progresses.</p>
60 1 Jordi Rovira
61 15 Jordi Rovira
<h2>Packaging a project</h2>
62 2 Jordi Rovira
63 15 Jordi Rovira
<p>When a project is packaged for distribution, Mutable will compile all the relevant CustomizableObject assets. This compilation step will be done with maximum optimisation so it will take longer than compiling an object in the editor. Additionally, the data used by the CustomizableObjects will be prepared for disk streaming. Thanks to this, the memory usage of your project will be kept low regardless how may options you have in your objects.</p>
64 1 Jordi Rovira
65 15 Jordi Rovira
<p>In order to package a project using Mutable you need to include an additional folder in the packaging process: <strong>&lt;YourProject&gt;/Content/MutableStreamedData</strong> . You can do this in the DefaultGame.ini file of your project:</p>
66 2 Jordi Rovira
67 15 Jordi Rovira
<pre style="margin-left: 40px;">
68 15 Jordi Rovira
+DirectoriesToAlwaysStageAsUFS=(Path=&quot;MutableStreamedData&quot;) )</pre>
69 1 Jordi Rovira
70 15 Jordi Rovira
<p>or from the project settings in the Unreal editor:</p>
71 1 Jordi Rovira
72 16 Jordi Rovira
<p><img alt="" data-rich-file-id="156" src="/system/rich/rich_files/rich_files/000/000/156/original/ProjectSettingsStreameingFolder.png" style="height: 50%; width: 50%;" /></p>
73 15 Jordi Rovira
74 1 Jordi Rovira
<h1>Using customizable objects in game</h1>
75 17 Jordi Rovira
76 17 Jordi Rovira
<h2>CustomizableSkeletalComponent</h2>
77 17 Jordi Rovira
78 17 Jordi Rovira
<p>This helper component can be used with an actor in order to update a SkeletalMeshComponent replacing its mesh asset with a Mutable-generated mesh. The steps to use this component are:</p>
79 17 Jordi Rovira
80 17 Jordi Rovira
<ol>
81 17 Jordi Rovira
	<li>Create an actor with a SkeletalMeshComponent.</li>
82 17 Jordi Rovira
	<li>Add a new CustomizableSkeletalComponent as a child of the SkeletalMeshComponent.</li>
83 17 Jordi Rovira
	<li>Assign a CustomizableInstance asset to the CustomizableSkeletalComponent.</li>
84 17 Jordi Rovira
	<li>When the actor is added to a level, it should automatically show the customized skeletal mesh.</li>
85 17 Jordi Rovira
</ol>
86 17 Jordi Rovira
87 18 Jordi Rovira
<h2>The Reference Mesh</h2>
88 17 Jordi Rovira
89 18 Jordi Rovira
<p>The Reference Mesh is an Unreal SkeletalMesh asset that is used as a template to create customizable skeletal meshes. It is assigned to the CustomizableObject asset.</p>
90 1 Jordi Rovira
91 18 Jordi Rovira
<ul>
92 18 Jordi Rovira
	<li>All the data that is not related to meshes and textures will be copied from the reference skeletal mesh.</li>
93 18 Jordi Rovira
	<li>While a customised skeletal mesh is being built, the reference skeletal mesh will be displayed.</li>
94 18 Jordi Rovira
</ul>
95 18 Jordi Rovira
96 18 Jordi Rovira
<h2>Object States</h2>
97 15 Jordi Rovira
98 15 Jordi Rovira
<h1>Internal Design</h1>
99 15 Jordi Rovira
100 15 Jordi Rovira
<p>Mutable is designed around the concept of virtual machine. Customizable objects are decomposed in series of intructions that are optimised to build the instances on different situations. These instructions operate on mesh fragments, images and colours and they transform them by merging, blending, packaging texture coordinates etc.</p>
101 15 Jordi Rovira
102 15 Jordi Rovira
<p>The system relies heavily in a pre-process of the object graph that generates code for a virtual machine whose operations involve mesh fragments, images, etc. This object-construction code is then optimised for every use case of the model so that the optimal process to construct an instance is found.</p>
103 15 Jordi Rovira
104 15 Jordi Rovira
<p><img alt="" data-rich-file-id="6" src="/system/rich/rich_files/rich_files/000/000/006/original/img_56f55d6a9b7b6.png" /></p>
105 15 Jordi Rovira
106 15 Jordi Rovira
<p>Mutable standalone model debugger and profiler showing the virtual machine code, the set of constant data (image blocks and mesh fragments), a preview object and texture layout and a simulation of the parallel construction of a model with its memory usage.</p>