Class TCastleSceneCore

Values

• fvLocalBoundingBox
• fvVerticesCount
• fvTrianglesCount
• fvMainLightForShadows
• fvShapesActiveCount
• fvShapesActiveVisibleCount

List of TScreenEffectNode nodes, collected by ChangedAll.

Is the scene visible currently. Descendants may set this to True during TCastleTransform.LocalRender.

Create TShape (or descendant) instance suitable for this TCastleSceneCore descendant. In this class, this simply creates new TShape instance. If you make a descendant of TCastleSceneCore, you may need to store some per-shape information, and then it may be useful to have your own TShape descendant to carry this information. So you can override this to create your own descendant, and then you're sure that all leafs within Shapes tree are created using this.

Example: TCastleScene uses this to create TGLShape.

Called after PointingDeviceSensors or PointingDeviceActiveSensors lists (possibly) changed.

In this class, DoPointingDeviceSensorsChange updates Cursor and calls OnPointingDeviceSensorsChange.

Called before changing one node into another, when old node may have beeen associated with a shape using TShapeTree.AssociateNode.

Load the model given as a X3D nodes graph. This replaces RootNode with new value.

Note that you should never load the same TX3DRootNode instance into multiple TCastleScene instances.

// DON'T DO THIS!
Node := LoadNode(URL);
Scene1 := TCastleScene.Create(Application);
Scene1.Load(Node, false);
Scene2 := TCastleScene.Create(Application);
Scene2.Load(Node, false);

If you need to load the same model into multiple scenes, it is best to use the Clone method:

SceneTemplate := TCastleScene.Create(Application);
SceneTemplate.Load(URL);
Scene1 := SceneTemplate.Clone(Application);
Scene2 := SceneTemplate.Clone(Application);

Using the Clone makes a copy of the underlying X3D graph, so it is roughly like doing:

Node := LoadNode(URL);
Scene1 := TCastleScene.Create(Application);
Scene1.Load(Node.DeepCopy as TX3DRootNode, false);
Scene2 := TCastleScene.Create(Application);
Scene2.Load(Node.DeepCopy as TX3DRootNode, false);

Note that sometimes you don't need to create multiple scenes to show the same model many times. You can simply insert the same TCastleScene instance multiple times to TCastleViewport.Items (TCastleRootTransform). See the manual: https://castle-engine.io/manual_scene.php#section_many_instances

Parameters

ARootNode

The model to load. This will become a new value of our RootNode property.

AOwnsRootNode

Should the scene take care of freeing this root node when it is no longer used. If False, you are expected to free it yourself, but only after the scene using it was freed.

AResetTime

If True then we will reset time at loading (using ResetTimeAtLoad), changing the Time. This is usually what you want when you load a new world.

Load the 3D model from given URL.

We load a number of 3D model formats (X3D, VRML, Collada, Wavefront OBJ...) and some 2D model formats (Spine JSON). See https://castle-engine.io/creating_data_model_formats.php for the complete list.

URL is downloaded using the CastleDownload unit, so it supports files, http resources and more. See https://castle-engine.io/manual_network.php about supported URL schemes. If you all you care about is loading normal files, then just pass a normal filename (absolute or relative to the current directory) as the URL parameter.

Warning: this symbol is deprecated: use Load with (AURL: string, AOptions: TSceneLoadOptions) parameters. AllowStdIn is not implemented anymore.

Save the current 3D model (X3D nodes graph) to the given file (URL).

The X3D encoding is automatically guessed from the URL extension. By default it is XML, and we suggest using the .x3d extension. If you specify an extension indicating "classic encoding", we will use such encoding (use .x3dv for X3D in classic encoding, or .wrl for older VRML content).

The file may also be automatically gzip compressed if extension indicates it. Use .x3d.gz to indicated XML compressed with gzip, or use .x3dv.gz or .wrl.gz to indicate classic encoding compressed with gzip.

The URL property is also changed.

Number of active shapes in the Shapes tree. This is equivalent to Shapes.ShapesCount(true), except that this is faster (it's cached and reused in this instance, and automatically invalidated only when needed).

Number of active and visible (TShape.Visible) shapes in the Shapes tree.

See also

ShapesActiveCount

Number of active shapes in the Shapes tree.

Calculate the number of triangls and vertexes of all shapa states. For detailed specification of what these functions do see appropriate TAbstractGeometryNode methods. Here, we just sum their results for all shapes.

Warning: this symbol is deprecated: use VerticesCount without Boolean argument, it is ignored now

Warning: this symbol is deprecated: use TrianglesCount without Boolean argument, it is ignored now

Helper functions for accessing viewpoints defined in the scene.

Release all internal associations with your VRML/X3D nodes. In particular, this will release OpenGL resources connected to your nodes. You should always call this before you (may) free some nodes in RootNode.

You have to call ChangedAll or Load at sometime after BeforeNodesFree, and before you try actual rendering, events etc. Otherwise some stuff may not get recalculated.

The InternalChangedAll parameter is for internal use. It is set to True when ChangedAll calls this method at the beginning of it's work, and means that nothing is freed, and we only require necessary cleanup at the beginning of ChangedAll. This way ChangedAll (when it wasn't preceeded by explicit BeforeNodesFree(false)) produces events from stacks CheckForDeletedNodes.

Call Node.FreeRemovingFromAllParents, making sure that changes to our VRML/X3D node graph are allowed. This makes sure we call BeforeNodesFree befor freeing, and ChangedAll afterwards.

