Things to Avoid/ko

Summary

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. Feel free to continue using these features.

Items on this page are NOT against the Guidelines.

Wherever possible, it is recommended to avoid using these items though.

창작물을 개선하거나 또는 다른 사용자가 의도치 않은 문제를 발생 시키는 것을 막기 위해서 라도, 이 문서를 한번 쯤 읽어보시기 바랍니다.

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.name)과 구조는 임의로 바뀔 수 있으며, 동일한 이름이나 구조를 쓰는 전혀 상관없는 슬롯을 참조할 수 도 있습니다.

아래에서 관련 예제와 문제 완화를 위한 방법과 대안을 정리해 두었습니다.

User Root의 이름 또는 구조

네오스가 기능 업데이트를 하면서 User Root에 속한 아이템을 추가하거나 삭제할 수 있습니다. 이름이나 구조에 의존하면, 문제가 발생할 수 있습니다. 예를 들자면, 최근 추가된 "Freeform Camera"를 처리하기 위해 새로운 슬롯이 추가되었습니다. 공교롭게도 사용자가 업데이트 이전에 수동으로 추가한 이름과 동일하다면, 연계된 기능에 문제를 일으킬것입니다.

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

피해야 할 방법:

• Find Child By Name
• Get Parent 또는 Get Child 노드등을 반복적으로 사용하여 슬롯 구조를 탐색

해결방법:

• 사용자 슬롯 탐색은 User Root Nodes를 이용하세요.
• User Nodes를 이용하세요.

아바타의 이름이나 구조

아바타는 매우 복잡한 아이템 입니다.

피해야 할 것:

• 아바타의 파츠를 탐색하기 위해 Find Child By Name 노드를 사용
• 아바타 파츠 탐색을 위해 Get Parent 및 Get Child 노드를 반복적으로 사용
• 아바타의 구조를 가정하여 코드를 구성
  • 예를 들면, 머리와 손만 있는 아바타는 "Avatar Root"가 없습니다.

해결방법:

• Avatar Nodes 카테고리를 이용하세요.

만약, User Root에서 특정 슬롯을 간편하게 탐색하고 싶으시다면, 이슈트래커에 새로운 기능이나 노드를 요청하세요.

다른 월드의 이름이나 구조

다른 월드를 방문하면, 월드의 손님으로 입장하기에 해당 월드에서 장난감이나 도구, 아바타 등을 만들 때 월드를 존중해 주시기 바랍니다.

피해야 할 것:

• 총이나 로켓 또는 기타 아이템에서 유발되는 아이템들을 root 슬롯에 생성
• 모든 월드가 동일한 슬롯 구조를 가졌다고 상정
• 커스텀 컬링 및 로코모션 모듈 사용
• Root Slot을 Dynamic Impulse로 호출
• 월드 변수 영역 또는 Root Slot에 동적변수를 할당
• 월드를 떠날때, 널부러놓은 아이템 삭제

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.

Slot obfuscation / "Encryption"

Once you've made something in Neos you may want to protect it. When doing this don't:

• Rename Slots, LogiX Nodes etc.
• Move, scale, rotate slots
• Apply LogiX to your creation which does any of the above.

While, this may seem like a way to protect your creation it doesn't do much for a knowledgeable user who has Builder permissions. Regardless of your methodology any in-app obfuscation is relatively easy to break in this manner.

Instead:

• For Avatars: utilize Avatar protection systems such a Simple Avatar Protection
• Avoid setting users as Builder in a world you want protected
• Avoid spawning items in sessions with users you do not know or trust

We also have several items on our roadmap to aid in this area, we'd encourage you to follow their progress and to vote on them:

• Hard Permissions - Protects assets, items and LogiX within a World.
• Object ID / Licenses - Protects assets, avatars, items, worlds etc from being saved.

Avatars

Disabling key Avatar Components

Avatars are very complex things, please don't disable any of the key components that avatars need to function. If you find yourself doing this too often please open a GitHub issue or ask a question on our discord about the behaviour you are trying to achieve.

Disabling Raycasts on your Avatar

Neos has a lot of tools, gadgets and items which may affect your avatar. Things like Knockback guns, explosions, guns, tools that mess with your scale etc. are quite common. A solution to this which is common is for users to disable the ability for their avatar to respond to ray casts. While this works in principle it can cause game experiences and standard Neos components or systems to not function. This can reduce your quality of experience across Neos. It is also actually hiding a larger problem and this is culture and guidelines related.

Editing, messing with and affecting you or your avatar in a session without your consent is against the Guidelines. Users doing this might not be aware that what they are doing is wrong so please take the time to inform them about the importance of consent and our Guidelines. Should the behavior continue please utilize session moderation or if it repeated or particularly malicious please make a Moderation ticket.

자동 비활성화된 구성요소를 강제로 활성화

가끔 구성요소(컴포넌트)를 사용할때 자동으로 비활성화 되는 경우가 있습니다. 이는 구성요소의 설정이나 슬롯 등에 문제가 있어 동작할 수 없음을 의미합니다.

• 이런 경우, 활성화 관련 필드값을 True로 설정하지 마세요.
• 이슈트래커에 버그신고를 합니다. 많은 경우 해결 가능한 문제일 수 있습니다.
• 가끔 구성요소를 잘못 사용하여 문제가 발생할 수 있으며, 이런 유형은 오류가 아니므로 수정되지 않을 수 있습니다. 때때로 이는 구성 요소의 실제 오용이며 수정되지 않을 수 있습니다.
• 가끔 앞에 _이 붙는 속성은 동적으로 변경되거나 삭제될 수 있으므로 사용을 피하세요.

