Suggestion: make the "Scene Requirement" section more clear in the documentation

[nanto2016]

First of all, there's just a very minor detail: I think the name should be "Scene Requirements" with an S as there multiple requirements, but I'm not 100% sure.

What brought me here in the first place is some confusion I got from the 2D example scene for Tweening. In this scene, there is a PhantomCamera2D as a child of an Area2D, but in the documentation, there it says:

• At least onePhantomCamera2D/PhantomCamera3D node
  • Without a parent node except for the scene's root.

Here's what I understood from this:

• There needs to be at least one Pcam
• Pcams need to be a direct child of the scene's root node

So does this portion of the docs actually mean that you need the Pcam to be a descendant of the scene's root node? If so, I would simply remove the portion that says "Without a parent node...".

And lastly, does the following quote from the docs (in the same section) mean that the Camera2D/Camera3D needs to be a direct child of the root node? From my testing, it in fact does not need to be a direct child of the root node.

• A Camera2D/Camera3D node
  • Without a parent node except for the scene's root.

If not, I suggest once again removing the last part.

I have never done this before but I will try to make a fork with these changes, plus an extremely minor detail: adding a space where indicated in the following image.

---

Thank you a lot for this great addon that I can't wait to use (and the really cool docs that come with it) !

[ramokz]

The wording “Without a parent node except for the scene's root.” is less of a strict requirement, and more of a general rule of thumb. It was added as I noticed a fair few people had nested PCams inside a parent node that was moving, which caused undesired follow mode behaviour, who then submitted bug reports. Keeping a PCam as a child of the scene root makes it so that issue wouldn't occur, assuming people didn't move the root node itself. But you're right in that it's not strictly true. Like most general rules, you can break them if you know what you're doing. In the Tweening example scene's case, those PCams nor its parent Area2D are meant to move, so in cases like that it doesn't matter whether they're nested or not.

Have been thinking of adding an option to set PCams as a top-level node, which would make the requirement note on the site go away, but that can lead to breaking behaviour, so it's likely for a 0.8 release.

[namelessvoid]

I second nanto2016's remark: This was also confusing to me and I needed some time to figuring out how to do this. I only need PCams in some child scenes and there was no good way to add them to the root node, except by some auto-load code-based way. Looking at the example scenes I realized that the "root node" probably means something like:

"Since Phantom Camera takes control of the transform of the Camera2D/3D nodes, it is recommended to nest both, Camera2D/3D and any PhantomCamera2D/3D nodes, into the scene tree in a way that no transform is applied to them. E.g. Nesting any of these nodes below a moving 'Player' node may cause unexpected side effects. To be save, place them into branches that only consist of pure Nodes. If you nest them below any Node2D/3D, make sure that these are not transformed."

This or something similar could be added below the bullet point list.

And to add more work to the plate 😁 There could be example scene trees (screenshots?) of valid and invalid scene tree configuration.