What is possible to do from IProcessSceneWithReport.OnProcessScene?

Edit: some Unity employee confirmed that the behaviour of being able to edit the scene that goes into the build without modifying it on disk is indeed intended behaviour. However, they warned that the modifications we do should only depend on the scene contents and always have the same result for the same scene contents.

Original post:

I'm wondering what kind of "stuff" is possible to do from IProcessSceneWithReport.OnProcessScene, specially regarding scene modifications. I have seen a couple posts suggesting it can modify the scene that is going into the build (or played in the editor), without modifying the scene asset on disk. This can be really useful, and indeed it works (I tested adding and removing objects on Unity 2019.1.5f1), but the documentation doesn't say anything about it, and I haven't seen any Unity devs saying anything about it, so it scares me to think that it may actually be undefined behaviour instead of intended...

I have sent feedback on the documentation page asking for documented clarification, but in the meantime, does anybody know?

 

I'm interested in this as well. I never actually took the time to test it out, but I always wondered whether it was possible and safe to do so.

 

Didn't take long to test. It's pretty much what you think. I took their sample script and extended it:

Code (csharp):

1. using UnityEditor;
2. using UnityEditor.Build;
3. using UnityEditor.Build.Reporting;
4. using UnityEngine;
5.  
6. class MyCustomBuildProcessor : IProcessSceneWithReport
7. {
8.     public int callbackOrder { get { return 0; } }
9.     public void OnProcessScene(UnityEngine.SceneManagement.Scene scene, BuildReport report)
10.     {
11.         Debug.Log("MyCustomBuildProcessor.OnProcessScene " + scene.name + " - STARTED!");
12.  
13.         if (scene.name.StartsWith("A"))
14.         {
15.             GameObject.CreatePrimitive(PrimitiveType.Cube);
16.         }
17.         else
18.         {
19.             GameObject.CreatePrimitive(PrimitiveType.Sphere);
20.         }
21.  
22.         Transform[] everything = GameObject.FindObjectsOfType<Transform>();
23.  
24.         Debug.Log("Contents of scene:");
25.  
26.         for (int i = 0; i < everything.Length; i++)
27.         {
28.             Debug.Log(System.String.Format("{0}. {1}", i, everything[i].name));
29.         }
30.  
31.         Debug.Log("MyCustomBuildProcessor.OnProcessScene " + scene.name + " - DONE!");
32.     }
33. }

I have two scenes in project:



And when I do a build, here is what the console contains. Note my added sphere and added cube, neither of which are permanently in the project (i.e., Scene files are unmodified on disk), but they HAVE been added to the built game.



And finally these are my two scenes as saved to disk:



Empirical observation for the big win!

 

@Kurt-Dekker Yes, I also did a test and found basically the same as you, but that's not really my question. What I want to know is if that's the intended behaviour, because I haven't seen any Unity documentation or developer saying it is. Since it's not documented as being one way or the other, what we are seeing could just be undefined behaviour, and if I start using it on a project, it could just break at any moment and leave me screwed... I prefer not to take my chances on behaviour not clearly documented.

 

I don't really understand what you expect here in the Scripting forum. What you find in the public API and in the documentation changes very rarely. Unity does not take public-facing API lightly.
If you want more precise documentation, it would be better to report the documentation page itself requesting better documentation. Or posting in the documentation forum.

 

As I said before, I already sent the request on the documentation page. What I'm doing here, until the documentation is updated (which may take long, or may never be done), is just asking if somebody (hoping it's some Unity dev) has actual knowledge about whether the behaviour is intended (and what other behaviour can be expected).

 

I agree with @Lurking-Ninja : Unity rarly changes stuff and almost always after a long period of deprecation. Just use the API if you need it, otherwise your're just wasting brain CPU cycles you could be spending designing your game!

ALSO, you are writing software... this means it is 'soft'... if an API goes away, you rewrite to use a new API, or you just remove the function. It's not like this fact is going to change because you pre-anticipated and thought about it extra long and hard in advance!

 

