Things to Avoid

Neos is a fantastic engine with a whole lot of power, options and capabilities. Some methods or practices can however be problematic or may lead to breakages at a later date. This is a general list of things to avoid or not do and the reasons behind them and some solutions or work arounds to assist you.

It is not meant to call out anyone or have any bad intentions etc. but is worth a read to understand where you might be able to improve your creations and to ensure that Neos updates or other users do not unintentionally end up in breaking things.

Summary

For a quick summary, if something feels hacky or undesirable please ask the community or the team if its a good idea or not. If there are problems or gaps within Neos that you'd like to see resolved please open an issue on our Issue Tracker.

Working around unsupported or not yet implemented features

Certain features that are yet to be implemented officially can be "hacked in" or achieved through modifying certain internal systems and properties. While we're ok with experimenting and toying around, please be aware that those approaches will very likely break, without guaranteed prior warning and official implementation in place.

This can leave you with broken content without ability to fix it until a much later point in the future, so we recommend avoiding such approaches in the first place and instead finding different method using already supported features.

You can find list of planned features on our official GitHub: https://github.com/Neos-Metaverse/NeosPublic/issues and vote on them so we prioritize them sooner. For any official features we always put a great care into ensuring long term content compatibility over implementing them quicker, to ensure that future Neos updates will keep your content functional.

If we close certain issue as something that we don't plan on implementing, we strongly advise against using hacks and workarounds to achieve that result completely, as those will be brittle and will break without replacement coming at all. In such cases you'll have to find a different approach that works with the design of the system to ensure long term compatibility.

Slot Names & Structure

Avoid relying on Slot names or structure for items and slots that you don’t own or control within your LogiX or components. The names of slots and their structure for items you don’t own or control may change at any time and this can break things you’ve made.

Here are some examples of where this may occur and some alternatives or suggestions to attempt to mitigate the issues

Names or Structure of a User Root

Items may be added or removed from the User Root with the addition of new features or updates to features. So try not to rely on this structure or naming conventions that these slots have. Additionally, do not rely on the ordering of these slots as they may change at any time.

Recently for example new Slots were added to a User root to cover the new "Freeform Camera".

Things to avoid in this area:

• Find Child By Name
• Repeated use of Get Parent / Get Child nodes to locate a slot using searching or understood hierarchy depths

Solutions for this area:

• Use the User Root Nodes to locate a user's slot.
• Use the User Nodes.

Names or Structure of an Avatar

Avatars are very complex creations.

Avoid:

• Find Child By Name to locate avatar parts
• Repeated use of Get Parent / Get Child nodes to locate avatar parts
• Assuming the structure of an avatar
  • For example, head and hands avatars don't have an "Avatar Root"

Solutions in this area:

• Use the Avatar Nodes.

If you’d like to routinely find or acquire a slot in the User Root, consider requesting a new node or feature for it on our Issue Tracker.

Names or Structures of Other People’s Worlds

When visiting other user’s worlds it is very important to remember that you are a guest in their space. When creating gadgets, tools and avatars you should try to be respectful of their world.

Things to avoid:

• Placing items in the root from Guns/Rockets and other items.
• Assuming the setup of the world is standard in terms of hierarchy for things like spawn or lights etc.
• Custom Culling systems or locomotion modules
• Avoid Calling Dynamic Impulses to the Root Slot
• Avoid placing Dynamic Variables in the Root Slot or World Variable Space
• Avoid leaving items in the world when you leave. Clean up after yourself.
  • Temporary items from Guns/Rockets & Particles should clean up after themselves. Consider marking them as non-persistent or setting them to delete themselves when you leave.

Solutions:

• When using the Set Parent node with a Root Slot Parent, Instead Supply a “Local User Space” node this will function identically in most cases but will keep items parented correctly to any world management systems rather than littering the root.
• Ask the world owner before spawning complex gadgets or modifying the world root.

Components

Forcing Auto-Disabled Components to be Enabled

Occasionally when using a component you may find that it disables itself. This usually means that something in the component setup or the slot that it was added to is problematic and would cause the component to fail to function.

• Do not drive the enabled checkbox/field to true in these cases
• Consider reporting a bug on our Issue Tracker. These situations may be a problem that can be resolved.
• Sometimes, these are actual miss-use of a component and may not be fixed.
• Properties within components that start with _ may be changed or removed at anytime and should be avoided where possible.

Reference IDs / "Ref Hacking"

When building in Neos, it may be desirable to use reference ids to get around certain restrictions or feature gaps that exist within Neos. When doing this keep the following in mind:

• Reference IDs may change at any time.
• Certain uses of References may be considered a security issue and be fixed without much notice.
  • If you notice something concerning please make a report on our Moderation System.

Generally, you should use dedicated nodes and concepts instead such as:

• The Allocating User Node
• Typed References and Casts

If you find yourself continually needing to use a certain reference id or path consider making a feature request on our Issue Tracker.

