Unity 开发人员转CGE（castle Game engine）城堡游戏引擎指导手册

如果您了解其他游戏引擎（例如Unity），本页将尝试解释某些概念如何映射到Castle Game Engine。如果您有任何疑问，请记得在论坛、Discord 聊天或其他地方提问。

GameObjectUnity 中的东西（简化）存在于你的世界中，并且可能是可见的，并且可能有受转换影响的子元素。

对于游戏对象（不是用户界面）， Castle Game EngineGameObject中最接近的等价物是类。的实例可以按层次结构排列，其中每个元素都会变换（移动、旋转、缩放）子元素。CGE 最重要的类是，它是实际上可以渲染/动画/碰撞模型的后代。只需设置为在那里加载您的模型（如 glTF 文件）即可。TCastleTransformTCastleTransformTCastleSceneTCastleTransformTCastleScene.Url

我们的手册文档TCastleScene和TCastleTransform功能在“带有场景、相机、导航的视口”一章中。基本上你可以做类似的事情

层次结构TCastleTransform放置在 a 中TCastleViewport，它是 2D 用户界面元素（ 的后代TCastleUserInterface）。

对于作为用户界面元素的对象，最重要的基类是TCastleUserInterface。它有很多后代，比如

• 明显的用户界面控件：TCastleButton、TCastleLabel、TCastleRectangleControl、TCastleImageControl...

• 布局：TCastleVerticalGroup, TCastleHorizontalGroup,

• 最后TCastleViewport是一个关键的 UI 组件，它是实际渲染TCastleTransform.

请参阅用户界面文档。

在最简单的情况下，您为每个 3D 模型创建一个TCastleScene实例。您可以使用CGE 编辑器直观地执行此操作，也可以通过代码执行此操作。

要将多个TCastleScene实例分组（并转换为一个组），您可以使用其他TCastleTransform实例。它TCastleScene也是一个TCastleTransform后代，所以它也可以有孩子。

遵循模板“3D FPS Game”（通过运行我们的编辑器创建它，选择“New Project”，然后选择“3D FPS Game”作为起点）。data/gameviewplay.castle-user-interface在生成的项目中，在编辑器中打开设计，以实际了解我的意思（在这个和之前的答案中）。

我们使用CGE 编辑器的目标是提供与 Unity 和其他游戏引擎编辑器类似的体验。因此，您可以将 3D 模型拖放到设计中，然后拖动它们来设计关卡。

简短回答：

相当于在行为中记录的MonoBehaviour类。您可以将其附加到控制它。TCastleBehaviorTCastleTransform

完整答案：

您可以通过多种方式从代码中控制 CGE 内容：

1. 定义一个来自的类TCastleBehavior（请参阅behaviors），并将其实例添加到TCastleTransform。喜欢

   <span style="color:#333333"><span style="background-color:#ffffff"><span style="background-color:#f7f7f8"><span style="color:#333333"><code>  <span style="color:#000000"><strong>type</strong></span>
       TMyBehaviorClass = <span style="color:#000000"><strong>class</strong></span>(TCastleBehavior)
       <strong>public</strong>
         <span style="color:#000000"><strong>procedure</strong></span> Update(<span style="color:#000000"><strong>const</strong></span> SecondsPassed: Single; <span style="color:#000000"><strong>var</strong></span> RemoveMe: TRemoveType); <strong>override</strong>;
       <span style="color:#000000"><strong>end</strong></span>;</code></span></span></span></span>

   然后从代码中添加这样的行为实例：

   <span style="color:#333333"><span style="background-color:#ffffff"><span style="background-color:#f7f7f8"><span style="color:#333333"><code>  <span style="color:#000000"><strong>var</strong></span>
       MyBehavior: TMyBehaviorClass;
     <span style="color:#000000"><strong>begin</strong></span>
       MyBehavior := TMyBehaviorClass.Create(SomOwner);
       MyBehavior.Xxx := ...; <span style="color:#999988"><em>// configure necessary parameters</em></span>
       MyTransform.AddBehavior(MyBehavior);
     <span style="color:#000000"><strong>end</strong></span>;</code></span></span></span></span>

   请参阅我们的模板“3D FPS Game”（通过运行我们的编辑器创建它，选择“New Project”，然后选择“3D FPS Game”作为起点），它准确地展示了这种方法。它定义了一个简单的TEnemy类，该类定义了敌人的逻辑，并且是TCastleBehavior后代。它控制着敌人的行动。它还允许通过检查来检查（例如，当射击射线时）“我是否击中了敌人” SomeTransform.FindBehavior(TEnemy) <> nil。

   虽然上面的示例显示了使用代码附加行为，但您也可以TEnemy在编辑器中添加。有关如何在编辑器中注册类的信息，请参阅编辑器和自定义组件TEnemy文档。这需要使用菜单选项“Project -> Restart Editor (With Custom Components)”重新启动项目内的编辑器。这是一个额外的步骤，但对于复杂的行为来说是有意义的，可以更轻松地在编辑器中配置这些行为。

   该引擎还附带了一些标准行为（例如TCastleBillboard，TCastleSoundSource），并且可以轻松地从编辑器中添加和配置这些行为。