This avoids a common pitfall with relying on TShape or such existence between BeforeNodesFree and ChangedAll. BeforeNodesFree may free all our TShape instances, so if you want to free TX3DNode from our graph — you typically want to get this TX3DNode instance *before* calling BeforeNodesFree. Using this method to free the node ensures this.

Remove the shape node from the scene. In case of VRML 1.0 / Inventor, when the Shape doesn't have a node, we remove the geometry node.

Notify scene that potentially everything changed in the VRML/X3D graph. This includes adding/removal of some nodes within RootNode graph and changing their fields' values. (Before freeing the nodes, remember to also call BeforeNodesFree earlier.)

You usually never need to call this method explicitly. It's called by engine when necesssary. However, you need to call it yourself if you change the X3D graph directly through nodes' FdXxx fields, and you don't want to call for some reason FdXxx.Changed.

ChangedAll causes recalculation of all things dependent on RootNode, so it's very costly to call this. Avoid calling this. When you change a simple field, like by FdXxx.Value := ..., you should rather call FdXxx.Changed, and it may do something much faster than rebuilding the scene.

Descendant implementors notes: ChangedAll is virtual, when overriding it remember that it's called by constructor of this class, so you can put a lot of your initialization there (instead of in the constructor).

ChangedAll calls BeforeNodesFree(true) first, for safety (and TGLShape actually depends on it, see implementation comments).

Called when geometry changed. Does OnGeometryChanged, and does some other stuff necessary (mark some octrees for regenerating at next access).

This is public only for overloading (and for internal TShape access). Do not call this yourself — TShape and TCastleSceneCore implementations know when and how to call this.

Call OnViewpointsChanged, if assigned.

Call OnBoundViewpointVectorsChanged, if assigned.

Mechanism to schedule ChangedAll calls.

Since these calls may be costly (traversing the hierarchy), and their results are often not immediately needed by TCastleSceneCore or TX3DNode hierarchy, it's sometimes not desirable to call them immediately when geometry changed / all changed.

So you can use ScheduleChangedAll instead of ChangedAll. All event handlers within TCastleSceneCore already do this.

When you're within Begin/EndChangesSchedule, then ScheduleChangedAll just sets an internal flag and actual ChangedAll will be done only once at EndChangesSchedule. Otherwise (when not within Begin/EndChangesSchedule), ScheduleChangedAll will immediately call ChangedAll.

Warning: this symbol is deprecated: do not use this, better to construct a summary string yourself

Returns short information about the scene. This consists of a few lines, separated by newlines. Last line also ends with CastleUtils.NL.

Warning: this symbol is deprecated: better to construct a string yourself, use TrianglesCount, VerticesCount

Warning: this symbol is deprecated: better to construct a string yourself, use BoundingBox.ToString

Warning: this symbol is deprecated: better to construct a string yourself, use EdgesCount

Edges count in the scene, for information purposes.

A spatial structure containing all visible shapes. Add ssRendering to Spatial property, otherwise it's Nil.

You should not use this directly. Instead use TCastleViewport and then use Viewport.Items.WorldXxxCollision methods like Viewport.Items.WorldRay or Viewport.Items.WorldSphereCollision.

Note that when VRML/X3D scene contains Collision nodes, this octree contains the visible (not necessarily collidable) objects.

A spatial structure containing all collidable shapes. Add ssDynamicCollisions to Spatial property, otherwise it's Nil.

You should not usually use this directly. Instead use TCastleViewport and then use Viewport.Items.WorldXxxCollision methods like Viewport.Items.WorldRay or Viewport.Items.WorldSphereCollision.

You can use InternalOctreeCollisions to get either InternalOctreeDynamicCollisions or InternalOctreeStaticCollisions, whichever is available.

Note that when VRML/X3D scene contains Collision nodes, this octree contains the collidable (not necessarily rendered) objects.

TODO: Temporarily, this is updated simply by rebuilding.

A spatial structure containing all visible triangles, suitable only for scenes that stay static. Add ssVisibleTriangles to Spatial property, otherwise it's Nil.

You should not usually use this directly. Instead use TCastleViewport and then use Viewport.Items.WorldXxxCollision methods like Viewport.Items.WorldRay or Viewport.Items.WorldSphereCollision.

Note that when VRML/X3D scene contains X3D Collision nodes, this octree contains the visible (not necessarily collidable) objects.

A spatial structure containing all collidable triangles. Add ssStaticCollisions to Spatial property, otherwise it's Nil.

You should not usually use this directly. Instead use TCastleViewport and then use Viewport.Items.WorldXxxCollision methods like Viewport.Items.WorldRay or Viewport.Items.WorldSphereCollision.

It is automatically used by the XxxCollision methods in this class, if exists, unless OctreeDynamicCollisions exists.

Note that you can use InternalOctreeCollisions to get either InternalOctreeDynamicCollisions or InternalOctreeStaticCollisions, whichever is available.

Octree for collisions. This returns either InternalOctreeStaticCollisions or InternalOctreeDynamicCollisions, whichever is available (or Nil if none). Be sure to add ssDynamicCollisions or ssStaticCollisions to have this available.

You should not usually use this directly. Instead use TCastleViewport and then use Viewport.Items.WorldXxxCollision methods like Viewport.Items.WorldRay or Viewport.Items.WorldSphereCollision.

