diff --git a/Kerberos/src/Kerberos/Application.cpp b/Kerberos/src/Kerberos/Application.cpp index 542ad13..43b09c3 100644 --- a/Kerberos/src/Kerberos/Application.cpp +++ b/Kerberos/src/Kerberos/Application.cpp @@ -12,6 +12,17 @@ namespace Kerberos { Application* Application::s_Instance = nullptr; + /** + * @brief Constructs the Application singleton and initializes core subsystems. + * + * Initializes the global Application instance, sets the working directory if provided, + * creates the main window and its event callback, initializes the audio manager and loads a default audio resource, + * creates and registers the ImGui overlay, and initializes the renderer and scripting engine. + * + * @param spec Configuration used to initialize the application. Relevant fields: + * - spec.Name: window title. + * - spec.WorkingDirectory: if non-empty, sets the process working directory to this path; otherwise the current path is kept. + */ Application::Application(const ApplicationSpecification& spec) { KBR_PROFILE_FUNCTION(); @@ -49,6 +60,11 @@ namespace Kerberos //m_AudioManager->Play(R"(C:\Users\retek\Music\Technoshock.wav)"); } + /** + * @brief Destroys the Application and cleans up global subsystems. + * + * Performs application teardown tasks, including shutting down the scripting subsystem. + */ Application::~Application() { //Renderer::Shutdown(); @@ -148,4 +164,4 @@ namespace Kerberos for (const auto& func : functions) func(); } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Application.h b/Kerberos/src/Kerberos/Application.h index c196cfb..59a62fb 100644 --- a/Kerberos/src/Kerberos/Application.h +++ b/Kerberos/src/Kerberos/Application.h @@ -12,7 +12,26 @@ #include "Audio/AudioManager.h" -namespace Kerberos +/** + * Holds command-line arguments passed to the application. + * + * Count is the number of arguments; Args is a null-terminated string array of length Count. + */ + + /** + * Access a command-line argument by index. + * @param index Index of the argument to retrieve; must be less than Count. + * @returns The argument string at the given index. + * @note Asserts that index < Count. + */ + + /** + * Application creation configuration. + * + * Name is the application name. WorkingDirectory is the initial working directory. + * CommandLineArgs contains the captured command-line arguments. + */ + namespace Kerberos { struct ApplicationCommandLineArgs { @@ -33,6 +52,11 @@ namespace Kerberos ApplicationCommandLineArgs CommandLineArgs; }; + /** + * Create and initialize the application using the provided specification. + * Initializes core systems including the window, renderer, and ImGui layer. + * @param spec Configuration for the application including Name, WorkingDirectory, and CommandLineArgs. + */ class Application { public: @@ -92,4 +116,3 @@ namespace Kerberos Application* CreateApplication(ApplicationCommandLineArgs args); } - diff --git a/Kerberos/src/Kerberos/Assets/Asset.h b/Kerberos/src/Kerberos/Assets/Asset.h index 0026388..4590dd9 100644 --- a/Kerberos/src/Kerberos/Assets/Asset.h +++ b/Kerberos/src/Kerberos/Assets/Asset.h @@ -5,6 +5,18 @@ #include "Kerberos/Log.h" +/** + * Convert an AssetType value to its corresponding string name. + * @param type The AssetType to convert. + * @returns A `std::string_view` with the name of the asset type (e.g., "Texture2D", "Mesh", "Scene", "Sound"). + * If `type` is not a known AssetType, the function triggers an assertion and returns an empty string. + */ + +/** + * Parse a string name and return the corresponding AssetType enum value. + * @param str The string representation of the asset type (e.g., "Texture2D", "Mesh", "Scene", "Sound"). + * @returns The matching `AssetType`. If `str` is unrecognized, the function triggers an assertion and returns `AssetType::Texture2D`. + */ namespace Kerberos { using AssetHandle = UUID; diff --git a/Kerberos/src/Kerberos/Assets/EditorAssetManager.cpp b/Kerberos/src/Kerberos/Assets/EditorAssetManager.cpp index 66eb86a..3738003 100644 --- a/Kerberos/src/Kerberos/Assets/EditorAssetManager.cpp +++ b/Kerberos/src/Kerberos/Assets/EditorAssetManager.cpp @@ -22,6 +22,12 @@ namespace Kerberos { ".wav", AssetType::Sound } // TODO: Add more audio file types when supported }; + /** + * @brief Determines an AssetType based on a file's extension. + * + * @param filepath Filesystem path whose extension is used to infer the asset type. + * @return AssetType The mapped AssetType for the extension, or `AssetType::Texture2D` if the extension is unrecognized (a warning is logged in that case). + */ static AssetType AssetTypeFromFileExtension(const std::filesystem::path& filepath) { const std::string extension = filepath.extension().string(); @@ -173,6 +179,17 @@ namespace Kerberos file << out.c_str(); } + /** + * @brief Loads the project's AssetRegistry.kbrar and populates the in-memory asset registry. + * + * Attempts to read and parse the YAML asset registry file located in the project's asset directory + * and restores entries into m_AssetRegistry. Valid registry entries must include Handle, Type, and Path. + * Entries whose Type parses to Texture2D, TextureCube, Mesh, or Sound are added; entries with missing + * fields or unsupported types are reported and skipped (assertions are triggered for invalid/unsupported entries). + * + * @return true if the registry file was loaded and processed successfully, false on file load/parsing errors + * or if the registry structure is invalid. + */ bool EditorAssetManager::DeserializeAssetRegistry() { const std::filesystem::path& assetDirectoryPath = Project::GetAssetDirectory(); @@ -235,4 +252,4 @@ namespace Kerberos return true; } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Assets/Importers/AssetImporter.cpp b/Kerberos/src/Kerberos/Assets/Importers/AssetImporter.cpp index b072ca1..5ac2426 100644 --- a/Kerberos/src/Kerberos/Assets/Importers/AssetImporter.cpp +++ b/Kerberos/src/Kerberos/Assets/Importers/AssetImporter.cpp @@ -17,6 +17,16 @@ namespace Kerberos }); } + /** + * @brief Imports an asset according to the provided metadata and returns the created asset. + * + * Selects the appropriate importer based on metadata.Type and delegates the import operation. + * Asserts and returns `nullptr` if the asset type is unsupported. + * + * @param handle Handle to assign to the imported asset. + * @param metadata Metadata describing the asset (includes type and filepath). + * @return Ref Reference to the imported asset, or `nullptr` if the asset type is unsupported. + */ Ref AssetImporter::ImportAsset(const AssetHandle handle, const AssetMetadata& metadata) { switch (metadata.Type) @@ -41,4 +51,4 @@ namespace Kerberos KBR_CORE_ASSERT(false, "Unsupported asset type by AssetImporter!"); return nullptr; } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Assets/Importers/SoundImporter.cpp b/Kerberos/src/Kerberos/Assets/Importers/SoundImporter.cpp index 57017a0..2a27345 100644 --- a/Kerberos/src/Kerberos/Assets/Importers/SoundImporter.cpp +++ b/Kerberos/src/Kerberos/Assets/Importers/SoundImporter.cpp @@ -6,13 +6,25 @@ namespace Kerberos { + /** + * @brief Imports a sound asset using the file path contained in the asset metadata. + * + * @param metadata Asset metadata containing the file path to load. + * @return Ref Reference to the loaded Sound. + */ Ref SoundImporter::ImportSound(AssetHandle, const AssetMetadata& metadata) { return ImportSound(metadata.Filepath); } + /** + * @brief Loads a Sound from the given filesystem path. + * + * @param filepath Filesystem path to the sound file to load. + * @return Ref Reference to the loaded Sound object. + */ Ref SoundImporter::ImportSound(const std::filesystem::path& filepath) { return Application::Get().GetAudioManager()->Load(filepath); } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Assets/Importers/SoundImporter.h b/Kerberos/src/Kerberos/Assets/Importers/SoundImporter.h index 7640896..57021f8 100644 --- a/Kerberos/src/Kerberos/Assets/Importers/SoundImporter.h +++ b/Kerberos/src/Kerberos/Assets/Importers/SoundImporter.h @@ -4,6 +4,18 @@ #include "Kerberos/Assets/AssetMetadata.h" #include "Kerberos/Audio/Sound.h" +/** + * Import a sound asset identified by an asset handle and its metadata. + * @param handle Asset handle that identifies the source asset to import. + * @param metadata Metadata describing the asset (format, settings, source info) used during import. + * @returns Reference to the imported Sound. + */ + +/** + * Import a sound asset from a filesystem path. + * @param filepath Filesystem path to the sound file to import. + * @returns Reference to the imported Sound. + */ namespace Kerberos { class SoundImporter @@ -12,4 +24,4 @@ namespace Kerberos static Ref ImportSound(AssetHandle handle, const AssetMetadata& metadata); static Ref ImportSound(const std::filesystem::path& filepath); }; -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Audio/AudioManager.cpp b/Kerberos/src/Kerberos/Audio/AudioManager.cpp index b9a95d0..2fed0da 100644 --- a/Kerberos/src/Kerberos/Audio/AudioManager.cpp +++ b/Kerberos/src/Kerberos/Audio/AudioManager.cpp @@ -8,7 +8,16 @@ namespace Kerberos { - AudioManager* AudioManager::Create() + /** + * @brief Creates a platform-specific AudioManager instance. + * + * On Windows builds this returns a new XAudio2AudioManager. On unsupported platforms + * the function triggers a core assertion and returns `nullptr`. + * + * @return AudioManager* Pointer to a heap-allocated AudioManager instance appropriate + * for the current platform, or `nullptr` if no implementation exists. Caller takes ownership. + */ +AudioManager* AudioManager::Create() { #ifdef KBR_PLATFORM_WINDOWS return new XAudio2AudioManager(); @@ -17,4 +26,4 @@ namespace Kerberos KBR_CORE_ASSERT(false, "No AudioManager implementation for this platform!"); return nullptr; } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Audio/AudioManager.h b/Kerberos/src/Kerberos/Audio/AudioManager.h index 643ed90..0c55242 100644 --- a/Kerberos/src/Kerberos/Audio/AudioManager.h +++ b/Kerberos/src/Kerberos/Audio/AudioManager.h @@ -6,6 +6,77 @@ #include +/** + * Abstract interface for audio management and playback. + * + * Implementations manage sound loading, playback, and per-sound volume/mute controls. + */ + +/** + * Initialize the audio subsystem and any backend-specific resources. + */ + +/** + * Update the audio subsystem (called per-frame or periodically). + */ + +/** + * Shutdown the audio subsystem and release resources. + */ + +/** + * Load a sound from disk and return a reference to the loaded Sound. + * @param filepath Filesystem path to the sound asset to load. + * @returns A Ref referencing the loaded sound. + */ + +/** + * Play a sound from the given filesystem path. + * @param filepath Filesystem path to the sound asset to play. + */ + +/** + * Play a previously loaded sound identified by its UUID. + * @param soundID UUID of the sound to play. + */ + +/** + * Stop playback of a sound identified by its UUID. + * @param soundID UUID of the sound to stop. + */ + +/** + * Increase the volume of the specified sound by `delta`. + * @param soundID UUID of the sound whose volume will be increased. + * @param delta Amount to increase the volume by. + */ + +/** + * Decrease the volume of the specified sound by `delta`. + * @param soundID UUID of the sound whose volume will be decreased. + * @param delta Amount to decrease the volume by. + */ + +/** + * Set the volume for the specified sound. + * @param soundID UUID of the sound whose volume will be set. + * @param volume New volume level (typically in the range 0.0 to 1.0). + */ + +/** + * Reset the volume of the specified sound to its default level. + * @param soundID UUID of the sound whose volume will be reset. + */ + +/** + * Mute the specified sound. + * @param soundID UUID of the sound to mute. + */ + +/** + * Create and return a concrete AudioManager instance. + * @returns Pointer to a newly created AudioManager instance; the caller takes ownership and is responsible for deleting it. + */ namespace Kerberos { class AudioManager @@ -36,4 +107,4 @@ namespace Kerberos static AudioManager* Create(); }; -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Audio/Sound.cpp b/Kerberos/src/Kerberos/Audio/Sound.cpp index cd6c7de..db7d624 100644 --- a/Kerberos/src/Kerberos/Audio/Sound.cpp +++ b/Kerberos/src/Kerberos/Audio/Sound.cpp @@ -5,38 +5,73 @@ namespace Kerberos { + /** + * @brief Starts playback of this sound. + * + * Begins playing the audio resource associated with this Sound instance via the global audio manager. + */ void Sound::Play() const { Application::Get().GetAudioManager()->Play(m_SoundID); } + /** + * @brief Stops playback of this sound. + * + * Stops playback of the sound identified by this instance's sound ID via the application's AudioManager. + * If the sound is not currently playing, the call has no effect. + */ void Sound::Stop() const { Application::Get().GetAudioManager()->Stop(m_SoundID); } + /** + * @brief Increases this sound's playback volume by the specified amount. + * + * @param delta Amount to increase the current volume by. Positive values raise the volume. + */ void Sound::IncreaseVolume(const float delta) const { Application::Get().GetAudioManager()->IncreaseVolume(m_SoundID, delta); } + /** + * @brief Decreases this sound's playback volume by the specified amount. + * + * @param delta Amount to reduce the current volume by. */ void Sound::DecreaseVolume(const float delta) const { Application::Get().GetAudioManager()->DecreaseVolume(m_SoundID, delta); } + /** + * @brief Set the playback volume for this sound. + * + * @param volume Desired volume level; higher values increase loudness for this sound. + */ void Sound::SetVolume(const float volume) const { Application::Get().GetAudioManager()->SetVolume(m_SoundID, volume); } + /** + * @brief Reset the volume of this sound to its default level. + * + * Invokes the global audio manager to restore this sound's volume to the manager-defined default. + */ void Sound::ResetVolume() const { Application::Get().GetAudioManager()->ResetVolume(m_SoundID); } + /** + * @brief Mutes this sound so it produces no audible output. + * + * After calling this method, the sound remains muted until its volume is changed or it is explicitly unmuted. + */ void Sound::Mute() const { Application::Get().GetAudioManager()->Mute(m_SoundID); } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Audio/Sound.h b/Kerberos/src/Kerberos/Audio/Sound.h index 5a55b1c..bfadf95 100644 --- a/Kerberos/src/Kerberos/Audio/Sound.h +++ b/Kerberos/src/Kerberos/Audio/Sound.h @@ -3,6 +3,60 @@ #include "Kerberos/Core.h" #include "Kerberos/Assets/Asset.h" +/** + * Represents a sound asset and provides playback and volume controls. + */ + +/** + * Construct a Sound with the given name. + * @param name Human-readable name of the sound asset. + */ + +/** + * Begin playback of the sound. + */ + +/** + * Stop playback of the sound. + */ + +/** + * Increase the current volume by `delta`. + * @param delta Amount to increase the volume by (additive). + */ + +/** + * Decrease the current volume by `delta`. + * @param delta Amount to decrease the volume by (subtractive). + */ + +/** + * Set the current volume to `volume`. + * @param volume New volume level. + */ + +/** + * Restore the volume to its default value. + */ + +/** + * Mute the sound. + */ + +/** + * Get the name of the sound asset. + * @returns Reference to the internal name string. + */ + +/** + * Get the asset type for this asset. + * @returns The value `AssetType::Sound`. + */ + +/** + * Get the UUID that identifies this sound in the Audio Manager. + * @returns UUID of the sound asset. + */ namespace Kerberos { class Sound : public Asset @@ -40,4 +94,4 @@ namespace Kerberos */ UUID m_SoundID; }; -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Log.cpp b/Kerberos/src/Kerberos/Log.cpp index fd4346b..64d16eb 100644 --- a/Kerberos/src/Kerberos/Log.cpp +++ b/Kerberos/src/Kerberos/Log.cpp @@ -9,6 +9,19 @@ namespace Kerberos Ref Log::s_CoreLogger; Ref Log::s_ClientLogger; + /** + * @brief Initializes the logging subsystem and configures core and client loggers. + * + * Sets the global log format to "[HH:MM:SS] logger_name: message", creates colorized stdout and file sinks + * for both the core ("KERBEROS") and client ("APP") loggers, and assigns them to the corresponding + * global logger references. + * + * - Console sinks write to stdout and have their sink-level set to `trace`. + * - File sinks write to "Kerberos.log" (core) and "KerberosClient.log" (client) in append mode and have + * their sink-level set to `trace`. + * - Both global logger objects (`s_CoreLogger`, `s_ClientLogger`) are created with their sinks and + * have their logger-level set to `info`. + */ void Log::Init() { // [Timestamp] [name of logger]: [message] diff --git a/Kerberos/src/Kerberos/Renderer/GraphicsContext.h b/Kerberos/src/Kerberos/Renderer/GraphicsContext.h index 95cb228..f505a78 100644 --- a/Kerberos/src/Kerberos/Renderer/GraphicsContext.h +++ b/Kerberos/src/Kerberos/Renderer/GraphicsContext.h @@ -2,6 +2,49 @@ #include +/** + * @brief Compute shader capability limits for the current graphics context. + * + * Contains the maximum supported work group counts, work group sizes, and + * total invocations per work group exposed by the underlying GPU/driver. + */ + +/** + * @brief Maximum number of work groups that can be dispatched in each dimension. + */ + +/** + * @brief Maximum size of a work group (threads) in each dimension. + */ + +/** + * @brief Maximum total invocations (threads) within a single work group per dimension. + */ + +/** + * @brief Abstract interface for a platform-specific graphics context. + * + * Implementations initialize GPU state and present rendered frames. Concrete + * subclasses must provide initialization and buffer swap behaviour. + */ + +/** + * @brief Virtual destructor for proper cleanup in derived contexts. + */ + +/** + * @brief Initialize the graphics context and any associated GPU resources. + */ + +/** + * @brief Present the rendered frame by swapping the front and back buffers. + */ + +/** + * @brief Compute shader capability values for this context. + * + * Populated by concrete implementations to reflect the GPU/driver limits. + */ namespace Kerberos { struct ComputeInfo diff --git a/Kerberos/src/Kerberos/Scene/Scene.cpp b/Kerberos/src/Kerberos/Scene/Scene.cpp index 9e4260c..74ceedc 100644 --- a/Kerberos/src/Kerberos/Scene/Scene.cpp +++ b/Kerberos/src/Kerberos/Scene/Scene.cpp @@ -108,6 +108,14 @@ namespace Kerberos Render3DEditor(camera); } + /** + * @brief Advances the scene by a single timestep: updates subsystems and renders using the primary camera. + * + * Updates native and managed scripts, advances the physics system, updates the audio manager (when the scene is not paused), + * then finds the scene's primary camera and renders either the 3D or 2D runtime view using that camera's transform. + * + * @param ts Time step duration (seconds) used to update scripts, physics, and audio. + */ void Scene::OnUpdateRuntime(const Timestep ts) { KBR_PROFILE_FUNCTION(); @@ -213,6 +221,22 @@ namespace Kerberos m_Registry.destroy(enttId); } + /** + * @brief Creates a duplicate of an entity within the scene. + * + * Creates a new entity whose tag is the original entity's tag suffixed with " Copy", + * copies the transform and any present components from the source entity to the new one, + * and optionally duplicates the source's child hierarchy under the new entity. + * + * Special behavior: + * - CameraComponent on the new entity has its viewport size updated to the scene's current viewport. + * - NativeScriptComponent instantiation and destroy callbacks are set on the copy so the script instance + * is preserved and properly cleaned up for the duplicated entity. + * - RigidBody3DComponent on the copy has its runtime body pointer cleared. + * + * @param entity The entity to duplicate. + * @param duplicateChildren If true, recursively duplicate the entity's children and re-parent them under the new copy. + */ void Scene::DuplicateEntity(const Entity entity, const bool duplicateChildren) { KBR_PROFILE_FUNCTION(); @@ -440,6 +464,25 @@ namespace Kerberos return *m_PhysicsSystem; } + /** + * @brief Creates a new Scene by duplicating the provided source Scene. + * + * Produces a new Scene that contains copies of all entities from the source scene + * with their UUIDs and tags preserved. Copies a broad subset of components so + * the resulting scene reproduces visual, physical, audio, scripting, and environment + * state present in the source. + * + * @param other Source scene to copy. + * @return Ref A new Scene reference containing duplicated entities and components. + * + * The following components are copied when present on an entity: + * TransformComponent, SpriteRendererComponent, CameraComponent (viewport resized to the new scene), + * ScriptComponent, NativeScriptComponent (script instance transferred to the duplicate and lifecycle + * handlers configured), StaticMeshComponent, RigidBody3DComponent (runtime body reset to nullptr), + * BoxCollider3DComponent, SphereCollider3DComponent, CapsuleCollider3DComponent, MeshCollider3DComponent, + * DirectionalLightComponent, PointLightComponent, SpotLightComponent, EnvironmentComponent, + * TextComponent, AudioSource2DComponent, AudioSource3DComponent, and AudioListenerComponent. + */ Ref Scene::Copy(const Ref& other) { Ref newScene = CreateRef(); @@ -964,6 +1007,16 @@ namespace Kerberos {} template <> + /** + * @brief Initializes a MeshCollider3DComponent's mesh from the entity's StaticMeshComponent. + * + * If the entity has a valid StaticMesh in its StaticMeshComponent, assigns that mesh to + * MeshCollider3DComponent::Mesh. If no valid StaticMesh is present, the collider's mesh + * is left unchanged and a warning is emitted. + * + * @param entity The entity that owns the components. + * @param component The MeshCollider3DComponent being initialized. + */ void Scene::OnComponentAdded(const Entity entity, MeshCollider3DComponent& component) { const auto& smc = entity.GetComponent(); @@ -981,22 +1034,57 @@ namespace Kerberos {} template <> + /** + * @brief Hook invoked when a TextComponent is added to an entity in the scene. + * + * This specialization is called by the scene when a TextComponent is attached to the given entity + * and provides a place to initialize or configure the component for editor/runtime use. + * + * @param entity The entity that received the TextComponent. + * @param component The TextComponent instance that was added. + */ void Scene::OnComponentAdded(Entity entity, TextComponent& component) { } template <> + /** + * @brief Invoked when an AudioSource3DComponent is attached to an entity. + * + * This specialization is called immediately after an AudioSource3DComponent is added to the given entity. + * It is intentionally empty and serves as a placeholder for future initialization or registration logic. + * + * @param entity The entity that received the component. + * @param component The newly added AudioSource3DComponent instance. + */ void Scene::OnComponentAdded(Entity entity, AudioSource3DComponent& component) { } template <> + /** + * @brief Handler invoked when an AudioSource2DComponent is added to an entity; currently a no-op. + * + * This specialization is provided as a hook for future initialization or side effects required + * when a 2D audio source component is attached to an entity. At present it performs no actions. + * + * @param entity The entity receiving the component. + * @param component The added AudioSource2DComponent instance. + */ void Scene::OnComponentAdded(Entity entity, AudioSource2DComponent& component) { } template <> + /** + * @brief Called when an AudioListenerComponent is added to an entity. + * + * Specialization hook provided for initializing or configuring audio listener state when the component is attached. + * + * @param entity The entity receiving the AudioListenerComponent. + * @param component The newly added AudioListenerComponent. + */ void Scene::OnComponentAdded(Entity entity, AudioListenerComponent& component) { } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Scene/SceneSerializer.cpp b/Kerberos/src/Kerberos/Scene/SceneSerializer.cpp index 7ab6926..fe147ab 100644 --- a/Kerberos/src/Kerberos/Scene/SceneSerializer.cpp +++ b/Kerberos/src/Kerberos/Scene/SceneSerializer.cpp @@ -105,6 +105,20 @@ namespace Kerberos return out; } + /** + * @brief Serializes an Entity and any of its present components into the given YAML emitter as a YAML map. + * + * The function writes the entity UUID and, for each component the entity has, emits a component-specific map + * containing that component's properties. Supported components include: + * TagComponent, TransformComponent, SpriteRendererComponent, CameraComponent, HierarchyComponent, + * ScriptComponent, NativeScriptComponent (placeholder), DirectionalLightComponent, PointLightComponent, + * SpotLightComponent, RigidBody3DComponent, BoxCollider3DComponent, SphereCollider3DComponent, + * CapsuleCollider3DComponent, MeshCollider3DComponent, StaticMeshComponent, EnvironmentComponent, + * TextComponent, AudioSource3DComponent, AudioSource2DComponent, and AudioListenerComponent. + * + * @param out YAML::Emitter to which the entity map will be written. + * @param entity The Entity to serialize; only components present on this entity will be emitted. + */ static void SerializeEntity(YAML::Emitter& out, const Entity entity) { out << YAML::BeginMap; @@ -499,6 +513,17 @@ namespace Kerberos throw std::logic_error("Not implemented"); } + /** + * @brief Deserialize a scene from a YAML file and recreate its entities and components in the associated Scene. + * + * Reads the YAML at the given filesystem path, parses the scene name and the "Entities" sequence, and for each entity + * reconstructs the entity with its UUID, tag, transform, and any present components (camera, sprite renderer, hierarchy, + * script, lights, physics colliders, mesh/static mesh, environment, text, and audio components), loading referenced assets + * when handles are present. + * + * @param filepath Path to the YAML scene file to deserialize. + * @return true if the file was parsed and the scene deserialized; `false` if the file is invalid or does not contain a top-level "Scene" node. + */ bool SceneSerializer::Deserialize(const std::filesystem::path& filepath) const { const std::ifstream inFile(filepath); @@ -817,4 +842,4 @@ namespace Kerberos { throw std::logic_error("Not implemented"); } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Scripting/ScriptInterface.cpp b/Kerberos/src/Kerberos/Scripting/ScriptInterface.cpp index 792aa76..3150495 100644 --- a/Kerberos/src/Kerberos/Scripting/ScriptInterface.cpp +++ b/Kerberos/src/Kerberos/Scripting/ScriptInterface.cpp @@ -242,6 +242,14 @@ namespace Kerberos return ScriptEngine::StringToMonoString(fontPath); } + /** + * @brief Sets the font file path for the TextComponent of the specified entity. + * + * @param entityID UUID of the entity whose TextComponent font path will be set. + * @param fontPath Managed string containing the font file path. + * + * @throws std::runtime_error Always thrown because this function is not implemented yet. + */ static void TextComponent_SetFontPath(const UUID entityID, const MonoString* fontPath) { KBR_CORE_ASSERT(fontPath == nullptr, "Null pointer passed to fontPath"); @@ -249,6 +257,13 @@ namespace Kerberos throw std::runtime_error("TextComponent_SetFontPath is not implemented yet"); } + /** + * @brief Starts playback of the AudioSource2DComponent attached to the specified entity. + * + * If the entity has an AudioSource2DComponent with a loaded SoundAsset, playback is initiated. + * + * @param entityID UUID of the entity whose AudioSource2DComponent should be played. + */ static void AudioSource2DComponent_Play(const UUID entityID) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -261,6 +276,13 @@ namespace Kerberos } } + /** + * @brief Stops playback of the entity's 2D audio source, if one is attached. + * + * If the entity has an AudioSource2DComponent with a loaded SoundAsset, this will call Stop() on that asset. + * + * @param entityID UUID of the entity whose AudioSource2DComponent should be stopped. + */ static void AudioSource2DComponent_Stop(const UUID entityID) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -273,6 +295,12 @@ namespace Kerberos } } + /** + * @brief Retrieves the playback volume for a 2D audio source on the specified entity. + * + * @param entityID UUID of the entity that owns the AudioSource2DComponent. + * @return float Current volume of the audio source (typically in range 0.0 to 1.0). + */ static float AudioSource2DComponent_GetVolume(const UUID entityID) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -282,6 +310,14 @@ namespace Kerberos return audioComponent.Volume; } + /** + * @brief Sets the playback volume on an entity's AudioSource2DComponent. + * + * Updates the AudioSource2DComponent::Volume for the entity identified by the given UUID. + * + * @param entityID UUID of the entity whose audio source volume will be set. + * @param volume New volume value to assign to the audio source. + */ static void AudioSource2DComponent_SetVolume(const UUID entityID, const float volume) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -291,6 +327,12 @@ namespace Kerberos audioComponent.Volume = volume; } + /** + * @brief Set the looping state of an entity's AudioSource2DComponent. + * + * @param entityID UUID of the entity whose AudioSource2DComponent will be modified. + * @param loop `true` to enable looping, `false` to disable looping. + */ static void AudioSource2DComponent_SetLooping(const UUID entityID, const bool loop) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -300,6 +342,12 @@ namespace Kerberos audioComponent.Loop = loop; } + /** + * @brief Retrieves whether the 2D audio source on the given entity is set to loop. + * + * @param entityID UUID of the entity to query. + * @return `true` if the entity's AudioSource2DComponent has looping enabled, `false` otherwise. + */ static bool AudioSource2DComponent_IsLooping(const UUID entityID) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -310,6 +358,13 @@ namespace Kerberos } + /** + * @brief Plays the 3D audio clip attached to an entity's AudioSource3DComponent. + * + * Invokes Play() on the component's SoundAsset if the entity's AudioSource3DComponent has a valid SoundAsset; otherwise does nothing. + * + * @param entityID UUID of the target entity in the current scene. + */ static void AudioSource3DComponent_Play(const UUID entityID) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -322,6 +377,14 @@ namespace Kerberos } } + /** + * @brief Stops playback of the 3D audio source attached to the given entity. + * + * If the entity's AudioSource3DComponent has an associated SoundAsset, that asset's + * Stop() method is invoked. If no SoundAsset is present, the function has no effect. + * + * @param entityID UUID of the entity whose AudioSource3DComponent should be stopped. + */ static void AudioSource3DComponent_Stop(const UUID entityID) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -334,6 +397,12 @@ namespace Kerberos } } + /** + * @brief Retrieves the playback volume of an entity's AudioSource3DComponent. + * + * @param entityID UUID of the entity whose audio volume is requested. + * @return float Current volume of the AudioSource3DComponent. + */ static float AudioSource3DComponent_GetVolume(const UUID entityID) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -343,6 +412,14 @@ namespace Kerberos return audioComponent.Volume; } + /** + * @brief Sets the playback volume for an entity's 3D audio source and applies it to the underlying sound asset. + * + * Updates the AudioSource3DComponent's Volume field for the specified entity and forwards the value to the associated SoundAsset. + * + * @param entityID UUID of the entity whose 3D audio source volume will be set. + * @param volume New volume level to apply to the component and sound asset. + */ static void AudioSource3DComponent_SetVolume(const UUID entityID, const float volume) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -353,6 +430,12 @@ namespace Kerberos audioComponent.SoundAsset->SetVolume(volume); } + /** + * @brief Sets whether the AudioSource3DComponent on the entity should loop playback. + * + * @param entityID UUID of the entity whose AudioSource3DComponent will be modified. + * @param loop `true` to enable looping, `false` to disable it. + */ static void AudioSource3DComponent_SetLooping(const UUID entityID, const bool loop) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -362,6 +445,12 @@ namespace Kerberos audioComponent.Loop = loop; } + /** + * @brief Determines whether the 3D audio source on the given entity is set to loop. + * + * @param entityID UUID of the entity to query. + * @return `true` if the entity's AudioSource3DComponent is configured to loop playback, `false` otherwise. + */ static bool AudioSource3DComponent_IsLooping(const UUID entityID) { const std::weak_ptr& scene = ScriptEngine::GetSceneContext(); @@ -373,11 +462,24 @@ namespace Kerberos + /** + * @brief Checks whether the specified keyboard key is currently pressed. + * + * @param key KeyCode identifying the keyboard key to check. + * @return true if the key is currently pressed, false otherwise. + */ static bool Input_IsKeyDown(const KeyCode key) { return Input::IsKeyPressed(key); } + /** + * @brief Registers native functions as internal calls available to managed scripts. + * + * @details Binds the engine's native entry points (logging, entity queries, transform and + * physics accessors, text and audio component accessors, and input queries) so they can be + * invoked from the scripting runtime. + */ void ScriptInterface::RegisterFunctions() { KBR_ADD_INTERNAL_CALL(NativeLog); @@ -438,6 +540,12 @@ namespace Kerberos s_EntityHasComponentFunctions[managedType] = [](const Entity entity) { return entity.HasComponent(); }; } + /** + * @brief Registers engine component types with the scripting runtime so managed code can identify and query them. + * + * Retrieves the core assembly image and registers the set of engine component types that are exposed to C# scripts. + * Asserts that the core assembly image is available before registration. + */ void ScriptInterface::RegisterComponentTypes() { MonoImage* coreImage = ScriptEngine::GetCoreAssemblyImage(); @@ -466,4 +574,4 @@ namespace Kerberos RegisterComponent(coreImage); } -} +} \ No newline at end of file diff --git a/Kerberos/src/Kerberos/Utils/PlatformUtils.h b/Kerberos/src/Kerberos/Utils/PlatformUtils.h index adb4ffe..47f72b2 100644 --- a/Kerberos/src/Kerberos/Utils/PlatformUtils.h +++ b/Kerberos/src/Kerberos/Utils/PlatformUtils.h @@ -1,5 +1,30 @@ #pragma once +/** + * Open a system file-open dialog and return the selected file's absolute path. + * @param filter A file type filter in the form "Description (*.ext1;*.ext2)|*.ext1;*.ext2". + * @return An absolute path to the selected file, or an empty string if the dialog was cancelled. + */ +/** + * Open a system file-save dialog and return the selected file's absolute path. + * @param filter A file type filter in the form "Description (*.ext1;*.ext2)|*.ext1;*.ext2". + * @return An absolute path to the selected file, or an empty string if the dialog was cancelled. + */ +/** + * Open the specified file with the system's default associated application. + * @param path The path to the file to open. + * @return `true` if the file was successfully opened, `false` otherwise. + */ +/** + * Delete the file at the specified path. + * @param path A null-terminated string specifying the path of the file to delete. + * @return `true` if the file was successfully deleted, `false` otherwise. + */ +/** + * Reveal the specified path in the system file explorer. + * @param path The path to reveal. + * @return `true` if the path was successfully revealed, `false` otherwise. + */ namespace Kerberos { class FileDialog diff --git a/Kerberos/src/Platform/OpenGL/OpenGLContext.cpp b/Kerberos/src/Platform/OpenGL/OpenGLContext.cpp index e650c92..4c5fa6a 100644 --- a/Kerberos/src/Platform/OpenGL/OpenGLContext.cpp +++ b/Kerberos/src/Platform/OpenGL/OpenGLContext.cpp @@ -6,12 +6,29 @@ namespace Kerberos { + /** + * @brief Constructs an OpenGLContext bound to the given GLFW window. + * + * Associates this OpenGLContext with the provided GLFWwindow pointer so the context can be made current and used for GL operations. + * + * @param windowHandle Pointer to the GLFWwindow whose OpenGL context will be managed. Must not be null. + * + * The constructor asserts that `windowHandle` is not null. */ OpenGLContext::OpenGLContext(GLFWwindow* windowHandle) : m_WindowHandle(windowHandle) { KBR_CORE_ASSERT(windowHandle, "Window handle is null!"); } + /** + * @brief Initializes the OpenGL context associated with the stored GLFW window. + * + * Makes the window's OpenGL context current, loads GL function pointers, queries and stores + * compute shader limits, and logs vendor, renderer, OpenGL and GLSL version information + * along with the retrieved compute shader limits. + * + * @note This function will assert if the GL loader (Glad) fails to initialize. + */ void OpenGLContext::Init() { KBR_PROFILE_FUNCTION(); @@ -47,6 +64,12 @@ namespace Kerberos m_ComputeInfo.MaxWorkGroupInvocations.z); } + /** + * @brief Presents the rendered frame by swapping the window's front and back buffers. + * + * Swaps the associated GLFW window's back buffer to the front so the most recently + * rendered framebuffer becomes visible on screen. + */ void OpenGLContext::SwapBuffers() { KBR_PROFILE_FUNCTION(); @@ -54,6 +77,19 @@ namespace Kerberos glfwSwapBuffers(m_WindowHandle); } + /** + * @brief Queries and stores GPU compute shader work-group limits. + * + * Retrieves the per-dimension limits for compute shader dispatch from OpenGL + * and writes them into the OpenGLContext's m_ComputeInfo structure. Specifically, + * it populates: + * - m_ComputeInfo.MaxWorkGroupCount (GL_MAX_COMPUTE_WORK_GROUP_COUNT) + * - m_ComputeInfo.MaxWorkGroupSize (GL_MAX_COMPUTE_WORK_GROUP_SIZE) + * - m_ComputeInfo.MaxWorkGroupInvocations (GL_MAX_COMPUTE_WORK_GROUP_INVOCATIONS) + * + * Each stored value is a glm::vec3 containing the x, y, and z components as + * unsigned integers. + */ void OpenGLContext::QueryComputeInfo() { int maxWorkGroupCount[3]; @@ -90,4 +126,3 @@ namespace Kerberos ); } } - diff --git a/Kerberos/src/Platform/OpenGL/OpenGLContext.h b/Kerberos/src/Platform/OpenGL/OpenGLContext.h index 2960383..d0ed0ed 100644 --- a/Kerberos/src/Platform/OpenGL/OpenGLContext.h +++ b/Kerberos/src/Platform/OpenGL/OpenGLContext.h @@ -4,6 +4,22 @@ #include +/** + * Construct an OpenGLContext for the given GLFW window handle. + * @param windowHandle Pointer to the GLFW window associated with this context. + */ + +/** + * Initialize the OpenGL context for the associated GLFW window and prepare any required OpenGL state. + */ + +/** + * Present the currently rendered frame by swapping the window's front and back buffers. + */ + +/** + * Query and cache device and compute-related capabilities (e.g., compute shader limits, work group sizes). + */ namespace Kerberos { class OpenGLContext final : public GraphicsContext @@ -22,4 +38,3 @@ namespace Kerberos }; } - diff --git a/Kerberos/src/Platform/OpenGL/OpenGLRendererAPI.cpp b/Kerberos/src/Platform/OpenGL/OpenGLRendererAPI.cpp index c1ee951..1f59d92 100644 --- a/Kerberos/src/Platform/OpenGL/OpenGLRendererAPI.cpp +++ b/Kerberos/src/Platform/OpenGL/OpenGLRendererAPI.cpp @@ -5,6 +5,19 @@ namespace Kerberos { + /** + * @brief Formats an OpenGL debug message with source and type labels and logs it at a level corresponding to the message severity. + * + * Composes a human-readable message that prefixes the GL message with its source and type, then emits the composed string to the core logger using a severity-appropriate logging macro. + * + * @param source GL debug message source (GLenum). + * @param type GL debug message type (GLenum). + * @param id GL-assigned message ID. + * @param severity GL debug message severity (GLenum). + * @param length Length of the message string, in bytes. + * @param message Pointer to the message text (null-terminated C string). + * @param userParam User-supplied pointer passed through from glDebugMessageCallback. + */ static void OpenGLMessageCallback( unsigned source, unsigned type, @@ -145,4 +158,4 @@ namespace Kerberos glDrawArrays(GL_TRIANGLES, 0, static_cast(vertexCount)); } -} +} \ No newline at end of file diff --git a/Kerberos/src/Platform/OpenGL/OpenGLShader.cpp b/Kerberos/src/Platform/OpenGL/OpenGLShader.cpp index 1f3dd10..ef7363d 100644 --- a/Kerberos/src/Platform/OpenGL/OpenGLShader.cpp +++ b/Kerberos/src/Platform/OpenGL/OpenGLShader.cpp @@ -31,6 +31,16 @@ namespace Kerberos return 0; } + /** + * @brief Map an OpenGL shader stage value to the corresponding shaderc GLSL shader kind. + * + * Converts a GLenum representing an OpenGL shader stage (for example, GL_VERTEX_SHADER, + * GL_FRAGMENT_SHADER, or GL_GEOMETRY_SHADER) into the matching shaderc_shader_kind. + * The function asserts if an unsupported stage value is provided. + * + * @param stage OpenGL shader stage enum. + * @return shaderc_shader_kind Corresponding shaderc GLSL shader kind. + */ static shaderc_shader_kind GLShaderStageToShaderC(const GLenum stage) { switch (stage) @@ -44,6 +54,12 @@ namespace Kerberos return static_cast(0); } + /** + * @brief Convert an OpenGL shader stage enum to its string representation. + * + * @param stage OpenGL shader stage value; expected `GL_VERTEX_SHADER`, `GL_FRAGMENT_SHADER`, or `GL_GEOMETRY_SHADER`. + * @return const char* String literal naming the provided stage (for example, `"GL_VERTEX_SHADER"`). + */ static const char* GLShaderStageToString(const GLenum stage) { switch (stage) @@ -389,6 +405,18 @@ namespace Kerberos m_RendererID = program; } + /** + * @brief Compile GLSL sources to Vulkan SPIR-V or load them from the on-disk cache and reflect their resources. + * + * Compiles each provided shader source to Vulkan SPIR-V using shaderc when the cached binary is missing or older + * than the source; otherwise loads the SPIR-V from the cache. Populates the object's m_VulkanSPIRV map, writes + * newly compiled binaries to the cache directory, and invokes reflection for each stage. + * + * Side effects: + * - Updates m_VulkanSPIRV with compiled or cached SPIR-V data. + * - May write compiled SPIR-V files to the cache directory. + * - Logs compilation/cache activity and asserts on compilation failures. + */ void OpenGLShader::CompileOrGetVulkanBinaries(const std::unordered_map& shaderSources) { KBR_CORE_INFO("\nCompiling shader: {}", m_FilePath); @@ -511,6 +539,18 @@ namespace Kerberos Reflect(stage, data); } + /** + * @brief Ensures OpenGL-compatible SPIR-V binaries are available for each shader stage. + * + * Cross-compiles the stored Vulkan SPIR-V for each stage to OpenGL GLSL, compiles that GLSL + * to OpenGL SPIR-V, and populates the shader object's OpenGL artifacts. Uses a cache directory + * to load or store compiled OpenGL SPIR-V when available and up-to-date with the source file. + * + * Side effects: + * - Updates the member containers `m_OpenGLSPIRV` and `m_OpenGLSourceCode`. + * - Reads from and writes to the shader cache directory on disk. + * - Logs status and may assert on fatal compilation or cross-compilation failures. + */ void OpenGLShader::CompileOrGetOpenGLBinaries() { auto& shaderData = m_OpenGLSPIRV; @@ -655,6 +695,15 @@ namespace Kerberos Reflect(stage, data);*/ } + /** + * @brief Create and link an OpenGL program from cached SPIR-V shader binaries. + * + * Creates a GL program, loads each SPIR-V module in m_OpenGLSPIRV as a specialized shader, + * attaches them, links the program, and on success stores the program id in m_RendererID. + * Per-stage shader object IDs are recorded in m_OpenGLShaderIDs. Intermediate shader objects + * are detached and deleted after linking. If linking fails, an error is logged, the program + * and shader objects are deleted, and an assertion is triggered. + */ void OpenGLShader::CreateProgram() { const GLuint program = glCreateProgram(); @@ -707,6 +756,18 @@ namespace Kerberos m_RendererID = program; } + /** + * @brief Reflects a SPIR-V shader module and emits its resource metadata for a given GL shader stage. + * + * Inspects the provided SPIR-V binary and reports information about uniform buffers, sampled images + * (textures/samplers), storage buffers, storage images, and push constant blocks for the specified + * shader stage. The reported metadata includes names, descriptor set, binding, sizes, array/descriptor + * counts and member offsets where applicable. + * + * @param stage The OpenGL shader stage enum (e.g., GL_VERTEX_SHADER, GL_FRAGMENT_SHADER, GL_GEOMETRY_SHADER) + * that identifies which stage the SPIR-V module represents. + * @param shaderData The SPIR-V binary data for the shader stage used as the source for reflection. + */ void OpenGLShader::Reflect(const GLenum stage, const std::vector& shaderData) { const spirv_cross::Compiler compiler(shaderData); @@ -818,4 +879,4 @@ namespace Kerberos KBR_CORE_TRACE(" Name: {0}, Offset: {1}, Size: {2}", resource.name, offset, size); } } -} +} \ No newline at end of file diff --git a/Kerberos/src/Platform/Vulkan/VulkanContext.cpp b/Kerberos/src/Platform/Vulkan/VulkanContext.cpp index da1511b..c8be945 100644 --- a/Kerberos/src/Platform/Vulkan/VulkanContext.cpp +++ b/Kerberos/src/Platform/Vulkan/VulkanContext.cpp @@ -1060,6 +1060,17 @@ namespace Kerberos return commandBuffer; } + /** + * @brief Submits a command buffer to the graphics queue and blocks until execution completes. + * + * Ends the provided primary command buffer, submits it to the context's graphics queue using a + * temporary fence, waits for the fence to signal completion, and then destroys the fence. + * + * @param commandBuffer The primary command buffer to end, submit, and wait for. + * + * @throws std::runtime_error If ending the command buffer, creating the fence, submitting the + * queue, or waiting for the fence fails. + */ void VulkanContext::SubmitCommandBuffer(const VkCommandBuffer commandBuffer) const { constexpr uint64_t fenceWaitTimeout = 10000000000000; @@ -1101,6 +1112,12 @@ namespace Kerberos vkDestroyFence(m_Device, fence, nullptr); } + /** + * @brief Obtain the GPU device address of a Vulkan buffer. + * + * @param buffer Vulkan buffer whose device address will be queried. + * @return uint64_t The device address associated with `buffer`. + */ uint64_t VulkanContext::GetBufferDeviceAddress(const VkBuffer buffer) const { // TODO: Store the enabled extensions and features and check if buffer device address is enabled @@ -1111,6 +1128,14 @@ namespace Kerberos } + /** + * @brief Verifies that all requested Vulkan validation layers are available on the system. + * + * Queries the instance layer properties and checks each entry in the `validationLayers` list + * is present among the available layers. + * + * @return `true` if every requested validation layer in `validationLayers` is supported, `false` otherwise. + */ bool VulkanContext::CheckValidationLayerSupport() { uint32_t layerCount; @@ -1316,4 +1341,4 @@ namespace Kerberos return actualExtent; } -} +} \ No newline at end of file diff --git a/Kerberos/src/Platform/Vulkan/VulkanContext.h b/Kerberos/src/Platform/Vulkan/VulkanContext.h index e930929..932dc21 100644 --- a/Kerberos/src/Platform/Vulkan/VulkanContext.h +++ b/Kerberos/src/Platform/Vulkan/VulkanContext.h @@ -11,6 +11,22 @@ #include "VulkanBuffer.h" +/** + * Acquire a command buffer intended for single-use recording. + * + * @returns A command buffer ready for one-time command recording; caller must submit it after recording. + */ +/** + * Submit a recorded command buffer to the device for execution. + * + * @param commandBuffer The command buffer containing recorded commands to submit. + */ +/** + * Retrieve the device address for a buffer that supports shader device addresses. + * + * @param buffer The Vulkan buffer whose device address to query. The buffer must have been created with VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT and the VK_KHR_buffer_device_address feature/extension enabled. + * @returns The 64-bit device address of the specified buffer. + */ namespace Kerberos { class VulkanContext : public GraphicsContext @@ -157,4 +173,4 @@ namespace Kerberos static VulkanContext* s_Instance; }; -} +} \ No newline at end of file diff --git a/Kerberos/src/Platform/Windows/Audio/XAudio2AudioManager.cpp b/Kerberos/src/Platform/Windows/Audio/XAudio2AudioManager.cpp index 52ab231..1d22994 100644 --- a/Kerberos/src/Platform/Windows/Audio/XAudio2AudioManager.cpp +++ b/Kerberos/src/Platform/Windows/Audio/XAudio2AudioManager.cpp @@ -5,11 +5,26 @@ namespace Kerberos { + /** + * @brief Releases audio manager resources and performs shutdown. + * + * Ensures XAudio2 resources, mastering voice, and COM state managed by the audio + * manager are cleaned up before destruction. + */ XAudio2AudioManager::~XAudio2AudioManager() { XAudio2AudioManager::Shutdown(); } + /** + * @brief Initializes the XAudio2 audio subsystem and prepares a mastering voice. + * + * Initializes the COM library for multithreaded use, creates the XAudio2 engine instance, + * and creates a mastering voice used for audio output. When built with KBR_DEBUG, applies + * XAUDIO2 debug configuration to the engine. Logs success on completion. + * + * @throws std::runtime_error If COM initialization, XAudio2 creation, or mastering voice creation fails. + */ void XAudio2AudioManager::Init() { HRESULT res = CoInitializeEx(nullptr, COINIT_MULTITHREADED); @@ -52,6 +67,11 @@ namespace Kerberos } + /** + * @brief Updates playback state and cleans up finished source voices. + * + * Iterates through tracked playing audio source voices, stops and destroys any voice that has no queued buffers, removes its entry from the playing-audio map, and logs the outcome. Leaves voices with queued buffers unchanged. + */ void XAudio2AudioManager::Update() { for (auto it = m_PlayingAudios.begin(); it != m_PlayingAudios.end(); ) @@ -77,6 +97,12 @@ namespace Kerberos } } + /** + * @brief Releases XAudio2 resources and uninitializes COM for the audio manager. + * + * Destroys the mastering voice if present, releases the XAudio2 instance, clears internal pointers, + * and calls CoUninitialize to uninitialize the COM library. + */ void XAudio2AudioManager::Shutdown() { if (m_MasteringVoice) @@ -92,6 +118,16 @@ namespace Kerberos CoUninitialize(); } + /** + * Loads an audio file, creates a Sound for PCM WAV files, and registers its ID-to-filepath mapping. + * + * Detects the audio format of `filepath`. If the file is PCM (WAV), creates a Sound using the file stem + * as the name, stores the mapping from the Sound's UUID to `filepath`, and returns a Ref to the created Sound. + * For unsupported or unimplemented formats, returns nullptr. + * + * @param filepath Filesystem path to the audio file to load. + * @return Ref Reference to the created Sound on success, or `nullptr` if the format is unsupported or loading failed. + */ Ref XAudio2AudioManager::Load(const std::filesystem::path& filepath) { const AudioFormat format = DetectAudioFormat(filepath); @@ -118,6 +154,16 @@ namespace Kerberos return nullptr; } + /** + * Plays a previously loaded WAV file identified by its filesystem path. + * + * Looks up the WAV data that must have been loaded earlier; if the file is not loaded + * or contains no audio data, the function logs an error and returns. Otherwise it + * creates an XAudio2 source voice, submits the audio buffer, starts playback, and + * records the voice in the manager's playing-audio map for later control and cleanup. + * + * @param filepath Filesystem path to the WAV file that was loaded into the manager. + */ void XAudio2AudioManager::Play(const std::filesystem::path& filepath) { const auto it = m_LoadedWAVs.find(filepath); @@ -163,6 +209,13 @@ namespace Kerberos KBR_CORE_INFO("Playing WAV file: {0}", filepath.string()); } + /** + * Plays the sound associated with the given sound UUID. + * + * If the UUID is not mapped to a loaded file, the function logs an error and returns without playing. + * + * @param soundID UUID of the sound to play. + */ void XAudio2AudioManager::Play(const UUID& soundID) { const auto filepath = m_SoundUUIDToFilepath.find(soundID); @@ -175,6 +228,13 @@ namespace Kerberos Play(filepath->second); } + /** + * Stops playback of the sound identified by `soundID` and releases its associated source voice. + * + * If `soundID` is not mapped to a loaded filepath or the sound is not currently playing, the function logs an error and returns without side effects. On success, the source voice is stopped, destroyed, and the playing entry is removed. + * + * @param soundID UUID of the sound to stop. + */ void XAudio2AudioManager::Stop(const UUID& soundID) { const auto filepath = m_SoundUUIDToFilepath.find(soundID); @@ -203,6 +263,15 @@ namespace Kerberos m_PlayingAudios.erase(it); } + /** + * @brief Increases the playback volume for a currently playing sound by the specified delta. + * + * If the sound ID is unknown or the sound is not currently playing, the function logs an error and returns without changing volume. + * If setting the new volume fails, the function logs an error. + * + * @param soundID UUID of the sound whose volume will be increased. + * @param delta Amount to add to the current volume (linear scale). + */ void XAudio2AudioManager::IncreaseVolume(const UUID& soundID, const float delta) { const auto filepath = m_SoundUUIDToFilepath.find(soundID); @@ -228,6 +297,15 @@ namespace Kerberos } } + /** + * @brief Decreases the playback volume of a currently playing sound. + * + * Looks up the sound by its UUID and subtracts `delta` from the sound's current volume. + * If the UUID is unknown or the sound is not playing, the call has no effect. + * + * @param soundID UUID of the sound whose volume will be decreased. + * @param delta Amount to subtract from the current volume (linear scale). + */ void XAudio2AudioManager::DecreaseVolume(const UUID& soundID, const float delta) { const auto filepath = m_SoundUUIDToFilepath.find(soundID); @@ -253,6 +331,16 @@ namespace Kerberos } } + /** + * @brief Sets the playback volume for a currently playing sound. + * + * Sets the volume for the sound identified by `soundID` if that sound is currently playing. + * The value is linear where 1.0 is the original (unmodified) volume and 0.0 is silence. + * If `soundID` is not known or the sound is not currently playing, the call has no effect. + * + * @param soundID Unique identifier of the sound. + * @param volume Linear volume multiplier to apply to the sound (1.0 = original, 0.0 = mute). + */ void XAudio2AudioManager::SetVolume(const UUID& soundID, const float volume) { const auto filepath = m_SoundUUIDToFilepath.find(soundID); @@ -275,17 +363,33 @@ namespace Kerberos } } + /** + * @brief Resets the playback volume for a sound to the default level. + * + * @param soundID UUID identifying the sound whose volume will be set to 1.0f. + */ void XAudio2AudioManager::ResetVolume(const UUID& soundID) { SetVolume(soundID, 1.0f); } + /** + * @brief Mutes the sound associated with the given ID by setting its volume to 0. + * + * @param soundID UUID of the sound to mute. + */ void XAudio2AudioManager::Mute(const UUID& soundID) { SetVolume(soundID, 0.0f); } + /** + * @brief Determines the audio format of a file by its extension. + * + * @param filepath Filesystem path to the audio file whose format should be detected. + * @return AudioFormat The detected format: `FormatPcm` for `.wav`, `FormatAdpcm` for `.adpcm`, `FormatIeeeFloat` for `.f32`, or `FormatUnknown` if the extension is unrecognized. + */ AudioFormat XAudio2AudioManager::DetectAudioFormat(const std::filesystem::path& filepath) { const std::string extension = filepath.extension().string(); @@ -304,6 +408,21 @@ namespace Kerberos return AudioFormat::FormatUnknown; } + /** + * @brief Loads a PCM WAV file from disk and stores its parsed audio data for playback. + * + * Parses the RIFF/WAVE file at the given path, extracts the 'fmt ' chunk into a WAVEFORMATEX + * structure and the 'data' chunk into a raw byte buffer, then stores the result in + * m_LoadedWAVs keyed by the provided filepath. + * + * If the file cannot be opened, is not a valid RIFF/WAVE file, or is missing either the + * 'fmt ' or 'data' chunk (or the data chunk is empty), the function logs an error and + * returns without modifying m_LoadedWAVs. + * + * @param filepath Filesystem path to the WAV file to load. Only PCM/WAVE formats with a + * standard 'fmt ' chunk are supported; extra format bytes (chunkSize > 16) + * are skipped and cbSize is set to 0 for the parsed format. + */ void XAudio2AudioManager::LoadWavFile(const std::filesystem::path& filepath) { std::ifstream file(filepath, std::ios::binary); @@ -389,4 +508,4 @@ namespace Kerberos m_LoadedWAVs[filepath] = std::move(soundData); } -} +} \ No newline at end of file diff --git a/Kerberos/src/Platform/Windows/Audio/XAudio2AudioManager.h b/Kerberos/src/Platform/Windows/Audio/XAudio2AudioManager.h index bf7ff3e..ae018dc 100644 --- a/Kerberos/src/Platform/Windows/Audio/XAudio2AudioManager.h +++ b/Kerberos/src/Platform/Windows/Audio/XAudio2AudioManager.h @@ -8,6 +8,100 @@ #include +/** + * @enum AudioFormat + * @brief Supported audio data formats. + * + * Enumerates recognized container/codec types for loaded audio data. + */ + +/** + * @struct AudioData + * @brief Holds decoded audio format metadata and raw sample bytes. + * + * Contains a WAVEFORMATEX describing the sample format, a contiguous buffer + * of raw audio bytes, and the detected AudioFormat. + */ + +/** + * @class XAudio2AudioManager + * @brief Platform implementation of the AudioManager using XAudio2. + * + * Manages initialization and shutdown of the XAudio2 engine, loading of WAV + * assets, playback control, and per-sound volume management. + */ + +/** + * @brief Initialize the XAudio2 engine and related resources. + */ + +/** + * @brief Perform per-frame audio manager work (e.g., cleanup finished voices). + */ + +/** + * @brief Shutdown the XAudio2 engine and release all audio resources. + */ + +/** + * @brief Load a sound from disk and register it with the audio manager. + * @param filepath Filesystem path to the audio file to load. + * @returns Ref Reference to the loaded sound resource. + */ + +/** + * @brief Play a sound identified by a filesystem path. + * @param filepath Filesystem path of a previously loaded sound. + */ + +/** + * @brief Play a sound identified by its UUID. + * @param soundID Unique identifier of the sound to play. + */ + +/** + * @brief Stop playback of a sound identified by its UUID. + * @param soundID Unique identifier of the sound to stop. + */ + +/** + * @brief Increase the playback volume of a sound by a delta. + * @param soundID Unique identifier of the sound. + * @param delta Amount to add to the current volume. + */ + +/** + * @brief Decrease the playback volume of a sound by a delta. + * @param soundID Unique identifier of the sound. + * @param delta Amount to subtract from the current volume. + */ + +/** + * @brief Set the playback volume of a sound. + * @param soundID Unique identifier of the sound. + * @param volume Absolute volume level to set. + */ + +/** + * @brief Reset the playback volume of a sound to its default value. + * @param soundID Unique identifier of the sound. + */ + +/** + * @brief Mute or unmute a sound. + * @param soundID Unique identifier of the sound. + */ + +/** + * @brief Detect the audio format for a file based on its path or header. + * @param filepath Filesystem path to the audio file to inspect. + * @returns AudioFormat The detected audio format enum value. + */ + +/** + * @brief Load WAV file contents into the manager's in-memory structures. + * @param filepath Filesystem path to the WAV file to load. + */ namespace Kerberos { enum class AudioFormat : uint8_t @@ -69,4 +163,4 @@ namespace Kerberos std::unordered_map m_SoundUUIDToFilepath; std::unordered_map m_PlayingAudios; }; -} +} \ No newline at end of file diff --git a/Kerberos/src/Platform/Windows/WindowsPlatformUtils.cpp b/Kerberos/src/Platform/Windows/WindowsPlatformUtils.cpp index 33b4bf0..02f67d3 100644 --- a/Kerberos/src/Platform/Windows/WindowsPlatformUtils.cpp +++ b/Kerberos/src/Platform/Windows/WindowsPlatformUtils.cpp @@ -56,6 +56,14 @@ namespace Kerberos return {}; } + /** + * @brief Open the specified file with the system default handler and wait for the launched process to exit. + * + * Attempts to launch the given file using the system "open" verb and blocks until the opened process terminates. + * + * @param path Path to the file to open. If `path` is null or empty, the function returns `false`. + * @return true if the file was successfully launched and the launched process exited, `false` otherwise. + */ bool FileOperations::OpenFile(const char* path) { if (!path || path[0] == '\0') @@ -84,6 +92,12 @@ namespace Kerberos return false; } + /** + * @brief Delete the file at the specified filesystem path. + * + * @param path Path to the file to delete. + * @return true if the file was successfully removed, false otherwise. + */ bool FileOperations::Delete(const char* path) { if (!path || path[0] == '\0') @@ -100,6 +114,15 @@ namespace Kerberos return false; } + /** + * @brief Opens Windows File Explorer and selects the specified file. + * + * Opens Explorer with the given path selected. If Explorer is launched successfully, this function + * waits until the Explorer process terminates before returning. + * + * @param path Path to the file to reveal; must be a non-empty, null-terminated string. + * @return true if Explorer was launched and the operation completed, false otherwise. + */ bool FileOperations::RevealInFileExplorer(const char* path) { if (!path || path[0] == '\0') @@ -128,4 +151,4 @@ namespace Kerberos KBR_CORE_ERROR("Failed to reveal file in explorer: {0}, Error code: {1}", path, error); return false; } -} +} \ No newline at end of file diff --git a/KerberosEditor/src/Editor/AssetConstants.h b/KerberosEditor/src/Editor/AssetConstants.h index 6c281cb..9a2c40b 100644 --- a/KerberosEditor/src/Editor/AssetConstants.h +++ b/KerberosEditor/src/Editor/AssetConstants.h @@ -1,5 +1,32 @@ #pragma once +/** + * @brief Identifier for a generic asset browser item type. + */ + +/** + * @brief Identifier for a 2D texture asset type in the asset browser. + */ + +/** + * @brief Identifier for a cubemap (texture cube) asset type in the asset browser. + */ + +/** + * @brief Identifier for a mesh asset type in the asset browser. + */ + +/** + * @brief Identifier for a scene asset type in the asset browser. + */ + +/** + * @brief Identifier for an audio asset type in the asset browser. + */ + +/** + * @brief Identifier for a font asset type in the asset browser. + */ namespace Kerberos { constexpr const char* ASSET_BROWSER_ITEM = "ASSET_BROWSER_ITEM"; @@ -9,4 +36,4 @@ namespace Kerberos constexpr const char* ASSET_BROWSER_SCENE = "ASSET_BROWSER_SCENE"; constexpr const char* ASSET_BROWSER_AUDIO = "ASSET_BROWSER_AUDIO"; constexpr const char* ASSET_BROWSER_FONT = "ASSET_BROWSER_FONT"; -} +} \ No newline at end of file diff --git a/KerberosEditor/src/Editor/AssetsPanel.cpp b/KerberosEditor/src/Editor/AssetsPanel.cpp index 340c6f3..29fa768 100644 --- a/KerberosEditor/src/Editor/AssetsPanel.cpp +++ b/KerberosEditor/src/Editor/AssetsPanel.cpp @@ -27,6 +27,18 @@ namespace Kerberos } + /** + * @brief Render the Assets panel UI and handle user interactions. + * + * Displays the current assets directory and either an asset-mode view (hierarchical + * assets) or a filesystem-mode view (folder contents), and processes user actions: + * navigation (enter/back), toggling modes, refreshing the asset tree, importing files, + * creating context menus, deleting files/folders, opening files, initiating drag-and-drop + * payloads for assets, and caching image thumbnails for display. + * + * This function updates panel state such as the current directory, active mode, the + * asset thumbnail cache, and the in-memory asset tree as users interact with the UI. + */ void AssetsPanel::OnImGuiRender() { ImGui::Begin("Assets"); @@ -370,6 +382,14 @@ namespace Kerberos } } + /** + * @brief Starts an ImGui drag-and-drop source for an asset and sets the payload and preview according to the asset's file extension or type. + * + * Determines the payload type and preview shown during drag based on the file extension (".jpg", ".png", ".svg" => ASSET_BROWSER_TEXTURE; ".kbrcubemap" => ASSET_BROWSER_TEXTURE_CUBE; ".obj" => ASSET_BROWSER_MESH) or when the resolved AssetType is Sound (ASSET_BROWSER_AUDIO). The provided AssetHandle is used as the payload data; an available texture asset is shown as a 64×64 thumbnail for image payloads, otherwise the filename or "Invalid Texture" text is shown. + * + * @param handle AssetHandle to use as the drag payload. + * @param filename Filesystem path of the asset; its extension is used to select payload type and preview behavior. + */ void AssetsPanel::HandleAssetDragAndDrop(const AssetHandle handle, const std::filesystem::path& filename) { if (ImGui::BeginDragDropSource()) @@ -419,4 +439,4 @@ namespace Kerberos KBR_CORE_ERROR("Invalid directory path: {0}", path.string()); } -} +} \ No newline at end of file diff --git a/KerberosEditor/src/Editor/AssetsPanel.h b/KerberosEditor/src/Editor/AssetsPanel.h index e5f0f4b..2453266 100644 --- a/KerberosEditor/src/Editor/AssetsPanel.h +++ b/KerberosEditor/src/Editor/AssetsPanel.h @@ -11,6 +11,31 @@ #include "imgui/imgui.h" +/** + * Set the current directory displayed by the assets panel. + * @param path Filesystem path to use as the current directory. + */ + +/** + * Display a context menu for a file entry in the assets panel. + * @param path Iterator reference to the file's path within the current directory listing. + */ + +/** + * Display a context menu for a folder entry in the assets panel. + * @param path Iterator reference to the folder's path within the current directory listing. + */ + +/** + * Display a context menu for an empty area of the assets panel using the provided ImGui popup flags. + * @param popupFlags ImGui popup flags to control menu behavior when opened. + */ + +/** + * Handle a drag-and-drop operation for an asset onto a target filename. + * @param handle Asset handle being dragged. + * @param filename Target filename or path the asset was dropped onto. + */ namespace Kerberos { class AssetsPanel @@ -84,4 +109,3 @@ namespace Kerberos }; } - diff --git a/KerberosEditor/src/Editor/HierarchyPanel.cpp b/KerberosEditor/src/Editor/HierarchyPanel.cpp index cea6d71..aee4dbc 100644 --- a/KerberosEditor/src/Editor/HierarchyPanel.cpp +++ b/KerberosEditor/src/Editor/HierarchyPanel.cpp @@ -21,6 +21,14 @@ namespace Kerberos { + /** + * @brief Creates a HierarchyPanel bound to a scene and initializes panel state. + * + * Initializes the panel with the provided scene context and loads editor state and assets + * by calling SetContext with the given scene reference. + * + * @param context Reference to the Scene that this panel will display and operate on. + */ HierarchyPanel::HierarchyPanel(const Ref& context) : m_Context(context) { @@ -177,6 +185,14 @@ namespace Kerberos } } + /** + * @brief Renders an "Add Component" ImGui popup and adds the selected component to the given entity. + * + * Presents a popup menu with component categories (including Physics and Audio). When a menu item is chosen, + * the corresponding component is added to the provided entity and the popup is closed. + * + * @param entity The entity to which the selected component will be added. + */ void HierarchyPanel::AddComponentPopup(Entity entity) { if (ImGui::Button("Add Component")) @@ -432,6 +448,17 @@ namespace Kerberos ImGui::PopID(); } + /** + * @brief Renders and exposes editable UI controls for all components attached to the given entity. + * + * Displays collapsible sections for each present component (Tag, Transform, Camera, Script, Sprite, lights, + * Static Mesh, physics colliders/bodies, Environment, Text, audio components, etc.), providing controls to + * view and modify their properties. Each component section includes a settings popup that can remove the + * component. Changing transform values triggers recalculation of the entity's transform. Drag-and-drop handlers + * allow assigning assets (meshes, textures, fonts, cubemaps, sounds) and will emit error notifications on type mismatch. + * + * @param entity The entity whose components are shown and edited. + */ void HierarchyPanel::DrawComponents(const Entity entity) { if (entity.HasComponent()) @@ -1614,4 +1641,4 @@ namespace Kerberos } } } -} +} \ No newline at end of file diff --git a/KerberosEditor/src/EditorLayer.cpp b/KerberosEditor/src/EditorLayer.cpp index e05fca0..c348be2 100644 --- a/KerberosEditor/src/EditorLayer.cpp +++ b/KerberosEditor/src/EditorLayer.cpp @@ -23,6 +23,16 @@ namespace Kerberos { } + /** + * @brief Initialize the editor layer, project, and editor scene state. + * + * Creates the active editor scene (or opens/creates a project based on command-line + * arguments or user selection), configures the editor camera and viewport size, + * imports editor assets (textures, sprite sheet, subtextures, toolbar icons), and + * performs initial scene setup such as creating optional test entities, obtaining + * the primary camera entity, setting the hierarchy context, calculating initial + * world transforms, and setting the default gizmo operation. + */ void EditorLayer::OnAttach() { KBR_PROFILE_FUNCTION(); @@ -650,6 +660,14 @@ namespace Kerberos m_HierarchyPanel.SetContext(m_ActiveScene); } + /** + * @brief Handles drag-and-drop payloads dropped onto the editor viewport. + * + * Detects ImGui drag-and-drop targets and accepts payloads matching ASSET_BROWSER_ITEM. + * When a payload is accepted, logs and enqueues an informational notification containing + * the payload path. If the payload corresponds to a Scene asset, retrieves the scene asset + * (the function does not automatically open it). + */ void EditorLayer::HandleDragAndDrop() { if (ImGui::BeginDragDropTarget()) @@ -976,4 +994,4 @@ namespace Kerberos m_ActiveScene = m_EditorScene; } -} +} \ No newline at end of file diff --git a/KerberosScriptCoreLib/Source/InternalCalls.cs b/KerberosScriptCoreLib/Source/InternalCalls.cs index f4653a5..2efa97f 100644 --- a/KerberosScriptCoreLib/Source/InternalCalls.cs +++ b/KerberosScriptCoreLib/Source/InternalCalls.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Runtime.CompilerServices; using Kerberos.Source.Kerberos.Core; using Kerberos.Source.Kerberos.Scene; @@ -76,50 +76,108 @@ public static class InternalCalls [MethodImpl(MethodImplOptions.InternalCall)] internal static extern string TextComponent_GetFontPath(ulong entityID); - // ----------------------------- Input ----------------------------- + /// + /// Check whether the specified keyboard key is currently pressed. + /// + /// The key to check. + /// `true` if the specified key is currently pressed, `false` otherwise. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern bool Input_IsKeyDown(KeyCode key); - // ------------------------- AudioSource2DComponent -------------------------- + /// + /// Plays the 2D audio source attached to the specified entity. + /// + /// The unique identifier of the entity with the AudioSource2D component. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern void AudioSource2DComponent_Play(ulong entityID); + /// + /// Stops playback of the 2D audio source attached to the specified entity. + /// + /// The unique identifier of the entity whose 2D audio source will be stopped. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern void AudioSource2DComponent_Stop(ulong entityID); + /// + /// Sets the playback volume for the 2D audio source component on the specified entity. + /// + /// ID of the entity that owns the 2D audio source component. + /// Volume multiplier where 1.0 represents the original volume. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern void AudioSource2DComponent_SetVolume(ulong entityID, float volume); + /// + /// Retrieves the current volume level of the 2D audio source attached to the specified entity. + /// + /// The entity identifier whose 2D audio source volume is requested. + /// The volume level as a float. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern float AudioSource2DComponent_GetVolume(ulong entityID); + /// + /// Enables or disables looping for the 2D audio source attached to the specified entity. + /// + /// The entity's unique identifier. + /// `true` to enable looping, `false` to disable it. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern void AudioSource2DComponent_SetLooping(ulong entityID, bool looping); + /// + /// Determines whether the 2D audio source on the specified entity is set to loop. + /// + /// The entity's unique identifier. + /// `true` if the audio source is set to loop, `false` otherwise. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern bool AudioSource2DComponent_IsLooping(ulong entityID); - // ------------------------- AudioSource3DComponent -------------------------- + /// + /// Plays the 3D audio source attached to the specified entity. + /// + /// The unique identifier of the entity. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern void AudioSource3DComponent_Play(ulong entityID); + /// + /// Stops playback of the specified entity's 3D audio source. + /// + /// The unique identifier of the entity whose 3D audio source will be stopped. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern void AudioSource3DComponent_Stop(ulong entityID); + /// + /// Sets the playback volume for the 3D audio source attached to the specified entity. + /// + /// The identifier of the entity that owns the 3D audio source. + /// Desired volume level (engine-defined scale). [MethodImpl(MethodImplOptions.InternalCall)] internal static extern void AudioSource3DComponent_SetVolume(ulong entityID, float volume); + /// + /// Gets the playback volume of the 3D audio source attached to the specified entity. + /// + /// The entity's unique identifier. + /// The volume level where 0.0 is silent and 1.0 is the original/full volume. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern float AudioSource3DComponent_GetVolume(ulong entityID); + /// + /// Sets whether the 3D audio source attached to the specified entity should loop playback. + /// + /// The unique identifier of the entity containing the audio source. + /// `true` to enable looping, `false` to disable it. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern void AudioSource3DComponent_SetLooping(ulong entityID, bool looping); + /// + /// Determines whether the 3D audio source on the specified entity is set to loop. + /// + /// The unique identifier of the entity containing the 3D audio source component. + /// `true` if looping is enabled on the entity's 3D audio source component, `false` otherwise. [MethodImpl(MethodImplOptions.InternalCall)] internal static extern bool AudioSource3DComponent_IsLooping(ulong entityID); } -} +} \ No newline at end of file diff --git a/KerberosScriptCoreLib/Source/Kerberos/Player.cs b/KerberosScriptCoreLib/Source/Kerberos/Player.cs index 75366a9..708fbbe 100644 --- a/KerberosScriptCoreLib/Source/Kerberos/Player.cs +++ b/KerberosScriptCoreLib/Source/Kerberos/Player.cs @@ -1,4 +1,4 @@ -using System; +using System; using Kerberos.Source.Kerberos.Core; using Kerberos.Source.Kerberos.Scene; @@ -16,6 +16,9 @@ public class Player : Entity // Implement OnXButtonClicked methods for private bool _isPlayingAudio = false; + /// + /// Initializes a new Player instance with default field values. + /// internal Player() : base() { } @@ -24,6 +27,12 @@ public Player(ulong id) : base(id) { } + /// + /// Initialize the player after it is created by caching the TransformComponent, any present optional components (RigidBody3DComponent and AudioSource2DComponent), and resolving the scene Camera entity. + /// + /// + /// Also writes a creation message containing the entity ID to the console. + /// protected override void OnCreate() { Console.WriteLine($"Player::OnCreate - {ID}"); @@ -42,6 +51,13 @@ protected override void OnCreate() } + /// + /// Processes player input each frame to move the player, optionally apply a physics impulse, adjust camera zoom, and control 2D audio playback. + /// + /// Time elapsed since the last update used to scale movement and camera zoom adjustments. + /// + /// If a rigidbody component is present and the impulse key is pressed, an impulse is applied and the rest of the update is skipped for that frame. Camera zoom and audio controls only take effect when their respective components are available. + /// protected override void OnUpdate(float deltaTime) { Vector3 velocity = Vector3.Zero; @@ -88,4 +104,4 @@ protected override void OnUpdate(float deltaTime) } } } -} +} \ No newline at end of file diff --git a/KerberosScriptCoreLib/Source/Kerberos/Scene/Components.cs b/KerberosScriptCoreLib/Source/Kerberos/Scene/Components.cs index 522ee43..77819b6 100644 --- a/KerberosScriptCoreLib/Source/Kerberos/Scene/Components.cs +++ b/KerberosScriptCoreLib/Source/Kerberos/Scene/Components.cs @@ -1,4 +1,4 @@ -using Kerberos.Source.Kerberos.Core; +using Kerberos.Source.Kerberos.Core; using System; using System.IO; @@ -115,19 +115,31 @@ public string FontPath public class AudioSource2DComponent : Component { - public void Play() => InternalCalls.AudioSource2DComponent_Play(Entity.ID); - - public void Stop() => InternalCalls.AudioSource2DComponent_Stop(Entity.ID); + /// +/// Starts playing the audio clip attached to this component. +/// +public void Play() => InternalCalls.AudioSource2DComponent_Play(Entity.ID); + + /// +/// Stops playback of the 2D audio source attached to this component. +/// +public void Stop() => InternalCalls.AudioSource2DComponent_Stop(Entity.ID); } public class AudioSource3DComponent : Component { - public void Play() => InternalCalls.AudioSource3DComponent_Play(Entity.ID); - - public void Stop() => InternalCalls.AudioSource3DComponent_Stop(Entity.ID); + /// +/// Starts playback of the audio clip associated with this 3D audio source component. +/// +public void Play() => InternalCalls.AudioSource3DComponent_Play(Entity.ID); + + /// +/// Stops playback of the 3D audio source attached to this component's entity. +/// +public void Stop() => InternalCalls.AudioSource3DComponent_Stop(Entity.ID); } public class AudioListenerComponent : Component { } -} +} \ No newline at end of file