From Neos Wiki
Jump to navigation Jump to search
This page contains changes which are not marked for translation.
Other languages:

Neos is a complex piece of early access 'beta' software which is under very active development. As such, occasional bugs or usability issues are to be expected. Everyone can help improve the Neos experience by reporting problems or providing ideas.

This page deals with the process of reporting technical issues or making suggestions for the development of the Neos platform. For information on identifying and dealing with problems related to other users' behaviour, see the Guidelines and Moderation pages.

The Neos development team depends on the community to provide high-quality feedback to help find and address problems. We can make the job of Frooxius and the other programmers easier by using the appropriate channels and formats to raise issues. This is best for everyone involved as it makes it more likely that bugfixes or new features can be implemented quickly. It also helps helps focus developer resources and attention most efficiently.

Feedback Guidelines

Generally users should not contact Frooxius directly about issues or suggestions. The following steps are the best approaches for providing feedback in the most useful manner, depending on the situation.

Reporting security vulnerabilities or exploits

If you think you have found an exploit which could be used to cause harm, e.g. to steal private assets or spread malicious software:

  1. Do not discuss the issue with other users, including on Discord or GitHub!
    • This helps to reduce the possibility that someone could cause damage before the problem can be fixed.
  2. It is best to immediately tell a Moderator, especially if you think someone is actively using the exploit.
  3. Such issues should be confidentially reported by sending a direct message to the Neos Team member Shifty on Discord. You can alternatively open a ticket on the official Neos moderation webpage.

Serious exploits and security vulnerabilities are dealt with as quickly as possible.

Reporting bugs or problems

If you think you have found a bug or a situation where Neos does not work properly:

  1. Search to see whether the problem has already been reported on the Neos GitHub issue tracker.
    • If there is an existing issue, you can react with a 👍 to indicate that it is relevant to you. You can also contribute to the discussion by leaving a comment if there are extra details you think may be helpful - try to write in clear English and stay focused on the specific issue topic. Additionally, Patreon supporters can indicate that an issue is a particular priority for them (see Patreon priority support).
  2. Search to see if the problem has been discussed before in the #❓questions-help or #🐜bugs-and-feedback channels on the official Neos Discord server.
    • If the issue has not been brought up before, or you are unsure whether something is a bug or 'working as intended', posting about it in Discord is a good way to get feedback. It can be helpful to get suggestions from others and to find out whether the problem is affecting multiple people.
  3. Once you are confident you have found a bug, the best way to notify the developers is to create a GitHub issue using the 'Bug' template. See the #Github section for information on writing good GitHub issues.
    • Understandably, some users may not be familiar with GitHub and may not feel comfortable opening issues. If you would like help reporting an issue, please ask in the #🐜bugs-and-feedback channel or speak to a Moderator.

Feature requests or suggestions

If you want to suggest ideas for new features or tweaks to current ones:

  1. Check to see whether your idea is already on the Neos development roadmap.
  2. Search to see whether a similar suggestion has already been raised on the Neos GitHub issue tracker. Many features on the roadmap also have open GitHub issues.

Hopefully your idea is already on the roadmap, or has an associated GitHub issue, which means it's already being considered by the Neos team! If you would like to show your support, you can react with a 👍 on the relevant GitHub issue. You can also contribute to the discussion by leaving a comment - try to write in clear English and stay focused on the specific issue topic. Additionally, Patreon supporters can indicate that an issue is a particular priority for them (see Patreon priority support).

If you didn't find your suggestion by 1. or 2.:

  1. Make a post in the #💡ideas channel on the official Neos Discord server. Discord has nice search features and is helpful to check to see whether the point has been raised before. This channel is a great place to discuss possible features and get additional perspectives.
  2. Create an issue on GitHub using the 'Feature request' or 'Tweak' templates - whichever is most appropriate. See the #Github section for information on writing good GitHub issues.

Issue priority

After creating a GitHub issue try to remain patient. There are many different features and issues that the team would like to implement or fix, but only a few can be worked on at any particular time. There are several factors that determine the priority:

  • Severity: If it’s something with serious global impact on usability or security of users, it will be very high on the list.
  • Demand: The more people request a given feature or issue to be fixed, the higher its priority. This changes over time, so don’t hesitate to add your voice even if it was already requested. Becoming a supporter or donating will give your requests higher priority as it helps grow and support our team.
  • Complexity: Some things are significantly quicker to implement/fix than others. If something is a trivial fix it might get addressed very quickly even though it doesn’t have as high demand or severity.
  • Prerequisites: Certain features or issues cannot be (efficiently) addressed without other, much bigger features or architectural changes done first. Our goal is long term sustainability and stability of the codebase, so certain things can take a lot longer to get addressed despite the demand. We will try to communicate whenever this is the case.

Usually GitHub issues will receive a response within a few days from the development team or other experienced Neos users. However sometimes things are missed - if your issue has not received any attention after a couple of weeks, it is resonable to make a comment under the issue politely requesting further information.


GitHub is a very popular website used to support the development of software projects. For Neos, GitHub is used to collect feedback and issue reports such that they can properly tracked and dealt with. When issues are created or updated in the Neos GitHub repository, a bot links to them in the #🐱github-feed channel on the Neos Discord server. The Neos Quality Control Lead, Shifty, has written about creating good GitHub issues in a weekly annoucement post and Turk has published a video tutorial too.

In order to use GitHub and interact with issues, users need to first make a free GitHub account. It is then helpful to read through the readme, much of which is also copied here.