2. 您可以从视图中控制事物（请参阅视图）。像这样的视图TViewPlay（参见上面提到的模板“3D FPS Game”）有自己的方法来Update处理输入。视图可以保留对您世界中所有事物的引用，并且可以控制它们。

   例如，您可以像这样处理视图方法中的所有生物TViewPlay.Update。我们关于使用代码控制视口的手册显示了移动多辆车的示例。

3. 您还可以分配事件，例如OnClick. 大多数 UI 控件都会公开明显的事件，例如TCastleButton.OnClick. 您可以自由地在一个中心位置处理这些事件（例如 LCLTForm后代（仅当您使用TCastleControl）或 CGETCastleView后代）或分散处理（例如，创建您自己的类的不同实例来处理每个不同生物、不同项目的事件） 。

   使用事件的方法类似于在 Lazarus LCL 或 Delphi VCL 中使用 UI。

   当您想要在一个类（视图）中处理与某些 UI 相关的所有事件（例如单击游戏选项中可见的所有按钮）时，此方法是最佳选择。

4. 在 CGE 中控制事物的另一种方法是从现有类创建类后代。在 CGE 中，您可以从几乎所有类（包括 importantTCastleTransform和TCastleUserInterface）创建后代，并在那里重写虚拟方法。例如，您可以重写TCastleTransform.Update以每帧执行某些操作。

   因此，您可以定义一个类似从or派生的类TMyCreature。这个类将控制它自己的变换（例如，它会改变它自己的变换以移动生物），并且它可能会加载一些子项（更多和实例）来显示生物并为其设置动画。TCastleTransformTCastleSceneTranslationTCastleTransformTCastleScene

   这是一种经典的 OOP 方法。这就像虚幻引擎一样，允许您定义自己的角色类来覆盖基类。

   您甚至可以将自定义类注册为在编辑器中可用，以直观地添加/配置它们。

您应该将游戏数据放置在data项目的子目录中。请参阅有关“数据”目录的手册。它将自动打包并在您的游戏中可用。

子目录中的所有内容都data可以在运行时加载。Assets/Resources/从这个意义上说，如果你关心细节的话，它实际上类似于Unity的子目录。

不属于您的游戏数据的内容（例如源代码）不应放置在data子目录中。源代码应该位于数据之外。只有编译器必须能够找到它（您可以使用标准 Lazarus项目选项和/或（用于构建跨平台项目）<compiler_options>在 CastleEngineManifest.xml 中指定源位置）。按照惯例，大多数 CGE 示例将 Pascal 源代码放置在code子目录中（或顶级项目目录中），但这实际上只是一个惯例。

一个较大的CGE项目的布局可能是这样的：