Reference IDs / "Ref 해킹"

네오스에서 참조ID(Reference ID)를 사용하여 기능제한이나 기능의 차이를 매우는 것이 바람직할 수 있습니다. 이 작업은 다음을 주의하여 주세요.

• 참조ID는 언제든지 변경될 수 있습니다.
• 어떤 참조는 보안 이슈를 유발할 수 있기에, 사전 알림 없이 패치될 수 있습니다.
  • 보안적 우려가 발견되면 중재시스템에 신고 해 주세요.

일반적으로 다음과 같은 전용 노드나 개념을 사용해야합니다:

• Allocating User 노드
• 자료형 참조들과 형변

어떠한 참조ID 또는 경로를 계속 사용해야 한다면, 이슈트래커에 요청을 해 주시기 바랍니다.

Depending on the order of Components

Components have an inherent order in which they appear in the inspector and are processed by Neos. However, this order should be considered non-deterministic as they are internally stored in an unordered collection. There are ways to modify that order, but it is not guaranteed that existing objects will indefinitely preserve that order. Therefore, creations that depend on the order of Components may break at any time.

An example of this is utilizing multiple button actions on the same button event that depend on being processed in a specific order.

Instead:

• Use LogiX impulses. LogiX is designed to be used for complex behaviors and program logic while components are generally intended for simple tasks. You can always depend on the order of operations in an impulse chain.

복잡한 자료형에 ToString 노드를 이용

기초 자료형(float, int, double 등)이 아닌 자료형의 출력을 ToString 노드에 연결하는 경우. 그 값이 업데이트로 인해 변경되거나 다른 값으로 바뀔 수 있으니 출력값에 의존하지 마세요.

이러한 자료형을 문자형으로 추출하여 비교한다거나 하는 로직은 잠재적인 오류를 포함하게 됩니다.

아래의 방법을 이용하세요:

• 사용자 비교는 User Root Nodes 또는User Nodes를 사용
• 슬롯 비교는 Slots Nodes를 사용
• 자료형 비교는 Type 노드를 사용

그럼에도 이런 작업을 해야 할 필요가 있다면, 이슈트래커에 기능을 요청해 두세요.

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.

• 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.

• 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 equipped item based on whether the user is pressing primary fire.

Combining multiple nodes into the same slot

When looking to optimize LogiX, you might be worried about how many slots a set of LogiX takes up and look to improve this by collapsing the nodes down into one slot. This usually needs a plugin and is referred to as "Mono-Packing".

While this does cut down on the slot count of LogiX, it makes the "mono-packed" LogiX difficult to edit, read and understand. Additionally, it makes the LogiX more difficult for Neos to optimize for you in the future.

Instead:

• Wait for additional Optimizations and enhancements to LogiX such as LogiX Functions.
• Consider looking into other Optimization techniques and sources such as the Optimization_Guidelines.
• Wait for a native equivalent which may allow for seamless unpacking/packing
• Remember that the Slot count of an object does not necessarily dictate how performant it is. Performance comes from a variety of sources and Slot count is just one.

Inspectors

Relying on/using the text found in inspectors

Sometimes within inspectors, you might find some useful information, such as in the "Ref Editor" component's inspector. Including(but not limited to):

• Running string comparisons/filtering/searching on Inspector UI component properties

Relying on the text is fragile and may break. Inspectors within Neos are due for serious amounts of re-working due to a number of features such as collections, hard permissions, The UI Update, component access etc. These changes may change the text that is shown in the inspector windows. So relying on the text here to remain the same across these updates is not recommended.

Instead:

• Wait for features such as component access which will allow you to use these fields directly rather than via string matching.

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.

Switching Neos DB URLs for Shaders

You may have noticed that you can swap URLs on StaticShader assets with URLs from other StaticShader assets with varying degrees of visual impact. This will break at a later date, particularly when custom shaders land with our upcoming graphics engine replacement. You should not rely on this for any sort of visual effect when producing your content.

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.

If you have one of these files and it is not able to be imported in a newer version of Neos, older versions of Neos will continue to work, so try using a version of Neos released before the date the file was modified.

Using Keyboard Components/Nodes to spawn items

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 using this method for "Cloud Spawning", 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.

Systems

Custom "Blocking" Systems

Neos currently does not have a User Blocking feature. This is a very high priority item for the team, which you can on GitHub.

While this lack of feature remains in Neos, some users have discovered ways to created Custom Blocking Systems inside Neos. These systems usually:

• Disable the User slot of "Blocked" users.
• Disable parts of "Blocked" users.
• Use other items, that are on this page to modify users etc.

While these systems provide safety and security for those who wish to block users, we do not recommend them and therefore they're on this page.

Such systems can cause the following issues:

• Session Crashes
• Neos Crashes
• Unsynchronized Sessions - Objects and values being out of sync or different for different users.
• Data Loss - Items/Worlds that are being created are at risk of being lost.

We understand that this is a problematic topic, but encourage everyone to follow our existing tooling in order to attempt to resolve the issues that might lead to blocking:

• Using standard session moderation features - Muting, Kicking, Banning
• Removing the user as a Neos Contact.
• Speaking to the session host to ask them to use session moderation features
• Creating a ticket on our Moderation Portal

You can read more about moderation on our dedicated Moderation page.