Users should always search for pre-existing issues before creating new ones. GitHub has powerful search functionality - you can either use pre-defined filters using the 'Filters' dropdown menu (to the left of the search bar) or use the more complex syntax documented here. It is most efficient to keep all information and discussion for specific topics in a single issue thread. If you happen to create a duplicate issue, don't worry - these will generally be closed by one of the users who help moderate GitHub. Users are welcome to then contribute to the older post.

To create a new issue, click on the green 'New issue' button. You will then be presented with a choice of templates, pick the most appropriate for the information you would like to share.

Creating good GitHub issues

Three keys to a good issue report are as follows:

  1. Clarity: Be sure to report the issue in a clear, and concise way.
  2. Replicability: List a simplified series of steps required to replicate the issue.
  3. Objectivity: Try to keep reports objective, and highlight the underlying issue first. Suggestions for how to resolve it are welcome, but should be secondary to identifying the issue.

Keep the following points in mind:

  • Be as descriptive as possible. Explain what happened prior to problem, what the problem looks like and what you expected instead. The better the description, the less discussion will be needed and the greater likelihood of getting the issue solved.
  • If you experience a problem, make sure it’s reported, either by you, a Mentor or Moderator, or Shifty. If you simply wait for someone else to report it instead or the developers to notice themselves, it might not get fixed for a long time (or at all).
  • See if you can find a way to reliably replicate the bug. If you can help the developers easily reproduce the bug on their end, it significantly helps with its resolution.
  • If you experienced a bug, including the log files can significantly help in resolving the issue. See the FAQ for where to find the logs.
  • If you have crashed, frozen, or encountered hardware issue, include the additional Unity log as well.
  • If you have crashed or frozen, check for crash dumps and include those too.
  • Sometimes bugs can be accidentally introduced, or made worse, by a specific update. #Regression Testing has information on how you can test and collect evidence in these cases. It is useful to narrow down exactly which build was associated with an issue appearing.
  • Even if your exact suggestion isn’t eventually implemented, it’s still very useful to report it. This helps the developers understand what issues users are dealing with and incorporate those into future decisions, or address the problem in an alternate way.
  • Please keep issues on topic and conversation calm and factual. Bringing emotion makes issues harder to deal with and will only hurt their resolution and impact our overall development speed. Remember, the developers are human as well!

The issue resolution process

After creating a GitHub issue, any users with a GitHub account will be able to add comments and other information in the thread. You may be asked to clarify certain points or to provide additional information, such as log files. Responding quickly, clearly, and calmly helps everyone work towards the best resolution. Tags may be added to the issue to help categorize it. For example, the 'Needs more information' tag may be added when the developers don't fully understand the problem or don't have enough information to replicate it. Tags such as 'Bug', 'Tweak', or 'Feature request' are automatically added after creating an issue with the respective template.

Sometimes the developers or other users may make suggestions of alternatives or workarounds for dealing with the problem; this doesn't necessarily mean that they don't like a proposal or that they don't think your issue is really a problem. Often they will be trying to help you deal with the problem temporarily until a proper fix can be found. However, it is possible that people may disagree about problems or solutions, or misunderstandings may arise. That's alright - as long as everyone remains calm and respectful, the discussion is healthy and can even lead to a better solution than the issue author first expected!

When an issue is considered resolved, the issue will usually be closed on GitHub. After being closed, an issue still exists and can still be commented upon or reopened if a fix was insufficient.

Generally the developers will try to take all feedback into account, though there may be times when the developers state that an issue will not be addressed, or will not be solved in the requested way. Usually they will try to provide an explanation for why the have made such a decision. Having an issue closed without being fixed or without an obvious resolution may be difficult to understand; it is acceptable to politely ask for clarification as to why a decision was made or to calmly argue your case. Ultimately the developers' decisions are final.

Dealing with asset import problems

Neos can support many different assets types (e.g. models, audio, images etc.) natively. However, due to the wide variety of models, rigs and file types, not all of them will import correctly. You might encounter things like:

  • Vertices being randomly messed up, stretching where they shouldn’t (either with static model or when using blendshapes)
  • Model failing to import at all or crashing Neos
  • Fingers being mangled after avatar is equppiped

Such issues can be reported in the usual ways (#🐜bugs-and-feedback and GitHub). In these cases, if you can share the model file itself, send it over to developers for testing. This significantly increases the chance of the issue being fixed, as they can analyze what is going wrong with the file.

Regression Testing

Modern software projects, such as Neos, are extremely complicated with many interdependent parts. When fixing bugs or adding new features, unexpected problems can occur and other features may break or stop working properly. These are called "regressions". When solving regression issues it is extremely helpful to know exactly which Neos version introduced the problem. The following approaches can be used to determine in which build a problem first arose.

Reverting to the previous build

If you think the most recent update caused a regression, it is possible to revert to the previous public build:

  • Find Neos VR in your Steam library sidebar.
  • Right click, and click on 'Properties' in the dropdown menu which will appear.
  • Select the 'BETAS' tab and select the previous-build option in the dropdown menu.

Note that generally you will be unable to join other users' sessions unless they are on the same build as you.

Reverting to older builds

There is no officially supported method to revert to builds older than the previous public release. However there are some online tools which can be used to do so. Note that these tools are not affilitated with Neos/Solirax or Steam/Valve and users download and use them at their own risk.

There is an unofficial repository of previous software builds for the Steam platform. Since Neos is primarily distributed via Steam, this can be used to access older versions of Neos - the relevant page is here.