请参阅支持的模型格式。简而言之：glTF 是最好的:) 此文档页面还链接到各种创作工具“如何导出数据”的说明。

使用view3dscene测试您的模型以查看支持的内容。如果您在CGE 编辑器中双击模型，它将自动启动 view3dscene。

不，我们可能永远不会这样做（除非间接通过一些通用转换库）。FBX 是 Autodesk 的专有模型格式。请不要使用 FBX，它是专有的（Autodesk FBX 规范故意“保密”，并且 Autodesk 只通过其付费 SDK 批准使用 FBX），而且也不是那么好。使用 glTF。

如果您有 FBX 格式的现有模型，您可以将它们转换为 glTF（使用 FBX2glTF 的 Godot Engine 分支）。如果您有模型的源版本，您可能可以将它们从创作软件重新导出到 glTF。您还可以使用Blender或许多其他工具在模型格式之间进行转换。

答案的简短摘要：使用 TCastleWindow。如果您想要的只是一款跨平台游戏，其中所有内容均使用 Castle Game Engine 渲染。如果您来到这里并且想要“只是使用 CGE 制作游戏”，请使用TCastleWindow.

详细信息： https://castle-engine.io/manual_lazarus_control.php概述了差异：

• TCastleControl 意味着引擎渲染在 Lazarus 形式内。也就是说，TCastleControl 是一个常规的 Lazarus 控件，可以放置在更大的窗体上。您可以使用Lazarus设计器来放置LCL控件，并且可以使用CGE编辑器来设计CGE控件（在TCastleControl内）。

• TCastleWindow 意味着引擎渲染是一个单独的窗口，并且我们没有使用 LCL。您可以使用CGE编辑器来设计控件。因此，您无法访问 LCL 控件，但作为交换，您可以获得完美的跨平台代码（Android、iOS、Switch 仅适用于 TCastleWindow）。

在这两种情况下，您都可以使用 Lazarus 作为 IDE — 来编写代码、调试等。在这两种情况下，您都可以使用 CGE 编辑器来设计 CGE 控件（位于 TCastleControl 或 TCastleWindow 内部）。

等效的方法是设置MyViewport.Items.TimeScale.

它特定于给定的世界，这是TCastleAbstractRootTransform可用的实例MyViewport.Items。简单的游戏只有一个视口，一个TCastleViewport实例。的多个实例TCastleViewport是可能的，然后可以共享同一个世界，或显示不同的世界（只需在Items之间分配）。

可以通过额外的时间缩放TCastleScene.TimePlayingSpeed。这在给定TCastleScene实例中是本地的。

在Container.Fps.SecondsPassed. 请参阅查看事件以获取最简单的用法示例。

在您重写TCastleUserInterface.Update（包括TCastleView.Update）或TCastleTransform.Update方法时，您还有一个SecondsPassed包含该值的显式参数。TCastleTransform.Update时间已经缩放（如果您使用上面MyViewport.Items.TimeScale提到的）。

TCastleTransform和都TCastleUserInterface具有布尔Exists属性：TCastleTransform.Exists, TCastleUserInterface.Exists。默认情况下这是true. 只需将其设置为false即可使所有组件的行为就好像该组件不属于层次结构一样。不存在的组件不可见、不碰撞、不处理任何输入、不引发任何事件等。因此 UnityGameObject.SetActive(xxx)翻译为 CGE MyTransform.Exists := xxx。

您还可以控制 的TCastleTransform.Collides、TCastleTransform.Pickable和TCastleTransform.Visible属性TCastleTransform。这些对于使某些东西有用，例如可见但不可碰撞，或可碰撞但不可见。请注意，当Existsis 时false，它会“覆盖”它们，并且不存在的对象永远不会碰撞并且永远不可见。