Viewpoint defined in the 3D file (or some default camera settings if no viewpoint is found).

GetViewpoint seeks for VRML/X3D nodes like Viewpoint, OrthoViewpoint (actually, any X3DViewpointNode) and VRML 1.0 PerspectiveCamera and OrthographicCamera. GetPerspectiveViewpoint seeks only for perspective viewpoints.

If ViewpointDescription = '', they return the first found viewpoint node. Otherwise, they look for X3DViewpointNode with description field mathing given string.

If camera properties were found in some node, it returns this node. Otherwise it returns nil. This way you can optionally extract some additional info from used viewpoint node, or do something special if default values were used. Often you will just ignore result of this function — after all, the most important feature of this function is that you don't have to care about details of dealing with camera node.

Returned CamDir and CamUp and GravityUp are always normalized — reasons the same as for TAbstractViewpointNode.GetView.

Frees some scene resources, to conserve memory. See TSceneFreeResources documentation.

Warning: this symbol is deprecated: use Node.UnregisterScene

Recursively unset node's TX3DNode.Scene.

Scene processes X3D key sensor nodes here, https://castle-engine.io/x3d_implementation_keydevicesensor.php . Remember to set ListenPressRelease to process the key sensor nodes.

Called when pointing device moves. This may generate the continuously-generated events like hitPoint_changed, also it updates PointingDeviceOverItem and PointingDeviceOverPoint, thus producing isOver and such events.

To make pointing-device sensors work Ok, make sure you have non-nil OctreeCollisions (e.g. include ssDynamicCollisions in Spatial).

Pointing-device sensors over which the pointing device is. This is just a shortcut for PointingDeviceOverItemˆ.State.PointingDeviceSensors, returning Nil if PointingDeviceOverItem = Nil.

Clear any references to PTriangle passed previously in TRayCollisionNode argument to PointingDevicePress, PointingDeviceRelease, PointingDeviceMove. This is internally used in case some of past seen PTriangle may become invalid, so any memory about them should be cleared.

This doesn't cause any X3D events (contrary to e.g. calling PointingDeviceMove with Pick.Triangle = Nil).

This method clears any references to saved PTriangle and PointingDeviceActiveSensors. Note that this still calls DoPointingDeviceSensorsChange (making OnPointingDeviceSensorsChange event), if PointingDeviceActiveSensors / PointingDeviceSensors possibly changed.

Change current scene time, setting Time. It is crucial that you call this continuously to have some VRML/X3D time-dependent features working, like TimeSensor and MovieTexture. See Time for details what is affected by this.

This is automatically taken care of if you added this scene to TCastleWindow.Controls or TCastleControl.Controls. Then our Update takes care of doing the job, according to TimePlaying and TimePlayingSpeed.

This causes time to be passed to appropriate time-dependent nodes, events will be called etc.

SetTime and IncreaseTime do exactly the same, the difference is only that for IncreaseTime you specify increase in the time (that is, NewTime = Time + TimeIncrease). Use whichever version is more handy.

