PhotonDust - new particle system testing - Phase 2 (compatibility)

[Frooxius]

Hello everyone!

We're now ready to move to the second phase of PhotonDust testing since things seem to be pretty stable from phase 1! Just to recap, the testing is divided into two phases:

• Phase 1 - stability testing (this one is done!)
• Phase 2 - compatibility testing

This testing is for Phase 2

Build Version

Use latest build on main branch!

What is being tested

As part of our performance optimizations, we are replacing the existing (now called "Legacy") particle system in Resonite with our custom one called PhotonDust.

The legacy particle system is a hybrid between Unity and FrooxEngine, with Unity handling most of the simulation. This tight integration prevents moving FrooxEngine from being moved out of Unity into a more performant .NET 9 process. PhotonDust solves this problem, by handling most parts of the simulation completely within FrooxEngine and only submitting simulated results to Unity for rendering.

Since this introduces a new complex system to Resonite, this has potential to cause stability issues (though most were eliminated during development itself) and content compatibility issues - our system works on different principles from the original particle system - it is a lot more modular and flexible. This requires adapters to support existing content.

You can learn a bit more about PhotonDust here:
#587

General testing notes

• The new particle system is called just "Particle System"
• The old particle system is now called "Legacy Particle System"
• During testing, any existing content will keep using the old "Legacy Particle System" by default
• You can create new instances of PhotonDust as well as the old particle system - both systems exist independently in these builds

Converting old content

• You can turn on conversion of old content in the Settings -> Misc -> Debug -> Convert particle system to PhotonDust
• After this setting is enabled, any legacy particle systems on items loaded inventory items, avatars & worlds by you will be converted to PhotonDust
• The setting doesn't affect items and worlds loaded by other users

Avoiding data corruption

• DO NOT save any converted worlds/items for any purpose other than testing - they might break or have conversion issues!
• DO NOT build any long term content with PhotonDust yet - there might be breaking changes during testing and your content will break

How to test

In the Phase 2 we focus on compatibility of the new system with old content and making sure it converts properly. I recommend testing wide variety of items, avatars and worlds that feature particle systems, converting them to the new system and checking if they look similar enough or if there's breakage!

Currently I'm keeping the build still on the prerelease branch, but this will be merged into main starting next week - since both systems can co-exist next to each other, we can test on the public builds.

• On Steam, switch to the prerelease branch and make sure the build updates before you run it
• Make sure your build version matches the one at the top of this message

What to test

• Enable the conversion of particle systems to PhotonDust in settings and spawn items, avatars, tools, gadgets or load entire worlds
• Test those items and see if the particles look the same (or very close) as they do on an unconverted item (remember, you can toggle the conversion back and forth right before you load an item, so you can test them side by side!)

It's also good to just mess with the new system from scratch to potentially catch more errors as well with the particle systems:

• Create new instances of the new particle system and mess around with them
• Try different modules and settings (trails, lights, billboard & mesh particles...)
• Delete the instances and modules

What to watch out for

These are good things to watch out for when testing the new particle system:

