Skip to content

Script Engine

Jump to bottom
ZilverBlade edited this page Aug 29, 2024 · 21 revisions

Index

  1. Game Loop
  2. Scripting
    1. Script Classes
    2. Script Attributes
      1. Editor
      2. Network
    3. Networking
      1. Connection, Relevance and Roles
      2. Field Replication
      3. Method Replication (RPC)

Glossary

  • C# calls static methods in the convention Namespace.Class.Subclass.Method(parameters), however to distinguish namespaces from class scopes, methods and fields, in this documentation it is written as Namespace.Class::Subclass::Method(parameters) (similar to C++ scope style).
  • Certain words are written in bold to stand out, avoiding confusion or error with certain concepts by grabbing your eye’s attention.

1. Game Loop

  • Shard3D runs with a single threaded game loop, everything gets called in a defined order, however it is planned to separate the game logic and physics from the renderer (1 game thread, 1 renderer thread).
  • Renderer calls always get called at the end of the loop
  • Physics runs with a fixed step rate configurable in the engine_settings.ini (default is 120Hz). It may run multiple times per frame or it may even skip a frame! (depending on the framerate)
  • When physics is stepped in a frame, it's done before the C# script step except for LLevel::PreFixedTickEvent(float ts) (Shard3D.Scriptable) (this also means that fixed tick methods will be called before their variable tick counterparts)
  • Physics body transform interpolation occurs every frame after physics step (if occurred) and before script engine step (this also means before the fixed step events)

2. Scripting

2.i. Script Classes

  • Scripts derive from 3 base classes: LLevel, LGameMode, AActor (Shard3D.Scriptable)

  • L is the prefix stating it’s a singleton inside the level, thus there may only be one instance.

  • A is the prefix stating it’s an actor, which is a scriptable prefab actor, it may have multiple instances.

  • AActor:

    • Is to be used standalone for any sort of script, whilst AController is used for input management (this distinction is made due to how the networking system is set up):

      • AController (Inherits AActor, IGhostActor, INetworkReplicatesServerOwner, INetworkOwnableActor)
        • Only this class and UIControl should be allowed to poll user inputs and manage renderer data
        • Must be spawned by Level::SpawnController<T>() (where T is a class derived from AController)

    • BeginEvent() (called when level simulation starts, only called once solely for actors that already existed before the level started simulation!)

    • EndEvent() (called when the level simulation ends, only called once solely for actors that survived until the end of the simulation!)

    • SpawnEvent() (called when actor is spawned)

    • KillEvent() (called when actor is destroyed)

    • TickEvent(float dt) (called every game loop, is not stable, as it has a variable delta time and should be used when integration can be done with a variable frame time)

    • PhysicsTickEvent(float ts) (called at the same rate as the physics step, may be called several times per frame, or it may be skipped in a frame as it runs at a fixed step rate, should be used for integration that requires a fixed time step. Warning, this does not mean that the values get interpolated like the physics positions do, if interpolation between steps is requires, you should do that in a variable frametime tick event (e.g. AActor::TickEvent(), LLevel::PostTickEvent()))

  • LLevel:

    • Is set in the WorldSceneInfoComponent
    • BeginEvent() (called before any other begin event, it is the first event called)
    • EndEvent() (called after every end event, it is the last event called)
    • PreTickEvent(float dt) (called before any AActor::TickEvent(float dt))
    • PostTickEvent(float dt) (called after every AActor::TickEvent(float dt))
    • PrePhysicsTickEvent(float ts) (called before any AActor::PhysicsTickEvent(float ts) and before regular tick events)
    • PostPhysicsTickEvent(float ts) (called after every AActor::PhysicsTickEvent(float ts) and before regular tick events)

  • LGameMode

    • Is set in the WorldSceneInfoComponent
    • N is the prefix stating it is a networking related method
    • NClientConnectingEvent(AController controller) (client has connected and their respective default controller prefab)
    • NClientDisconnectedEvent(AController controller) (client has disconnected)

2.ii. Script Attributes

  • The script api provides 2 kinds of attributes, attributes are only used by derived classes of AActor and UIControl, one purely flag oriented kind by inheriting an empty interface (so that it gets passed onto derived classes, e.g. public class MyBaseClass : ITestAttribute) and another property oriented kind that work like C# attributes (e.g. [MyAttribute] or [MyOtherAttribute(true)])

2.ii.a. Editor Attributes

  • Shard3D offers the ability for fields to be edited in editor, this allows for multiple instances to have different parameters at edit time, being loaded from the scene file at runtime. It also offers the ability for (exclusively useful for editor) calling methods in the editor (without input parameters or return types!)
  • Attributes (Shard3D.Reflection.Attributes):
    • VisibleInEditor(bool editable = true)
    • CallableInEditor(bool requirePlayMode = true)
    • NumericFieldEditProperties(double min = -INFINITY, double max = INFINITY, double speed = 1.0)
  • [VisibleInEditor(bool)] may only be applied on top of the following types:
    • (of System) float, double, (u)byte, (u)short, (u)int, (u)long, string
    • (of Shard3D.Library.Types) Float2, Float3, Float4, Float3x3, Float4x4
    • (of Shard3D) Actor (This includes all classes derived from Actor)
  • [NumericFieldEditProperties(double, double, double)] may be applied on numeric fields that have the [VisibleInEditor] attribute with bool editable set to true.

2.ii.b. UI Attributes

2.ii.c. Network Attributes

Clone this wiki locally