profectus-docs/assets/guide_advanced-concepts_creating-features.md.b7295777.js

import{_ as s,c as e,o as a,N as n}from"./chunks/framework.0799945b.js";const d=JSON.parse('{"title":"Creating Features","description":"","frontmatter":{},"headers":[],"relativePath":"guide/advanced-concepts/creating-features.md","lastUpdated":1682272069000}'),o={name:"guide/advanced-concepts/creating-features.md"},t=n(`<h1 id="creating-features" tabindex="-1">Creating Features <a class="header-anchor" href="#creating-features" aria-label="Permalink to &quot;Creating Features&quot;">​</a></h1><p>Profectus is designed to encourage the developer to eventually start designing their own features for use in specific games. Features are designed to work where they require minimal (and typically zero) modifications around the code base - you simply write a single file for the feature, and any vue components it needs, and the act of importing that feature will set everything up. This also means you can share these features with others in entire collections, and any they don&#39;t use won&#39;t be present in the build output, won&#39;t be loaded, and won&#39;t affect the project in any way.</p><h2 id="creating-the-feature" tabindex="-1">Creating the Feature <a class="header-anchor" href="#creating-the-feature" aria-label="Permalink to &quot;Creating the Feature&quot;">​</a></h2><p>Every feature has a couple of types. They have the feature themselves, a generic version for convenience, and any constructor typically has an options type and a type that gets &quot;added&quot; to it to create the feature itself. These typically involve replacing some types to denote how various properties change from, for example, <code>Computable&lt;X&gt;</code> to <code>ProcessedComputable&lt;X&gt;</code>. You should be able to use any of the existing features as a reference for how these types look and work.</p><p>Most significantly, the base type should typically always have a <code>type</code> property pointing to a symbol unique to this feature, so they can be easily differentiated at runtime. If it&#39;s a feature that should be renderable, then it&#39;ll also need <code>[Component]</code> and <code>[GatherProps]</code> properties, which describe the vue component to use and how to get the props for it from this feature, as well as a unique ID for the feature&#39;s <a href="./nodes">node</a>. You can use the <a href="/api/modules/features/feature#getuniqueid">getUniqueID</a> utility to help.</p><p>The constructor itself should do several things. They should take their options within a function, so that they&#39;re not resolved when the object is constructed. It should return a lazy proxy of the feature, which allows features to reference each other and only resolve themselves once every feature is defined. The constructor should create any persistent refs it may require outside of the lazy proxy - it won&#39;t have access to the options at this point, so it should make any it <em>potentially</em> may require. Any that turn out not being needed can be <a href="/api/modules/game/persistence#deletepersistent">deleted</a>. Inside the lazy proxy the constructor should create the options object, assign onto it every property from the base type, call <a href="/api/modules/util/computed#processcomputable">processComputable</a> on every computable type, and <a href="/api/modules/features/feature#setdefault">setDefault</a> on any property with a default value. Then you should be able to simply return the options object, likely with a type cast, and the constructor will be complete.</p><p>Because typescript does not emit JS, if a property is supposed to be a function it is impossible to differentiate between a function that is itself the intended value or a function that returns the actual value. For this reason it is not recommended for any feature types to include properties that are <code>Computable&lt;Function&gt;</code>s, and all functions <em>will</em> be wrapped in <code>computed</code>. The notable exception to this is <a href="./../important-concepts/coercable#render-functions-jsx">JSX</a>, which uses a utility function to mark that a functi
<span class="line"><span style="color:#F07178;">    </span><span style="color:#C792EA;">interface</span><span style="color:#F07178;"> </span><span style="color:#FFCB6B;">Settings</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">{</span></span>
<span class="line"><span style="color:#F07178;">        hideChallenges</span><span style="color:#89DDFF;">:</span><span style="color:#F07178;"> </span><span style="color:#FFCB6B;">boolean</span><span style="color:#89DDFF;">;</span></span>
<span class="line"><span style="color:#F07178;">    </span><span style="color:#89DDFF;">}</span></span>
<span class="line"><span style="color:#89DDFF;">}</span></span></code></pre></div><p>Next you must set the default value of this setting when the settings is loaded, which happens during the <code>loadSettings</code> event emitted on the <a href="/api/modules/game/events#globalbus">global bus</a>. This is how that looks like for the same <code>hideChallenges</code> setting from above:</p><div class="language-ts"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki material-theme-palenight"><code><span class="line"><span style="color:#A6ACCD;">globalBus</span><span style="color:#89DDFF;">.</span><span style="color:#82AAFF;">on</span><span style="color:#A6ACCD;">(</span><span style="color:#89DDFF;">&quot;</span><span style="color:#C3E88D;">loadSettings</span><span style="color:#89DDFF;">&quot;</span><span style="color:#89DDFF;">,</span><span style="color:#A6ACCD;"> </span><span style="color:#A6ACCD;font-style:italic;">settings</span><span style="color:#A6ACCD;"> </span><span style="color:#C792EA;">=&gt;</span><span style="color:#A6ACCD;"> </span><span style="color:#89DDFF;">{</span></span>
<span class="line"><span style="color:#F07178;">    </span><span style="color:#82AAFF;">setDefault</span><span style="color:#F07178;">(</span><span style="color:#A6ACCD;">settings</span><span style="color:#89DDFF;">,</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">&quot;</span><span style="color:#C3E88D;">hideChallenges</span><span style="color:#89DDFF;">&quot;</span><span style="color:#89DDFF;">,</span><span style="color:#F07178;"> </span><span style="color:#FF9CAC;">false</span><span style="color:#F07178;">)</span><span style="color:#89DDFF;">;</span></span>
<span class="line"><span style="color:#89DDFF;">}</span><span style="color:#A6ACCD;">)</span><span style="color:#89DDFF;">;</span></span></code></pre></div><p>Finally, you&#39;ll need to register a Vue component to the settings menu so the player can actually modify this setting. Here&#39;s the example for the <code>hideChallenges</code> setting:</p><div class="language-ts"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki material-theme-palenight"><code><span class="line"><span style="color:#82AAFF;">registerSettingField</span><span style="color:#A6ACCD;">(</span></span>
<span class="line"><span style="color:#A6ACCD;">    </span><span style="color:#82AAFF;">jsx</span><span style="color:#A6ACCD;">(</span><span style="color:#89DDFF;">()</span><span style="color:#A6ACCD;"> </span><span style="color:#C792EA;">=&gt;</span><span style="color:#A6ACCD;"> (</span></span>
<span class="line"><span style="color:#A6ACCD;">        </span><span style="color:#89DDFF;">&lt;</span><span style="color:#A6ACCD;font-style:italic;">Toggle</span></span>
<span class="line"><span style="color:#A6ACCD;">            title</span><span style="color:#89DDFF;">={</span><span style="color:#F07178;">jsx</span><span style="color:#89DDFF;">(</span><span style="color:#A6ACCD;">(</span><span style="color:#89DDFF;">)</span><span style="color:#A6ACCD;"> </span><span style="color:#C792EA;">=&gt;</span><span style="color:#A6ACCD;"> (</span></span>
<span class="line"><span style="color:#A6ACCD;">                </span><span style="color:#89DDFF;">&lt;</span><span style="color:#FFCB6B;">span</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">class</span><span style="color:#89DDFF;">=</span><span style="color:#89DDFF;">&quot;</span><span style="color:#C3E88D;">option-title</span><span style="color:#89DDFF;">&quot;</span><span style="color:#89DDFF;">&gt;</span></span>
<span class="line"><span style="color:#A6ACCD;">                    </span><span style="color:#FFCB6B;">Hide</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">maxed</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">challenges</span></span>
<span class="line"><span style="color:#A6ACCD;">                    </span><span style="color:#89DDFF;">&lt;</span><span style="color:#FFCB6B;">desc</span><span style="color:#89DDFF;">&gt;</span><span style="color:#FFCB6B;">Hide</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">challenges</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">that</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">have</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">been</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">fully</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">completed</span><span style="color:#89DDFF;">.&lt;</span><span style="color:#A6ACCD;">/</span><span style="color:#FFCB6B;">desc</span><span style="color:#89DDFF;">&gt;</span></span>
<span class="line"><span style="color:#A6ACCD;">                </span><span style="color:#89DDFF;">&lt;</span><span style="color:#A6ACCD;">/</span><span style="color:#FFCB6B;">span</span><span style="color:#89DDFF;">&gt;</span></span>
<span class="line"><span style="color:#A6ACCD;">            ))</span><span style="color:#89DDFF;">}</span></span>
<span class="line"><span style="color:#A6ACCD;">            </span><span style="color:#A6ACCD;font-style:italic;">onUpdate</span><span style="color:#89DDFF;">:</span><span style="color:#FFCB6B;">modelValue</span><span style="color:#89DDFF;">={</span><span style="color:#A6ACCD;font-style:italic;">value</span><span style="color:#A6ACCD;"> </span><span style="color:#C792EA;">=&gt;</span><span style="color:#A6ACCD;"> (settings</span><span style="color:#89DDFF;">.</span><span style="color:#A6ACCD;">hideChallenges </span><span style="color:#89DDFF;">=</span><span style="color:#A6ACCD;"> value)</span><span style="color:#89DDFF;">}</span></span>
<span class="line"><span style="color:#A6ACCD;">            modelValue</span><span style="color:#89DDFF;">={</span><span style="color:#A6ACCD;">settings.hideChallenges</span><span style="color:#89DDFF;">}</span></span>
<span class="line"><span style="color:#A6ACCD;">        </span><span style="color:#89DDFF;">/&gt;</span></span>
<span class="line"><span style="color:#A6ACCD;">    ))</span></span>
<span class="line"><span style="color:#A6ACCD;">)</span><span style="color:#89DDFF;">;</span></span></code></pre></div><h2 id="updating-features" tabindex="-1">Updating Features <a class="header-anchor" href="#updating-features" aria-label="Permalink to &quot;Updating Features&quot;">​</a></h2><p>If your custom feature requires running some sort of update method every tick, you&#39;ll want to search layers when they&#39;re added for any features of this type (using the <a href="/api/modules/features/feature#findfeatures">findFeatures</a> utility), add an event handler for every <code>update</code>/<code>postUpdate</code>/<code>preUpdate</code>, and clean it up when the layer is removed. Here&#39;s how this looks like for the <code>action</code> feature:</p><div class="language-ts"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki material-theme-palenight has-diff"><code><span class="line"><span style="color:#C792EA;">const</span><span style="color:#A6ACCD;"> listeners</span><span style="color:#89DDFF;">:</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">Record</span><span style="color:#89DDFF;">&lt;</span><span style="color:#FFCB6B;">string</span><span style="color:#89DDFF;">,</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">Unsubscribe</span><span style="color:#A6ACCD;"> </span><span style="color:#89DDFF;">|</span><span style="color:#A6ACCD;"> </span><span style="color:#FFCB6B;">undefined</span><span style="color:#89DDFF;">&gt;</span><span style="color:#A6ACCD;"> </span><span style="color:#89DDFF;">=</span><span style="color:#A6ACCD;"> </span><span style="color:#89DDFF;">{};</span></span>
<span class="line"><span style="color:#A6ACCD;">globalBus</span><span style="color:#89DDFF;">.</span><span style="color:#82AAFF;">on</span><span style="color:#A6ACCD;">(</span><span style="color:#89DDFF;">&quot;</span><span style="color:#C3E88D;">addLayer</span><span style="color:#89DDFF;">&quot;</span><span style="color:#89DDFF;">,</span><span style="color:#A6ACCD;"> </span><span style="color:#A6ACCD;font-style:italic;">layer</span><span style="color:#A6ACCD;"> </span><span style="color:#C792EA;">=&gt;</span><span style="color:#A6ACCD;"> </span><span style="color:#89DDFF;">{</span></span>
<span class="line"><span style="color:#F07178;">    </span><span style="color:#C792EA;">const</span><span style="color:#F07178;"> </span><span style="color:#A6ACCD;">actions</span><span style="color:#89DDFF;">:</span><span style="color:#F07178;"> </span><span style="color:#FFCB6B;">GenericAction</span><span style="color:#F07178;">[] </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#82AAFF;">findFeatures</span><span style="color:#F07178;">(</span><span style="color:#A6ACCD;">layer</span><span style="color:#89DDFF;">,</span><span style="color:#F07178;"> </span><span style="color:#A6ACCD;">ActionType</span><span style="color:#F07178;">) </span><span style="color:#89DDFF;font-style:italic;">as</span><span style="color:#F07178;"> </span><span style="color:#FFCB6B;">GenericAction</span><span style="color:#F07178;">[]</span><span style="color:#89DDFF;">;</span></span>
<span class="line"><span style="color:#F07178;">    </span><span style="color:#A6ACCD;">listeners</span><span style="color:#F07178;">[</span><span style="color:#A6ACCD;">layer</span><span style="color:#89DDFF;">.</span><span style="color:#A6ACCD;">id</span><span style="color:#F07178;">] </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#A6ACCD;">layer</span><span style="color:#89DDFF;">.</span><span style="color:#82AAFF;">on</span><span style="color:#F07178;">(</span><span style="color:#89DDFF;">&quot;</span><span style="color:#C3E88D;">postUpdate</span><span style="color:#89DDFF;">&quot;</span><span style="color:#89DDFF;">,</span><span style="color:#F07178;"> </span><span style="color:#A6ACCD;font-style:italic;">diff</span><span style="color:#F07178;"> </span><span style="color:#C792EA;">=&gt;</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">{</span></span>
<span class="line"><span style="color:#F07178;">        </span><span style="color:#A6ACCD;">actions</span><span style="color:#89DDFF;">.</span><span style="color:#82AAFF;">forEach</span><span style="color:#F07178;">(</span><span style="color:#A6ACCD;font-style:italic;">action</span><span style="color:#F07178;"> </span><span style="color:#C792EA;">=&gt;</span><span style="color:#F07178;"> </span><span style="color:#A6ACCD;">action</span><span style="color:#89DDFF;">.</span><span style="color:#82AAFF;">update</span><span style="color:#F07178;">(</span><span style="color:#A6ACCD;">diff</span><span style="color:#F07178;">))</span><span style="color:#89DDFF;">;</span></span>
<span class="line"><span style="color:#F07178;">    </span><span style="color:#89DDFF;">}</span><span style="color:#F07178;">)</span><span style="color:#89DDFF;">;</span></span>
<span class="line"><span style="color:#89DDFF;">}</span><span style="color:#A6ACCD;">)</span><span style="color:#89DDFF;">;</span></span>
<span class="line"><span style="color:#A6ACCD;">globalBus</span><span style="color:#89DDFF;">.</span><span style="color:#82AAFF;">on</span><span style="color:#A6ACCD;">(</span><span style="color:#89DDFF;">&quot;</span><span style="color:#C3E88D;">removeLayer</span><span style="color:#89DDFF;">&quot;</span><span style="color:#89DDFF;">,</span><span style="color:#A6ACCD;"> </span><span style="color:#A6ACCD;font-style:italic;">layer</span><span style="color:#A6ACCD;"> </span><span style="color:#C792EA;">=&gt;</span><span style="color:#A6ACCD;"> </span><span style="color:#89DDFF;">{</span></span>
<span class="line"><span style="color:#89DDFF;">    </span><span style="color:#676E95;font-style:italic;">// unsubscribe from postUpdate</span></span>
<span class="line"><span style="color:#F07178;">    </span><span style="color:#A6ACCD;">listeners</span><span style="color:#F07178;">[</span><span style="color:#A6ACCD;">layer</span><span style="color:#89DDFF;">.</span><span style="color:#A6ACCD;">id</span><span style="color:#F07178;">]</span><span style="color:#89DDFF;">?.</span><span style="color:#F07178;">()</span><span style="color:#89DDFF;">;</span></span>
<span class="line"><span style="color:#F07178;">    </span><span style="color:#A6ACCD;">listeners</span><span style="color:#F07178;">[</span><span style="color:#A6ACCD;">layer</span><span style="color:#89DDFF;">.</span><span style="color:#A6ACCD;">id</span><span style="color:#F07178;">] </span><span style="color:#89DDFF;">=</span><span style="color:#F07178;"> </span><span style="color:#89DDFF;">undefined;</span></span>
<span class="line"><span style="color:#89DDFF;">}</span><span style="color:#A6ACCD;">)</span><span style="color:#89DDFF;">;</span></span></code></pre></div>`,19),l=[t];function p(r,c,i,y,F,D){return a(),e("div",null,l)}const C=s(o,[["render",p]]);export{d as __pageData,C as default};