Following X3D specification, time should only grow. So NewValue should be > Time (or TimeIncrease > 0). Otherwise we ignore this call. For resetting the time (when you don't necessarily want to grow Time) see ResetTime.

If a change of Time will produce some visible change in the VRML/X3D model (for example, MovieTexture will change, or TimeSensor change will be routed by interpolator to coordinates of some visible node) it will be reported by usual method, that is VisibleChangeHere.

Warning: this symbol is deprecated: it should not be necessary to call this, ever; using TX3DEvent.Send(...) or TX3DEvent.Send(..., NextEventTime) will automatically behave Ok.

The time within this scene, in seconds. Increasing this "drives" the animations (by increasing time of time-dependent nodes like X3D TimeSensor, which in turn drive the rest of the animation).

You can use SetTime or IncreaseTime to move time forward manually. But usually there's no need for it: our Update method takes care of it automatically, you only need to place the scene inside TCastleViewport.Items.

You can start/stop time progress by TimePlaying and scale it by TimePlayingSpeed. These properties affect how the time is updated by the Update method (so if you use SetTime or IncreaseTime methods, you're working around these properties).

Default time value is 0.0 (zero). However it will be reset at load to a current time (seconds since Unix epoch — that's what X3D standard says to use, although you can change it by KambiNavigationInfo.timeOriginAtLoad, see https://castle-engine.io/x3d_implementation_navigation_extensions.php#section_ext_time_origin_at_load ). You can perform this "time reset" yourself by ResetTimeAtLoad or ResetTime.

Time that should be used for next event. You usually don't need to call this directly, this is automatically used by TX3DEvent.Send when you don't specify explicit time.

Set Time to arbitrary value.

You should only use this when you loaded new VRML/X3D model.

Unlike SetTime and IncreaseTime, this doesn't require that Time grows. It still does some time-dependent events work, although some time-dependent nodes may be just unconditionally reset by this to starting value (as they keep local time, and so require TimeIncrease notion, without it we can only reset them).

Set Time to suitable initial value after loading a world.

This honours VRML/X3D specification about VRML/X3D time origin, and our extension [https://castle-engine.io/x3d_extensions.php#section_ext_time_origin_at_load].

Register compiled script handler, for VRML/X3D Script node with "compiled:" protocol. See [https://castle-engine.io/x3d_extensions.php#section_ext_script_compiled].

Update TCastleNavigation properties based on currently bound TNavigationInfoNode.

Bound TNavigationInfoNode is taken from NavigationInfoStack.Top. If no such node is bound (NavigationInfoStack.Top is Nil) then we behave as if TNavigationInfoNode with all fields at default was active.

Note that, since some fields are only in some descendants (e.g. MoveSpeed is only at TCastleWalkNavigation) then some TNavigationInfoNode settings are just not transferred to all Navigation instances like TCastleExamineNavigation.

WorldBox is the expected bounding box of the whole 3D scene. Usually, it should be TCastleViewport.Items.BoundingBox. In simple cases (if this scene is the only TCastleScene instance in your world, and it's not transformed) it may be equal to just BoundingBox of this scene.

Warning: this symbol is deprecated: use Camera.AnimateTo(APosition, ADirection, AUp)

Make Camera go to the view given by (world coordinates) APosition, ADirection, AUp.

Honours current NavigationInfo.transitionType and transitionTime. If transitionType indicates instanteneous transition, then jumps by simple Camera.SetWorldView(APosition, ADirection, AUp). Otherwise makes a smooth animation into new values by Camera.AnimateTo(APosition, ADirection, AUp, TransitionTime).

Will generate NavigationInfo.transitionComplete when transition ends.

Warning: this symbol is deprecated: use Camera.AnimateTo(APosition, ADirection, AUp)

Warning: this symbol is deprecated: use Camera.AnimateTo(APosition, ADirection, AUp)

Warning: this symbol is deprecated: use Camera.AnimateTo(APosition, ADirection, AUp)

Light node that should be used for headlight, or Nil if default directional headlight is suitable.

This never returns Nil. It's not concerned whether the headlight should actually be used — for this, see HeadlightOn.

Notify the scene that camera position/direction changed a lot. It may be called when you make a sudden change to the camera, like teleporting the player to a completely different scene part.

This may be used as a hint by some optimizations. It tells that what will be visible in the next rendered frame will be probably very different from what was visible in the last frame.

Current implementation notes:

Currently, this is used by TCastleScene if you use RenderOptions.OcclusionQuery. Normally, occlusion query tries to reuse results from previous frame, using the assumption that usually camera changes slowly and objects appear progressively in the view. When you make a sudden camera jump/change, this assumption breaks, so it's better to resign from occlusion query for the very next frame. This method will do exactly that.

Nice scene caption. Uses the "title" of WorldInfo node inside the VRML/X3D scene. If there is no WorldInfo node (or it has empty title) then result is based on loaded URL.

Find a named X3D node in the current node graph.

By default it searches both active and inactive graph parts. Add fnOnlyActive to search only in active parts.

It searches only within nodes of given type (NodeClass). Specifying NodeClass helps to make search unambiguous (as name clashes are possible, some authoring tools may write models with duplicate names for materials, meshes etc. and both glTF and X3D allow it). This allows to safely write code like:

MyMaterial := Scene.Node(TNodePhysicalMaterial, 'MyMaterial') as TNodePhysicalMaterial;

TODO: An even better version, "MyMaterial := Scene.Node<TNodePhysicalMaterial>('MyMaterial')", may be available in the future, if FPC support for generic methods will improve. Define GENERIC_METHODS to try it out now, but heed the warnings in castleconf.inc .

Exceptions raised

EX3DNotFound

When node is not found. Unless fnNilOnMissing in Options, then it returns Nil on missing node, and EX3DNotFound is never raised.

Find a named field within an X3D node in the current node graph.

Like Node, this searches all nodes (in active or not) graph parts.

Exceptions raised

EX3DNotFound

If given node or field could not be found.

Find a named event within an X3D node in the current node graph.

Like Node, this searches all nodes (in active or not) graph parts.

Exceptions raised

EX3DNotFound

If given node or event could not be found.

Does named animation with given name exist.

See also

AnimationsList

List the names of available animations in current scene.

PlayAnimation

TimeSensor of this animation. Nil if this name not found.

TimeSensor of this animation, by animation index (index on AnimationsList). Nil if this index not found.

Warning: this symbol is deprecated: use AnimationsList (and do not free it's result)

Forcefully, immediately, set pose from given animation, with given time in animation.

This avoids the normal passage of time in X3D scenes, it ignores the ProcessEvents and AnimateOnlyWhenVisible properties, it ignores the current animation set by PlayAnimation, and forces the current time on TimeSensors by TTimeSensorNode.FakeTime.

Warning: this symbol is deprecated: use ForceAnimationPose overload with "Loop: boolean" parameter

Play an animation specified by name. If the given animation name exists, then we return True and stop previously playing named animation (if any). Otherwise we return False and the current animation is unchanged.

To get the list of available animations, see AnimationsList.

This automatically turns on ProcessEvents, if it wasn't turned on already. Processing events is necessary for playing animations.

This is the simplest way to play animations using Castle Game Engine. For a nice overview about using PlayAnimation, see the manual https://castle-engine.io/manual_scene.php , section "Play animation".

Playing an already-playing animation is guaranteed to restart it from the beginning.

You can specify whether the animation should loop, whether to play it forward or backward, whether to do animation blending and some other options using TPlayAnimationParameters. If you use an overloaded version with the TPlayAnimationParameters, note that you can (and usually should) free the TPlayAnimationParameters instance right after calling this method. We do not keep reference to the TPlayAnimationParameters instance, and we do not free it ourselves.

More details about how this works:

• Calling this method does not change the scene immediately. There may be a delay between calling PlayAnimation and actually changing the scene to reflect the state at the beginning of the indicated animation. This delay is usually 1 frame (that is, the scene is updated at the next Update call), but it may be larger if you use the optimization AnimateSkipTicks.

  This is often a desirable optimization. There's often no "rush" to visually change the animation right now, and doing it at the nearest Update call is acceptable. It also means that calling PlayAnimation multiple times before a single Update call is not expensive.

  If you really need to change the scene immediately (for example, because you don't want to show user the initial scene state), simply call ForceInitialAnimationPose right after PlayAnimation.

• The animation is performed using X3D TTimeSensorNode.

  For example, TTimeSensorNode may instruct a TCoordinateInterpolatorNode to update the TIndexedFaceSetNode coordinates, and in effect the animation can deform a mesh. Or TTimeSensorNode may instruct a TPositionInterpolatorNode to update TTransformNode.Translation, and in effect the animation can move something. See https://castle-engine.io/x3d_implementation_interpolation.php for a thorough description how the animation works in X3D.

  This means that during the animation, the X3D nodes graph (within RootNode) is being changed.

  If you load a model from a castle-anim-frames or MD3 format, note that it is animated using a special "node interpolator". This also works using a special (internal) X3D node that switches which node is visible.

• Starting an animation effectively cancels any effect from any previous animation. That is, even if the new animation doesn't modify some transformations, these transformations are not left "as is", instead they are reset to the default model state using ResetAnimationState. This is usually the desired effect, corresponding to how the animations should intuitively behave, e.g. if you have "walk" and "idle" animations.

  If you want to simultaneously play multiple animations or if you want to simultaneously modify scene by code (while playing some animation) then you can control each time sensor using TTimeSensorNode.Start and TTimeSensorNode.Stop. See also the example in examples/animations/simultaneous_animations_one_scene .

Warning: this symbol is deprecated: use another overloaded version of PlayAnimation, like simple PlayAnimation(AnimationName: string, Loop: boolean)

Force the model to look like the initial animation frame now.

Use this after calling PlayAnimation. Calling this is simply ignored if no PlayAnimation was called earlier, of if the model already looks following the animation requested by PlayAnimation.

If you don't use this method, there may be a 1-frame delay between calling PlayAnimation and actually updating the rendered scene look. If during that time a rendering will happen, the user will see a scene in previous pose (not in the first pose of animation you requested by PlayAnimation). To avoid this, simply call this method right after PlayAnimation.

This sets first animation frame, unless you used TPlayAnimationParameters.InitialTime <> 0.

Duration, in seconds, of the named animation (named animations are detected by AnimationsList method). For a looping animation, this is the duration of a single cycle. 0 if not found.

Stop the CurrentAnimation, started by last PlayAnimation call. Note that this leaves the model in a state in the middle of the last animation.

You can use ResetAnimationState to reset the state afterwards. Calling ForceInitialAnimationPose also will do it.

Note that it is not necessary to stop the previous animation before starting a new one (by PlayAnimation). PlayAnimation will automatically stop the previous animation. Moreover, PlayAnimation may do animation blending (cross-fade) between old and new animation (if you use TPlayAnimationParameters.TransitionDuration), which only works if you did not call StopAnimation.

When animation is stopped (by this or any other means), by default it's TPlayAnimationParameters.StopNotification is called. You can use DisableStopNotification to avoid it, which should be used only in exceptional situations.

Reset all the fields affected by animations. See TimeSensor.detectAffectedFields documentation (https://castle-engine.io/x3d_implementation_time_extensions.php#section_detect_affected_fields) for details how these fields are detected, and when this is useful. By default this is enabled, for all TimeSensor nodes.

If IgnoreAffectedBy <> nil, the fields affected by the given TimeSensor may not be reset. This is an optimization useful in case this TimeSensor will modify the scene very soon, so resetting its affected fields is a waste of time. Do not depend on 100% that the fields affected by given TimeSensor are left untouched (in the current implementation, this field is ignored).

Force recalculating the text shapes when font changed. For now, we don't detect font changes (when TFontStyleNode.OnFont returns something different) ourselves. This calls TTextNode.FontChanged and TAsciiTextNode_1.FontChanged on all appropriate nodes.

Create a scene with the same contents (X3D scene graph) as this one. The created scene has exactly the same class as this one (we use ClassType.Create to call a virtual constructor).

Note that this does not copy other scene attributes, like ProcessEvents or Spatial or rendering attributes in TCastleScene.RenderOptions. It only copies the scene graph (RootNode) and also sets target URL based on source URL (for logging purposes, e.g. TCastleProfilerTime use this URL to report loading and preparation times).

Tree of shapes in the scene, acting as a simplfied mirror of the X3D node graph. Contents of this tree are read-only from outside.

Notification when geometry changed. "Geometry changed" means that the positions of triangles changed. This is not send when merely things like material changed.

It is not guaranteed that octrees are already recalculated when this is called. (They may be recalculated only on-demand, that is when you actually access them.) However, it is guaranteed that shape's transformation (like TShape.State.Transform) are already updated.

Notification when the list of viewpoints in the scene possibly changed.

Note that this doesn't necessarily mean that the current, bound viewpoint changed (although it could). If you only want to get notified when currently bound viewpoint changes, then what you seek is rather ViewpointStack.OnBoundChanged.

Notification when the currently bound viewpoint's vectors (position/orientation and such) changed.

More precisely, this is called whenever values generated by ViewpointStack.Top.GetView changed.

It cannot be called when ViewpointStack.Top = Nil. Note that this also doesn't notify you about changes to currently bound viewpoint, for this you rather want to use ViewpointStack.OnBoundChanged. This is called only when currently bound viewpoint stays the same, only it's vectors change.

Actual VRML/X3D graph defining this scene.

It is allowed to change contents of RootNode. Just make sure the scene is notified about these changes. The simplest option is to use simple properties of nodes (not the ones starting with Fd... prefix), when possible. Then everything is notified automatically. If you must use fields through the FdXxx properties, then assign them using TX3DField.Send, or (if you need to assign field values directly, like TSFVec3f.Value := ...) call TX3DField.Changed.

It is also allowed to change the value of RootNode and even to set RootNode to Nil. Changing RootNode allows you to load and unload whole new VRML/X3D graph (for example from some 3D file) whenever you want, and keep the same TCastleSceneCore instance (with the same rendering settings and such).

If True, RootNode will be freed by destructor of this class.

Progress title shown during spatial structure creation (through TProgress.Title). Uses only when not empty, and only if progress was not active already (so we avoid starting "progress bar within a progress bar").

Progress title shown during spatial structure creation (through TProgress.Title). Uses only when not empty, and only if progress was not active already (so we avoid starting "progress bar within a progress bar").

Current item over which the pointing device is. Nil if over none. For example, you can investigate it's pointing device sensors (in PointingDeviceOverItemˆ.State.PointingDeviceSensors), although there's a shortcut for just this in PointingDeviceSensors. You can change this by PointingDeviceMove and PointingDeviceClear.

Current 3D point under the pointing device. Only meaningful when PointingDeviceOverItem <> nil, otherwise undefined.

Currently active pointing-device sensors. Only TAbstractPointingDeviceSensorNode instances. Always empty when PointingDeviceActive = False. Read-only from outside of this class.

Note that sensor specified here doesn't have to be one of the sensors of PointingDeviceOverItem. When some sensor is activated, it grabs further events until it's deactivated (e.g. when you set PointingDeviceActive := false, which means that user released mouse button). This means that when user moves the mouse while given sensors are active, he can move mouse over other items, even the ones where the active sensors aren't listed — but the sensors remain active.

Is pointing device currently active (for example, mouse button is pressed down).

Event called PointingDeviceSensors or PointingDeviceActiveSensors lists (possibly) changed.

Initial world time, set by the last ResetTimeAtLoad call.

Stack of background nodes. The node at the top is the current background. All nodes on this stack must descend from TAbstractBackgroundNode class.

Stack of fog nodes. The node at the top is the current fog. All nodes on this stack must descend from TFogNode class.

Stack of NavigatinInfo nodes. The node at the top is the current NavigatinInfo. All nodes on this stack must descend from TNavigationInfoNode class.

Stack of viewpoint nodes. The node at the top is the current Viewpoint. All nodes on this stack must descend from TAbstractViewpointNode. Note that this includes also VRML 1.0/Inventor nodes.

List of handlers for VRML/X3D Script node with "compiled:" protocol. This is read-only, change this only by RegisterCompiledScript.

Should we use headlight for this scene. Controls if containing TCastleViewport will use a headlight, if this is the main scene.

When you load a new model, this is always updated based on this model's NavigationInfo.headlight. (If no NavigationInfo node, then default is to use the headlight.) When you bind a new NavigationInfo node, this is also updated to follow NavigationInfo.headlight.

You can change the value of this property. If we have a NavigationInfo node, then NavigationInfo.headlight field will be always updated to correspond to this value. (It will be even updated using events mechanism if ProcessEvents, so scripts inside the VRML/X3D "know" when you turn on/off the headlight and may react to it, e.g. spawn a zombie monster when you turn on the flashlight.)

Warning: this symbol is deprecated: do not use this; optimization done by this is really negligible; leave ProcessEvents=false for static scenes

Static scene will not be automatically notified about the changes to the field values. This means that TX3DField.Send and TX3DField.Changed will not notify this scene. This makes a small optimization when you know you will not modify scene's VRML/X3D graph besides loading (or you're prepared to do it by manually calling Scene.InternalChangedField, but this should not be used anymore, it's really dirty).

The behavior of events is undefined when scene is static. This means that you should always have ProcessEvents = False when Static = True. Only when Static = false you're allowed to freely change ProcessEvents to True.

Changing this is expensive when the scene content is already loaded, so it's best to adjust this before Load.

Global lights of this scene. Read-only. Useful to shine these lights on other scenes, if TCastleScene.CastGlobalLights.

Warning: this symbol is deprecated.

List the names of available animations in current scene. Animations are detected looking for TimeSensor nodes. See https://castle-engine.io/x3d_implementation_interpolation.php for an overview how nodes are used to create animations.

Note that if you set AnimationPrefix property, we additionally filter TimeSensor nodes to show only the names starting with given prefix. In this case, not all TTimeSensorNode are reflected in this list.

You can get the corresponding TTimeSensorNode by AnimationTimeSensor. Note that the same TTimeSensorNode may occur multiple times on this list, in case X3D IMPORT mechanism was used to rename the imported animation.

The resulting TStringList instance is owned by this object, do not free it.

Note that the list of animations may change if you rebuild the underlying X3D nodes graph, for example if you start to delete / add some TimeSensor nodes.

Warning: this symbol is deprecated: this property did not prove to be of much use; report if you need it, otherwise it may be removed one day

The prefix of an X3D TimeSensor node name to treat it as a "named animation". Named animation are used by methods AnimationsList, PlayAnimation, and AnimationDuration, HasAnimation. By default this is empty, which means we consider all TimeSensor nodes a "named animation".

You can set this to something like 'Anim_' or 'Animation_' or whatever your 3D export software produces. Only the TimeSensor nodes with names starting with this prefix will be available on AnimationsList, and this prefix will be stripped from the names you use with methods like PlayAnimation.

Currently played animation by PlayAnimation, or Nil.

Note that, in a general case, you can have multiple active animations (multiple TimeSensor X3D nodes may be active) at the same time. Calling TTimeSensorNode.Start directly on multiple nodes is one way to make it happen. This property simply describes the animation controlled by the last PlayAnimation method.

Note that the animation may be started by PlayAnimation with a 1-frame delay, but this property hides it from you, it is changed immediately by the PlayAnimation call.

Warning: this symbol is deprecated.

Deprecated name for URL.

When using PlayAnimation without TPlayAnimationParameters, this value is used as the duration (in seconds) of animation cross-fade (blending of animations). Zero (default value) disables the smooth transition, animations will change without any transition by default.

This default transition is only used if some previous animation was playing. Otherwise, it would be applied even when starting the initial animation.

When TimePlaying is True, the time of our 3D world will keep playing. More precisely, our Update will take care of increasing Time. Our Update is usually automatically called (if you added this scene to TCastleWindow.Controls or TCastleControl.Controls) so you don't have to do anything to make this work.

Controls the time speed (if TimePlaying is True): 1.0 means that 1 second of real time equals to 1 unit of world time.

Which spatial structures (octrees) should be created and used.

Using "spatial structures" allows to achieve various things:

• ssDynamicCollisions or ssStaticCollisions:

  Using one of these two flags allows to resolve collisions with the (collidable) triangles of the model. By default, every X3D Shape is collidable using it's exact mesh. You can use the X3D TCollisionNode to turn collisions off for some shapes, or replace some shapes with simpler objects for the collision-detection purposes.

  If you use neither ssDynamicCollisions nor ssStaticCollisions, then the collisions are resolved using the whole scene bounding box. That is, treating the whole scene as a giant cube.

  You can always toggle Collides to quickly make the scene not collidable. In summary:

  • Collides = False: the scene does not collide.

  • Collides = True and Spatial is empty: the scene collides as it's bounding box. This is the default situation after constructing TCastleScene.

  • Collides = True and Spatial contains ssDynamicCollisions or ssStaticCollisions: the scene collides as a set of triangles. The triangles are derived from information in X3D Shape and Collision nodes.

  The ssStaticCollisions can be used instead of ssDynamicCollisions when the scene is guaranteed to absolutely never change, and only when the speed is absolutely crucial. The collision structure created by ssStaticCollisions is a bit faster (although may use significantly more memory). The practical advice is to almost always use ssDynamicCollisions instead of ssStaticCollisions: the speed gains from ssStaticCollisions are usually impossible to measure, and ssStaticCollisions sometimes uses significantly more memory, and if you by accident modify the model (animate it etc.) with ssStaticCollisions -> then results are undefined, even crashes are possible.

• ssRendering:

  Using this flag adds an additional optimization during rendering. It allows to use frustum culling with an octree. Whether the frustum culling is actually used depends on TCastleScene.OctreeFrustumCulling value (by default: yes).

  Without this flag, we can still use frustum culling, but it's less effective as it considers each shape separately. Whether the frustum culling is actually used depends in this case on TCastleScene.FrustumCulling value (by default: yes).

  Using frustum culling (preferably with ssRendering flag) is highly adviced if your camera usually only sees only a part of the scene. For example, it a noticeable optimization if you have a camera walking/flying inside a typical game level/location.

• ssVisibleTriangles:

  Using this flag allows to resolve collisions with visible (not only collidable) triangles quickly.

  This is in practice useful only for ray-tracers, normal applications should not use this. Normal applications should avoid collision detection with the visible version of the model. Normal applications should instead perform collision detection with the collidable version of the model, since this is much better optimized (both by the engine code, and by an artist creating the model, using X3D Collision nodes etc.)

See TSceneSpatialStructure for more details about the possible values. For usual dynamic scenes rendered in real-time, you set this to [ssRendering, ssDynamicCollisions].

By default, the value of this property is empty, which means that no octrees will be created. This has to be the default value, to:

1. Not create octrees by default (e.g. at construction). Creating them takes time (and memory).

2. Allow developer to adjust TriangleOctreeLimits before creating the octree.

Should the event mechanism (a basic of animations and interactions) work.

If True, then events will be send and received through X3D routes, time dependent nodes (TTimeDependentFunctionality, like TTimeSensorNode) will be activated and updated from Time time property, Press, Release and other methods will activate key/mouse sensor nodes, scripts will be initialized and work, etc.

In other words, this makes the scene fully animated and interacting with the user.

If False, this all doesn't work, which makes the scene static.

Currently loaded scene URL. Change this property to load a scene from the given URL. We support many 3D and 2D scene formats, like X3D and glTF, see https://castle-engine.io/creating_data_model_formats.php .

Setting this property works just like using the Load method with a new URL. In fact, using directly the Load method will also change this URL property.

The only difference between Scene.URL := 'blah.x3d' and Scene.Load('blah.x3d') is that setting the URL will not reload the scene if you set it to the same value. That is, Scene.URL := Scene.URL; will not reload the scene (you have to use explicit Load for this.).

Pass URL = '' to load an empty scene, this sets RootNode to Nil.

At loading, process the scene to support shadow maps. This happens at the Load method call, and it makes "receiveShadows" field automatically handled.

Note that this is not the only way to make shadow maps. VRML/X3D author can always make shadow maps by using lower-level nodes, see [https://castle-engine.io/x3d_extensions.php#section_ext_shadow_maps]. When using these lower-level nodes, this property does not matter This property (and related ones like ShadowMapsDefaultSize) is relevant only for handling shadows by the "receiveShadows" field.

Default shadow map texture size.

Affects how shadow maps are handled for the "receiveShadows" field. This is taken into account at the scene Load time, and only if ShadowMaps is True.

VRML/X3D author can always override this by placing a GeneratedShadowMap node inside light's defaultShadowMap field. In this case, GeneratedShadowMap.size determines shadow map size.

When loading new model, use this viewpoint index to initialize camera. VRML/X3D specification says to use the first (index = 0) viewpoint, you can change this property to bind 2nd, 3rd and so on viewpoints.

This is applied only at loading (actually, at ChangedAll). If you later want to bind another viewpoint, just send set_bind := true to it.

When loading new model and looking for initial viewpoint, consider only viewpoints with this node name. Relevant only if non-empty.

This may cooperate with InitialViewpointIndex: InitialViewpointIndex specifies the index of viewpoint node that satisfies also InitialViewpointName condition. For example:

• InitialViewpointIndex = 0 and InitialViewpointName = '' means to use the first viewpoint, ignoring nodes' names. This is the default behavior, also following VRML/X3D specification.

• InitialViewpointIndex = 1 and InitialViewpointName = '' means to use the 2nd viewpoint. Node name doesn't matter.

• InitialViewpointIndex = 1 and InitialViewpointName = 'blah' means to use the first viewpoint named 'blah'. That is, we are only counting nodes named 'blah' for this.

When True, we animate (more precisely: process time pass in Update) only when the model is visible. This is a powerful optimization, but be careful if you depend on your animations for something else than just visual effect.

Non-zero values optimize the animation processing, by not updating the animation every frame. After updating the animation in one Update call, the next AnimateSkipTicks number of Update calls will go very quickly, as they will not actually change the scene at all.

This is an effective optimization if the scene is usually not large on the screen.

• The animation is less smooth. For example, if AnimateSkipTicks = 1, then every other Update call does not change the scene. For example, if you have 60 FPS, and Update is called 60 times per second, then we will actually change the scene only 30 times per second.

  The "skip" within every scene has a little random shift, to avoid synchronizing this skip across many created scenes. This makes this a little harder to notice.

• In exchange, the speedup is substantial. For example, if AnimateSkipTicks = 1, then the animation on CPU effectively costs 2x less. In general, AnimateSkipTicks = N means that the cost drops to 1 / (1 + N).

Warning: this symbol is deprecated: use TCastleBox, TCastleSphere, TCastlePlane for these primitives

Easily turn the scene into a simple primitive, like sphere or box or plane. Changing this to something else than pgNone reloads the scene (calls Load with a new X3D graph).

If AutoAnimation is set, this animation will be automatically played. It is useful to determine the initial animation, played once the model is loaded (each time URL changes). You can also change AutoAnimation at any other moment at runtime (set it to something non-empty to change to a new animation; set it to '' to stop any animation).

Note: Using AutoAnimation will under the hood call methods like PlayAnimation, StopAnimation and update CurrentAnimation. The reverse is not true: calling PlayAnimation doesn't change AutoAnimation. So you can think of AutoAnimation as "an initial animation, activated each time we load the model, even if later we can change it to something else using PlayAnimation".

See also

AutoAnimationLoop

Does the animation indicated by AutoAnimation loops.

Does the animation indicated by AutoAnimation loops.

Transformation nodes inside the model that are synchronized with automatically-created children TCastleTransform.

This allows to expose transformation nodes from glTF, X3D and other model formats as TCastleTransform. These transformation nodes include animated bones from skeletons (armatures). Such "exposed transformation" results in a creation of TCastleTransform child, with the same name and synchronized transformation (translation, rotation, scale).

This allows to expose e.g. "hand that may hold a weapon", or "slot of a vehicle where to attach a camera", as TCastleTransform. And this allows, in turn, to attach various things to (possibly animated) transformations, e.g. attach model of a weapon to a hand, or attach TCastleCamera to some bone. The attached things will be automatically animated when the scene skeleton animates.

Setting this property merely copies the contents using TStrings.Assign, as is usual for published TStrings properties. In CGE editor, there's a nice GUI editor to pick the transfomation nodes, click on "..." at this property.

Note: the owner of auto-created children is equal to this scene's Owner. This is most natural when you edit this in CGE editor, or load using TransformLoad.

See the engine example in: examples/animations/expose_transformations_to_animate_children/ .

See also

ExposeTransformsPrefix

Name prefix for all children created by ExposeTransforms.

Name prefix for all children created by ExposeTransforms. Useful to keep names unique in the scene.