From a12915664106e7b5e8756acaa809de237313a70d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20L=C3=BCbe=C3=9F?= Date: Wed, 13 Dec 2023 14:45:33 +0100 Subject: [PATCH] Documentation --- ScriptCore/Components/RigidBody2D.cs | 6 +- ScriptCore/Components/Transform.cs | 13 ++-- ScriptCore/Core/EngineObject.cs | 5 +- ScriptCore/Core/UUID.cs | 13 +++- ScriptCore/Editor/ReadonlyAttribute.cs | 4 ++ ScriptCore/Editor/ShowButtonAttribute.cs | 3 + ScriptCore/Editor/TextFieldAttribute.cs | 4 ++ ScriptCore/Entity.cs | 24 +++++--- ScriptCore/Extensions/EnumExtension.cs | 9 +++ ScriptCore/Extensions/FieldInfoExtension.cs | 3 + ScriptCore/Input.cs | 49 +++++++++++++++ ScriptCore/Key.cs | 3 + ScriptCore/Log.cs | 60 ++++++++++++++++--- ScriptCore/Math/Math.cs | 33 ++++++---- ScriptCore/MouseButton.cs | 3 + ScriptCore/Physics/Collision2D.cs | 4 ++ .../Serialization/SerializeFieldAttribute.cs | 12 ++++ 17 files changed, 211 insertions(+), 37 deletions(-) create mode 100644 ScriptCore/Serialization/SerializeFieldAttribute.cs diff --git a/ScriptCore/Components/RigidBody2D.cs b/ScriptCore/Components/RigidBody2D.cs index 3b6537f..999be49 100644 --- a/ScriptCore/Components/RigidBody2D.cs +++ b/ScriptCore/Components/RigidBody2D.cs @@ -1,8 +1,10 @@ -using GlitchyEngine.Components; using GlitchyEngine.Math; -namespace GlitchyEngine; +namespace GlitchyEngine.Components; +/// +/// Rigid body component for 2D physics. +/// public class Rigidbody2D : Component { /// diff --git a/ScriptCore/Components/Transform.cs b/ScriptCore/Components/Transform.cs index a25f9c1..7d4ddc1 100644 --- a/ScriptCore/Components/Transform.cs +++ b/ScriptCore/Components/Transform.cs @@ -4,8 +4,16 @@ using GlitchyEngine.Math; namespace GlitchyEngine; +/// +/// Represents the position, rotation and scale of an entity in the world. +///