• Converted particle systems behaving differently from unconverted
• Sessions crashing
• Client crashing
• Freezing or locking up
• Severe performance drop with typical setups (meaning if you make a >million particles then performance drop is somewhat expected and probably shouldn't report that)

What NOT to test & report

• Generally things that do not involve this system - any existing unrelated bugs with components and other systems.
  -- If you're unsure, try to replicate the issue on the main build and see if it also occurs - if it also happens there, just report it as normal bug

If you find something that got broken

• Create a GitHub issue for a pre-release bug: https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/new?assignees=shiftyscales&labels=prerelease&projects=&template=prerelease.yml
• Make sure to include the log
• Please include description of what happened. Be succinct, but exact.

IMPORTANT: For compatibility issues

• Try to isolate where is the difference in behavior coming from as much as you can in the report
• Make sure to include screenshots/video of both unconverted & converted behavior
• Please provide us unconverted copy of the item for testing
• You can strip down the item to just the minimum particle system that still replicates the issue (in fact, this is preferable!):
  -- Strip the unconverted item down as much as possible
  -- Save the stripped down item to your inventory
  -- Turn on conversion
  -- Check if the issue still persists on the converted item

If you find that stuff works okay

Please report it too and include details on what you generally tested, so we know things are okay. You don't need to make a new issue for this - just a comment in this Discussion is fine.

This lets us know that a bunch of stuff was tested and get better confidence that stuff won't break with release.

How long will testing go for?

This will depend on how many compatibility issues we'll find and how complex they are, so right now it's difficult to say. We'll keep testing until majority of items work correctly.

It's possible that we'll keep some minor differences in behavior, but this will depend on the issues we find.

The builds will remain on prerelease branch until next week. After that they'll be merged to main and we'll continue testing there.

[epicEaston197]

So far I've noticed that gravity is not converted correctly, particles move slower, trails are completely broken and Mesh particles seem to be way more intensive on performance all with the conversion

[Frooxius]

Please read the reporting instructions for compatibility and follow those.

[AegisTheWolf]

just made one now #3284 , it should catch some potential conversion issues, unless im missing a component i did not know i need to add to a particle system then even better it isnt broken the way i thought it be.

[epicEaston197]

Here's the item that I've been using to submit bug reports (Discord link because I can't actually upload the zip file here)
Hopefully this will be helpful to someone that's reporting issues

(Photo epilepsy warning)

もぺもぺほう - Layer.resonitepackage

[jae1911]

I've been playing with PD, and I would have one bit of feedback so far:

It would be nice if modules were organized in folders within the Modules one in the component picker.
For instance, everything about trails would be under a Trails one and so on. I think it would be easier that way to find modules since for instance, ParticlesTrailsModule is nowhere near the Trails* options and therefore harder to find (and easier to forget to put into the ParticleStyle).

Otherwise, other than #3295, all my existing stuff converted correctly to PD.

[Frooxius]

Yes, you make a good point. I wanted to sub-organize them too during development, I just never got around to it.

I'm not sure if I should do it by type (what, they affect - color/size/rotation) or when they act (initializers/simulators).

Or maybe type first and then when they act?

[jae1911]

I think sorting them by Type first would make the most sense and would already help a lot.

[epicEaston197]

A quote @orange3134 from issue #3304 (comment)

I noticed that the behavior is different when converting from inventory and when converting from ResonitePackage.

This is gonna make testing this a little harder Because I'm using packages for my testing entirely I don't use my inventory
I am using packages because I want to make sure that the video that I Upload matches the same behavior when someone imports the package for consistency reasons this bug might exaggerate conversion behavior

[Frooxius]

Hmm this is a bit strange, because all things being the same, it should be the same for both.

I'd actually document the difference between the two if you can, because there shouldn't be one in the first place.

[Frooxius]

2024.12.13.1342 [PRE-RELEASE]
A few more fixes + a new VelocityDrag module (this was super quick to add with this new system)!

This clears out most of the remaining issues for PhotonDust! I'm keeping this on prerelease branch, since I missed the window to push yesterday and I don't want to be making a big push right on Friday, so you'll need to test over there still.

THIS BUILD IS IF TESTING PURPOSES ONLY! If you'd like to help test, please read the instructions here: #3276

You can also see the progress of the issues here: https://github.com/orgs/Yellow-Dog-Man/projects/42/views/1

New Features:

• Added VelocityDrag module for PhotonDust (requested by @AlphaNeon, issue PhotonDust - Particle Drag Support #3288)
  -- This allows you to apply drag to particles, which slows them down over time
• Exposed RibbonPointRatio, Distribution and MaxRibbonPoints on ParticleRibbonsModule
  -- This allows you to control how many particles will be part of ribbons
  -- The value for MaxRibbonPoints is set conservatively high for legacy particle system (this fixes ribbons getting interrupted, reported by @Zozokasu, issue PhotonDust - Ribbon is intrrupted #3279)

Tweaks:

• Static mesh providers are now automatically marked as Readable when assigned as mesh particle (based on report by @Qualium, issue [PhotonDust] MeshParticleRenderer will not render static meshes, only procedural meshes #3348)

Fixes:

• Fix exceptions in particle system renderers when they are destroyed while data is still being submitted
  -- This fixes heavy performance degradation in asset integration particularly in cases where particle systems are rapidly created and destroyed (reported by @ModernBalloonie, issue PhotonDust - When particle systems with lights are duplicated and deleted fast, it causes the dashboard and UI to become inoperable. #3293)

[Frooxius]

PhotonDust is now merged into the main branch, but testing still continues! At the moment, it exists alongside the legacy particle system.

Once we polish up the remaining issues, following will happen:

• Experimental label will be removed
• Legacy particle system will be removed
• Conversion will be made automatic

[Frooxius]

Exiting the experimental phase soon

Hey everyone!

Right now, majority of the reported issues with PhotonDust have been resolved: https://github.com/orgs/Yellow-Dog-Man/projects/42/views/1

With PhotonDust getting stable now and not many new issues appearing, I'm now considering taking it out of the experimental phase soon. However before I do that, I wanted to give everyone a heads-up.

What will happen

• Experimental label on PhotonDust will be removed and it will now be stable and okay to use in new projects
• Conversion from Legacy -> PhotonDust will become automatic
• Legacy Particle System will be removed completely
• This phase of performance update will be considered done and we'll move to the next one (Audio System)

Before I take it out of the experimental phase, I'm giving it a few more days to see if more issues appear. If you ran into an issue, please make your issue soon!

We'll be able to fix issues afterwards too, but it'll be harder to make side-by-side comparisons once the legacy system is removed.

[Frooxius]

I'm closing this one! We'll do a quick and final phase of PhotonDust, will open issue soon!