Relying on undefined behaviour is one of the worst ideas on development, talking from experience, both mine and others'. There's no deprecation, no API going away or changing, undefined behaviour is not part of an API, things can just stop working at any time with no warning, and not always being easy to solve. What I'm doing is not wasting brain cycles, but the opposite, I'm using just a few minutes of my time to avoid the possibility of wasting many hours.

If I sound rude I apologize, but all I'm asking is if somebody knows what the intended behaviour is, nothing more, nothing less, I think that it's a very fair question and that the knowledge will benefit other people.

 

From my understanding, he just wants to be absolutely sure that what he's tried and what has worked is exactly what this is supposed to be used for.

And I guess we all know how long it can take until the documentations content changes to something useful / reliable.
So it could make sense getting into those subforums where the coders hang out the most.

From the naming of that API, that's probably its intended use though. But well, "should be" or "is probably" is not as good as "it definitely is", i can understand the concerns.

The example in the docs is rather one of those examples that no serious developer needs. It just doesn't even show anything useful besides how to implement an interface and write a log.

They should've added textual content explaining what this is used for, to which extent one can use this to manipulate the scene.

 

Okay, so for no apparent reason, that parameter's name crossed my mind again and I thought, wait, BuildReport... sounds like the build task must be complete when this one is called, and I was afraid I had fallen for the trap the OP wanted to avoid.

Even though BuildReport is used a bit more widely (contrary to my sudden assumption it could be an indicator that the build is complete), it turned out there are indeed similar interfaces for Pre and Post build processing as well. They also use the BuildReport type, but at least those seem just a little more self-describing.

However, they're not further documented either.

 

I'm here for a while now (on the forums). I haven't seen any occasions on the forums when anything like this was reassured. Especially here, where Unity employees are very rare and those Unity engineers who really could answer this question would never come here.
The question can be asked in the build forums, although there is no appropriate subforum for this at the moment.

I'm using the build report callbacks for a couple of years now for various reasons (mostly for codegen), I don't think it would be taken away any time soon. Obviously no one (I would argue that even Unity doesn't) knows if they will take it away at any point.

But whatever, it's not important, I just don't understand the expectations here.

 

From the documentation:

Which doesn't mean:

What I want to know is Unity's intention regarding functionality for the callback. Is it the above interpretation? Is it that interpretation plus other things? Is it some parts of that interpretation, and the others are bugs? We don't know!

Seriously, why is it so hard to understand why I want to know this? This is basic stuff to ask an engine developer, because, as I said, relying on undefined behaviour is a terrible idea, and now the only behaviour we know to be defined is that it's called once for each scene during the build.

If what you are are asking is why I'm posting this here when nobody from Unity will see it, I would say because this is the scripting forum, this is related to scripting, and I've also been on the forum for quite a while and have seen things like this answered by Unity devs. I guess I have a pair of other options to try to catch the attention of Unity, like opening a new thread on every single subforum, or send a bug report saying all this is a big nasty bug, but I'd consider those to be a dick move. But I'm all ears if somebody has a better way to make Unity devs aware of this issue.

 

The question is not whether this is going to be taken away or not.

The question asks for experience on usage, because the documentation currently lacks the actual and exact purpose of these. So he's hoping for some insight while he waits for an official update of these docs.

When something appears to work, and this is not documented, you're walking on a frozen lake, never knowing if it was officially said that you're safe walking on it.

So again, metaphorically speaking, while he's waiting for the official version he can rely on, he's trying to figure out which areas of that frozen lake have (at least practically) proven to bw safe. Perhaps someone comes along and says, you can go there, but don't attempt to do ...

Personally, this wouldn't bother me for my own projects. However, some people do care about it, and especially some companies do. This goes as far as having the instruction not to do wild experiences that "appear to work", but to only use stuff which is officially said to work.

I think
"The documentation stated that's how you do A and B, but they've changed it recently. That's why feature X and tool Y broke with the update."
is a still a better explanation than some sort of excuse as
"There wasn't anything about that in the documentations, but it seemed to work until it sadly broke."

Personally I can tell that fortunately, I'd just walk away having a bad feeling about that situation in my current day job. Others walk away knowing they totally messed things up, and they've proven to be not as professional as expected.
Depends on the working environment.