我们有 UI 缩放功能，可以智能地适应任何屏幕尺寸，其工作原理类似于 Unity 画布缩放。它允许假设特定的窗口大小进行设计，只要设置合理的锚点，设计在各种屏幕分辨率（即使具有不同的宽高比）下看起来都是合理的。它只是缩放坐标 - 实际渲染是针对最终分辨率完成的，因此它看起来总是“清晰”。

缩放是使用CastleSettings.xml文件配置的。默认 CGE 编辑器“新项目”模板将 UI 缩放设置为使用 1600x900 的参考窗口大小进行调整。

广告、分析、应用内购买等移动服务可作为Android 服务或iOS 服务提供。您可以在CastleEngineManifest.xml中声明它们，然后使用我们的构建工具构建项目。这些允许将您的代码与各种第三方服务（来自 Google、Apple 等）集成，或使用需要特殊权限（例如振动）的移动 API。

“服务”是指“在构建阶段添加的二进制或源代码形式的项目的一部分”。

• Android 服务可能包含 Java 代码、Android 预编译库、Gragle 配置等。

• iOS 服务可能包含 Objective-C 代码、iOS 预编译库、CocoaPods配置等。

• 在其他平台上，到目前为止我们不需要类似的概念。例如，通过公开 FMOD 或 Steam API 等的普通 Pascal 单元，始终可以将 CGE 与桌面上的第三方服务集成。也就是说，有一天我们可能会为其他平台添加“服务”。

您当然可以替换或增强我们引擎使用的着色器。

我们有合成着色器，类似于 Unity3d“表面着色器”，但增强了:)我对此感到非常自豪，它确实允许轻松编写一段着色器代码并将其添加到某些形状中，并且（与 Unity3d“表面着色器”相比）着色器”）它有一些很酷的新功能，例如组合多种效果的能力（因此您可以编写一个着色器效果，也许添加另一种着色器效果），或者更改灯光或纹理的着色或制作程序生成（在 GPU 上）纹理。

请参阅examples/viewport_and_scenes/shader_effects，了解 Pascal 中的简单演示，该演示将用 GLSL 编码的效果附加到从 glTF 加载的场景。当然，着色器统一变量可以在运行时从 Pascal 设置，因此您可以在运行时以零成本配置着色器。

请参阅https://github.com/castle-engine/demo-models，子目录compositing_shaders中的纯 X3D节点演示Effect（您可以从 CGE 加载它们；只是这些演示是Effect通过 X3D 代码创建节点，而不是通过 Pascal 代码） ）。

合成着色器文档（特别是本文档）描述了这些着色器效果的工作原理。

在 Unity 中，典型的世界是 3D 的层次结构GameObject。

• 在这个世界的某个地方，您有一个Camera组件，它确定相机参数（如投影）和视口大小。关联的变换GameObject决定了相机的位置和旋转。

• 您可以Camera在不同的游戏对象上拥有多个组件以拥有多个视口。

• 在这个世界的某个地方，您有一个画布，可以充当按钮和图像等 2D 控件的位置。

在 CGE 中，情况有点不同。Viewport( TCastleViewport)是一个2D控件，它可以在里面渲染3D世界。

• 您设计组件的层次结构TCastleUserInterface。它们都具有相同的属性来控制位置和大小，使用锚点，使用FullSize（填充父级等）。

• 有许多TCastleUserInterface后代，例如按钮、图像和视口。

• 在视口 ( TCastleViewport) 实例中，您可以放置​​ 3D 世界（在 中Viewport.Items）。

• 视口始终与 中的一台摄像机连接Viewport.Camera。该摄像机确定投影设置以及观看者的位置和旋转。

上面描述了编辑器模板中的典型设计。要查看其实际效果，请使用“3D FPS Game”等模板在编辑器中创建一个“新项目” ，然后在编辑器中打开设计。data/gameviewplay.castle-user-interface

简而言之，在 Unity 中，“视口”、“相机”和“UI”只是 3D 世界中的东西。在 CGE 中，“视口”（以及相应的“相机”）包含您的 3D 世界，而“视口”是您 UI 的一部分。

有效，