LogiX

Using the ToString Node on Complex Data Types

When using the ToString node on non-primitive data types(e.g. NOT float, int, double etc), do not rely on the output of the node. It may change or be updated at any time. This includes things such as Data Types, Users, Slots etc.

Comparing strings for these items is brittle and may change with Neos Updates.

Instead:

• For Users, use User Root Nodes or User Nodes.
• For Slots, use Slots Nodes.
• For Types, use the Type nodes.

If you find yourself continually needing to do this, consider making a feature request on our Issue Tracker.

Using Fire On True etc. when there are better alternatives

Several nodes in the Flow category can fire impulses when specific values change, e.g. Fire On True, Fire On False, Fire While True etc. These can be very powerful and are fine to use where they're the best solution for a specific use case. However, there are a few common situations where they may seem like a good option, but there are actually much better and more efficient alternatives.

In cases where e.g. Fire On True is appropriate, it is also advisable to provide a user value to the UpdatingUser input on these nodes rather than leaving it empty.

Buttons

Often users want to make something happen, for example changing a value or causing some LogiX to trigger, when a button is pressed.

Avoid:

• Using e.g. the IsPressed bool field on the various button components and to providing that as the input to Fire On True in order to fire LogiX impulses.

Instead:

• Use the dedicated node for this purpose, Button Events. This is more efficient and impulses can be fired when various different things happen with the given button (Pressed, Pressing, Released etc.).
  • ProbablePrime has produced a short tutorial on how to use this node here.
• If you only want to perform a simple action based on a button press, such as changing a value, consider the components in the Common UI > Button Interactions category. These can often replace simple actions you might otherwise perform with LogiX.
  • ProbablePrime has tutorials for several of these components - ButtonValueCycle, ButtonValueShift, ButtonValueSet, ButtonToggle.

Note that:

• It is reasonable to use the IsPressed bool for some effects which may be related to the button press state, such as driving the color of the button based on whether it is pressed or not.

Tooltips

Grabbable items can be made equippable by adding the RawDataTooltip component. This allows users to make custom tooltips, weapons, and gadgets which can be programmed to perform actions based on controller button presses much like the standard Neos tooltips.

Avoid:

• Using e.g. the Primary or Secondary bool fields on the RawDataTooltip component with Fire On True in order to fire LogiX impulses.

Instead:

• Use the dedicated node for this purpose, RawDataTooltip Events. This is more efficient and impulses can be fired when various different things happen when a RawDataTooltip is equipped.

Note that:

• It is reasonable to use the Primary and Secondary bool fields for some effects which may be related to when a user presses a controller button, such as driving the color of the eqipped item based on whether the user is pressing primary fire.

Graphics

Material "Stacking"

When creating visual effects in Neos you can add multiple material slots to a Mesh Renderer to stack materials on-top of each other. This can have a great visual effect but it may break at a later date. Wherever possible, you should avoid doing this.

Instead:

• Create Multiple Mesh Renderers in the same location each with a different material. This will lead to the same effect.
• Try experimenting with different material types available to you in Neos.
• Consider opening a Feature Request for the effect you're looking at.

Notes:

• This does not affect meshes with multiple material slots. For example Avatars. It just refers to using the same material slot used multiple times.
• For more information on this see this GitHub Issue.

Assets

Using .7zbson/json/bson

Within Neos items, avatars, gadgets and even worlds are sometimes stored in a variety of files that are usually some form of JSON, Binary JSON or Compressed variants of them. There are a few methods available which allow you to gain access to these files in these forms and these files can then be used to import, edit, save, backup etc Neos Items and Assets.

While this may seem handy and desirable to use, it unfortunately may break at any time for a number of reasons:

• Neos' format or structure for these assets may change.
• Neos may introduce/remove components within these files causing incompatibility.
• These files often refer or cross-link to other files which may be removed or changed further increasing the chance of incompatibility.

It is therefore not recommended to use this approach. It is not a supported feature.

Using Keyboard Components/Nodes to Spawn Items (Cloud Spawning)

By combining multiple Keyboard related components it is possible to trigger the spawning of an item from Neos' cloud. This usually uses a URL which points to a Neos Item or asset. While doing this can provide a good experience it is not something that is supported long term. This functionality may break or become non-functional at a later date.

This functionality is commonly known as "Cloud Spawning" right now but it isn't. Cloud Spawning is actually a feature that Neos plans to support in the future

Instead of this, please continue to vote on the ability to do this natively with LogiX.

Inventory

Long/Complex Folder Names

When creating folders within your inventory, you may be tempted to use very long folder names or names which contain ASCII Art. Doing this is not recommended as it may not display the same on all platforms and will cause navigational and technical issues in some areas. Additionally when inventory management/searching is added in the future it may cause issues with searching or indexing your inventory.

Emojis and a few RTF Formatting tags(such as changing the color) are ok though. Just do not overuse them.