+/// Every entity has a transform component. +/// public class Transform : Component { + /// + /// Gets or sets the translation (position) of the entity. + /// public float3 Translation { get @@ -13,9 +21,6 @@ public class Transform : Component ScriptGlue.Transform_GetTranslation(Entity.UUID, out float3 translation); return translation; } - set - { - ScriptGlue.Transform_SetTranslation(Entity.UUID, in value); - } + set => ScriptGlue.Transform_SetTranslation(Entity.UUID, in value); } } diff --git a/ScriptCore/Core/EngineObject.cs b/ScriptCore/Core/EngineObject.cs index c81653d..49933bd 100644 --- a/ScriptCore/Core/EngineObject.cs +++ b/ScriptCore/Core/EngineObject.cs @@ -1,11 +1,14 @@ namespace GlitchyEngine.Core; +/// +/// The base class for all classes that represent something that belongs to the engine (Entities, Components and Assets). +/// public abstract class EngineObject { protected internal UUID _uuid; /// - /// UUID used for identifying the object in the engine. + /// UUID (Universally Unique Identifier) used for identifying the object in the engine. /// public UUID UUID => _uuid; diff --git a/ScriptCore/Core/UUID.cs b/ScriptCore/Core/UUID.cs index ec92ab3..850c2e5 100644 --- a/ScriptCore/Core/UUID.cs +++ b/ScriptCore/Core/UUID.cs @@ -7,13 +7,24 @@ public struct UUID { private ulong _uuid; + /// + /// Create a new instance of a with the given value as ID. + /// + /// The id. public UUID(ulong uuid) { _uuid = uuid; } - public static UUID Zero = new UUID(0); + /// + /// A with the ID 0. + /// + public static readonly UUID Zero = new UUID(0); + /// + /// Creates a new random . + /// + /// The newly created public static UUID CreateNew() { ScriptGlue.UUID_CreateNew(out UUID id); diff --git a/ScriptCore/Editor/ReadonlyAttribute.cs b/ScriptCore/Editor/ReadonlyAttribute.cs index 859c1ce..8330d7c 100644 --- a/ScriptCore/Editor/ReadonlyAttribute.cs +++ b/ScriptCore/Editor/ReadonlyAttribute.cs @@ -2,6 +2,10 @@ namespace GlitchyEngine.Editor; +/// +/// Specifies, that the field should be readonly, so that it cannot be changed in the editor.
+/// Note, that this only affects the editor. Scripts can still change the values. +/// public sealed class ReadonlyAttribute : Attribute { } diff --git a/ScriptCore/Editor/ShowButtonAttribute.cs b/ScriptCore/Editor/ShowButtonAttribute.cs index 53d4bc8..181641e 100644 --- a/ScriptCore/Editor/ShowButtonAttribute.cs +++ b/ScriptCore/Editor/ShowButtonAttribute.cs @@ -3,6 +3,9 @@ using System; namespace GlitchyEngine.Editor; +/// +/// Specifies the visibility of a button. +/// public enum ButtonVisibility { /// diff --git a/ScriptCore/Editor/TextFieldAttribute.cs b/ScriptCore/Editor/TextFieldAttribute.cs index a2fa8a8..73f75bb 100644 --- a/ScriptCore/Editor/TextFieldAttribute.cs +++ b/ScriptCore/Editor/TextFieldAttribute.cs @@ -4,6 +4,10 @@ using System.Text; namespace GlitchyEngine.Editor; +/// +/// Specifies the properties of the textfield for the that the attribute is attached to. +/// +[AttributeUsage(AttributeTargets.Field)] public sealed class TextFieldAttribute : Attribute { /// diff --git a/ScriptCore/Entity.cs b/ScriptCore/Entity.cs index 2c5832b..483dfd3 100644 --- a/ScriptCore/Entity.cs +++ b/ScriptCore/Entity.cs @@ -12,7 +12,8 @@ namespace GlitchyEngine; public class Entity : EngineObject { /// - /// Don't call this constructor yourself. + /// Only to be called by the engine. Don't call this constructor yourself, it will not result in a valid entity. + /// If you want to create a new entity use or /// protected Entity() { @@ -20,7 +21,7 @@ public class Entity : EngineObject // This constructor will be called by the Engine to initialize the scripts fields. // Especially don't call Create here! Because Create would try and create a new entity. } - + /// /// Creates a new Entity. /// @@ -31,7 +32,7 @@ public class Entity : EngineObject } /// - /// Creates a new Entity. + /// Creates a new Entity with the specified components attached to it. /// /// The name of the new entity. /// The components that the entity shall have. @@ -56,9 +57,17 @@ public class Entity : EngineObject /// The ID of the entity that belongs to this instance. internal Entity(UUID uuid) : base(uuid) { } + /// + /// Returns if a component of the given type is attached to this entity. + /// + /// The type of the component. [MethodImpl(MethodImplOptions.AggressiveInlining)] public bool HasComponent() => HasComponent(typeof(T)); + /// + /// Returns if a component of the given type is attached to this entity. + /// + /// The type of the component. [MethodImpl(MethodImplOptions.AggressiveInlining)] public bool HasComponent(Type type) => ScriptGlue.Entity_HasComponent(_uuid, type); @@ -240,14 +249,11 @@ public class Entity : EngineObject ScriptGlue.Entity_RemoveScript(_uuid); } + /// + /// Gets the of this . + /// public Transform Transform => GetComponent(); - //public Vector3 Translation - //{ - // get => Transform.Translation; - // set => Transform.Translation = value; - //} - /// /// Returns the first entity with the given name. /// diff --git a/ScriptCore/Extensions/EnumExtension.cs b/ScriptCore/Extensions/EnumExtension.cs index 9b5d3ea..36ae009 100644 --- a/ScriptCore/Extensions/EnumExtension.cs +++ b/ScriptCore/Extensions/EnumExtension.cs @@ -3,8 +3,17 @@ using System.Linq; namespace GlitchyEngine.Extensions; +/// +/// Extends the -interface with useful methods. +/// public static class EnumExtension { + /// + /// Enumerates the enumerable and returns a tuple containing the item and the index for every item. + /// + /// + /// + /// public static IEnumerable<(T item, int index)> WithIndex(this IEnumerable self) => self.Select((item, index) => (item, index)); } \ No newline at end of file diff --git a/ScriptCore/Extensions/FieldInfoExtension.cs b/ScriptCore/Extensions/FieldInfoExtension.cs index 2a87d80..6aab1d6 100644 --- a/ScriptCore/Extensions/FieldInfoExtension.cs +++ b/ScriptCore/Extensions/FieldInfoExtension.cs @@ -5,6 +5,9 @@ using System.Text; namespace GlitchyEngine.Extensions; +/// +/// Extends the -class with useful methods. +/// public static class FieldInfoExtension { /// diff --git a/ScriptCore/Input.cs b/ScriptCore/Input.cs index 3607122..c69febf 100644 --- a/ScriptCore/Input.cs +++ b/ScriptCore/Input.cs @@ -2,26 +2,75 @@ namespace GlitchyEngine; +/// +/// Provides methods to query the state of the input devices. +/// public static class Input { + /// + /// Returns if the specified key is in the pressed down state. + /// + /// The key to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsKeyPressed(Key key); + + /// + /// Returns if the specified is in the released state. + /// + /// The key to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsKeyReleased(Key key); + + /// + /// Returns if the state of the specified changed this frame (i.e. changed from pressed to released or from released to pressed). + /// + /// The key to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsKeyToggled(Key key); + /// + /// Returns if is being pressed down this frame + /// ( was last frame and is this frame). + /// + /// The key to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsKeyPressing(Key key); + + /// + /// Returns if is being released this frame + /// ( was last frame and is this frame). + /// + /// The key to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsKeyReleasing(Key key); + /// + /// Returns if the specified mouse button is in the pressed down state. + /// + /// The button to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsMouseButtonPressed(MouseButton mouseButton); + + /// + /// Returns if the specified mouse button is in the released state. + /// + /// The button to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsMouseButtonReleased(MouseButton mouseButton); + + /// + /// Returns if the mouse button is being pressed down this frame + /// ( was last frame and is this frame). + /// + /// The button to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsMouseButtonPressing(MouseButton mouseButton); + + /// + /// Returns if the mouse button is being released this frame + /// ( was last frame and is this frame). + /// + /// The button to query. [MethodImpl(MethodImplOptions.InternalCall)] public static extern bool IsMouseButtonReleasing(MouseButton mouseButton); } diff --git a/ScriptCore/Key.cs b/ScriptCore/Key.cs index 1f8ebce..27dc328 100644 --- a/ScriptCore/Key.cs +++ b/ScriptCore/Key.cs @@ -1,5 +1,8 @@ namespace GlitchyEngine; +/// +/// An enum of all keys that can be queried using methods in . +/// public enum Key { // Based on Win32 Virtual Keys diff --git a/ScriptCore/Log.cs b/ScriptCore/Log.cs index 11d7545..e3e57f4 100644 --- a/ScriptCore/Log.cs +++ b/ScriptCore/Log.cs @@ -7,7 +7,10 @@ namespace GlitchyEngine; /// public class Log { - public enum LogLevel + /// + /// The severity of the log message. + /// + private enum LogLevel { Trace = 0, Debug, @@ -18,53 +21,96 @@ public class Log Off } + /// + /// Logs a trace message. + /// + /// The message to log. public static void Trace(string message) { LogMessage_Impl(LogLevel.Trace, message); } - + + /// + /// Logs an info message. + /// + /// The message to log. public static void Info(string message) { LogMessage_Impl(LogLevel.Info, message); } - + + /// + /// Logs a warning message. + /// + /// The message to log. public static void Warning(string message) { LogMessage_Impl(LogLevel.Warning, message); } - + + /// + /// Logs an error message. + /// + /// The message to log. public static void Error(string message) { LogMessage_Impl(LogLevel.Error, message); } - + + /// + /// Logs a critical error message. + /// + /// The message to log. public static void Critical(string message) { LogMessage_Impl(LogLevel.Critical, message); } + /// + /// Serializes the given object (using ) and logs it as a trace message. + /// + /// The object to serialize. public static void Trace(object obj) { LogMessage_Impl(LogLevel.Trace, obj.ToString()); } + + /// + /// Serializes the given object (using ) and logs it as an info message. + /// + /// The object to serialize. public static void Info(object obj) { LogMessage_Impl(LogLevel.Info, obj.ToString()); } + + /// + /// Serializes the given object (using ) and logs it as a warning message. + /// + /// The object to serialize. public static void Warning(object obj) { LogMessage_Impl(LogLevel.Warning, obj.ToString()); } + + /// + /// Serializes the given object (using ) and logs it as an error message. + /// + /// The object to serialize. public static void Error(object obj) { LogMessage_Impl(LogLevel.Error, obj.ToString()); } - + + /// + /// Serializes the given object (using ) and logs it as a critical error message. + /// + /// The object to serialize. public static void Critical(object obj) { LogMessage_Impl(LogLevel.Critical, obj.ToString()); } [MethodImpl(MethodImplOptions.InternalCall)] - public static extern string LogMessage_Impl(LogLevel logLevel, string message); + private static extern string LogMessage_Impl(LogLevel logLevel, string message); } diff --git a/ScriptCore/Math/Math.cs b/ScriptCore/Math/Math.cs index 6d548c7..685a6e9 100644 --- a/ScriptCore/Math/Math.cs +++ b/ScriptCore/Math/Math.cs @@ -3,6 +3,9 @@ using System.Runtime.CompilerServices; namespace GlitchyEngine.Math; +/// +/// Provides constants and methods for trigonometric and vector calculations. +/// public static class Math { /// An optimal representation of π. @@ -89,28 +92,32 @@ public static class Math #region modf / frac / trunc - // Splits the value x into fractional and integer parts, each of which has the same sign as x. + /// + /// Splits the value x into fractional and integer parts, each of which has the same sign as x. + /// public static float modf(float x, out float integerPart) => ScriptGlue.modf_float(x, out integerPart); - // Splits the value x into fractional and integer parts, each of which has the same sign as x. + /// public static float2 modf(float2 x, out float2 integerPart) => ScriptGlue.modf_float2(x, out integerPart); - - // Splits the value x into fractional and integer parts, each of which has the same sign as x. + + /// public static float3 modf(float3 x, out float3 integerPart) => ScriptGlue.modf_float3(x, out integerPart); - - // Splits the value x into fractional and integer parts, each of which has the same sign as x. + + /// public static float4 modf(float4 x, out float4 integerPart) => ScriptGlue.modf_float4(x, out integerPart); - // Returns the fractional (or decimal) part of x; which is greater than or equal to 0 and less than 1. + /// + /// Returns the fractional (or decimal) part of x; which is greater than or equal to 0 and less than 1. + /// public static float frac(float x) => modf(x, out _); - - // Returns the fractional (or decimal) part of x; which is greater than or equal to 0 and less than 1. + + /// public static float2 frac(float2 x) => modf(x, out _); - - // Returns the fractional (or decimal) part of x; which is greater than or equal to 0 and less than 1. + + /// public static float3 frac(float3 x) => modf(x, out _); - - // Returns the fractional (or decimal) part of x; which is greater than or equal to 0 and less than 1. + + /// public static float4 frac(float4 x) => modf(x, out _); diff --git a/ScriptCore/MouseButton.cs b/ScriptCore/MouseButton.cs index 561afd7..ae47acd 100644 --- a/ScriptCore/MouseButton.cs +++ b/ScriptCore/MouseButton.cs @@ -1,5 +1,8 @@ namespace GlitchyEngine; +/// +/// An enum of all mouse buttons that can be queried using methods in . +/// public enum MouseButton : byte { None = 0, diff --git a/ScriptCore/Physics/Collision2D.cs b/ScriptCore/Physics/Collision2D.cs index a4af231..cf5486e 100644 --- a/ScriptCore/Physics/Collision2D.cs +++ b/ScriptCore/Physics/Collision2D.cs @@ -1,8 +1,12 @@ using System.Runtime.InteropServices; +using GlitchyEngine.Components; using GlitchyEngine.Core; namespace GlitchyEngine.Physics; +/// +/// Represents a collision that occurred between two rigid bodies. +/// [StructLayout(LayoutKind.Sequential, Pack=1)] public struct Collision2D { diff --git a/ScriptCore/Serialization/SerializeFieldAttribute.cs b/ScriptCore/Serialization/SerializeFieldAttribute.cs new file mode 100644 index 0000000..56eb89d --- /dev/null +++ b/ScriptCore/Serialization/SerializeFieldAttribute.cs @@ -0,0 +1,12 @@ +using System; + +namespace GlitchyEngine.Serialization; + +/// +/// Specifies that the field is to be serialized. +/// +/// +[AttributeUsage(AttributeTargets.Field)] +public sealed class SerializeFieldAttribute : Attribute +{ +}