• 在 CGE 中，“视口”可以像任何其他 2D 控件一样定位/调整大小。有关显示 4 个视口的示例，请参阅Examples/viewport_and_scenes/multiple_viewports 。

• CGE 中视口的 Z 顺序（前面/后面）很简单，它的工作方式就像所有其他 2D 控件一样。您可以轻松地将其他 2D 控件放置在视口的前面或后面（如果视口有背景，后者很有用Transparent）。

• 在 CGE 中，每个“视口”可能显示一个完全不同的、不相关的 3D 世界。视口还可以共享世界（从不同的相机显示相同的世界），只需将它们设置为相同的Viewport.Items值即可。

预制件是一种在文件中存储游戏对象层次结构并附加 Unity 组件的方法。

CGE 中通常的等效方法是创建一个xxx.castle-transform文件，您可以在其中创建根为TCastleTransform或 的设计TCastleScene。这允许您构建TCastleTransform/TCastleScene实例的转换层次结构。然后，您可以将其xxx.castle-transform作为单个内容多次加载。请参阅Examples/advanced_editor，该文件data/soldier_with_cape.castle-transform中有此方法的最简单示例。

Unity UI 元素的预制件相当于 UI 设计文件，xxx.castle-user-interface上面已经提到过。

Unity AudioSource的等价物是我们的TCastleSoundSource. 这是一种行为，您将其附加到父级TCastleTransform，它可以播放空间化声音。请注意，对于非空间声音，您也可以直接调用TSoundEngine.Play，这更简单，并且不需要实例TCastleSoundSource。

Unity AudioClip的等价物是我们的TCastleSound.

有关如何在 CGE 中使用声音的信息，请参阅有关声音的手册章节。

• Owner来自于标准TComponent。请参阅手动和自动释放（Pascal 介绍）。它管理内存（当所有者在拥有的实例之前被释放时，所有者将释放拥有的实例）。

• Parent是视觉父母。CGE UI 有TCastleUserInterface.Parent. CGE 变换有TCastleTransform.Parent.

因此Parent和Owner是不同的概念，甚至在不同的类中声明。

有时，如果在特定情况下合适，则可以将两者设置为同一实例，但一般来说，这两件事只执行两个单独的功能Parent。Owner例如，在 CGE 编辑器中，设计中所有内容的所有者始终是一个中心DesignOwner组件。当您自己加载设计时，您Owner显式提供实例（作为UserInterfaceLoad, TransformLoad, 的参数ComponentLoad），然后您自己指定父级，但将设计添加到层次结构中（例如MyParentUi.InsertFront(MyLoadedUi)）。

使用TCastleDownload. 与 类似UnityWebRequest，该类可以发送 HTTP 请求（GET、POST 等）并可以异步下载数据。它被设计为一种简单但功能强大的网络通信方式。Z-Gantt时间进度计划甘特图软件

CGE示例/网络演示了它。

这是各种物理力方法（请参阅物理）从 Unity 映射到 CGE 的方式：

• Unity - Scripting API: Rigidbody.AddForceAtPosition → TCastleRigidBody.AddForceAtPosition（两者都在世界坐标空间中采用 2 个参数“力，位置”）

• Unity - Scripting API: Rigidbody.AddRelativeForce → TCastleRigidBody.AddForce（两者都采用 1 个参数“Force”）。通过ForceInLocalCoordinates= true.

• Unity - Scripting API: Rigidbody.AddForce → TCastleRigidBody.AddForce（两者都采用 1 个参数“Force”）。通过ForceInLocalCoordinates= false.

• Unity - Scripting API: Rigidbody.AddTorque → TCastleRigidBody.AddTorque（两者都采用 1 个参数，“扭矩”，在世界坐标空间中）

上述映射适用于默认 Unity 使用情况ForceMode.Force。

对于脉冲（使用 Unity API ForceMode.Impulse），我们有一个单独的方法TCastleRigidBody.ApplyImpulse。