### Building UltraStar Play with Nuke Build Tool Source: https://github.com/ultrastar-deluxe/play/wiki/Download-and-Install These commands demonstrate how to use the `build.sh` (Linux/macOS) or `build.ps1` (Windows) script to manage dependencies and build the UltraStar Play project. It covers restoring dependencies for the main game and companion app, and then building the main game for Windows 64-bit and the companion app for Android APK. The Nuke build tool and .NET are required. ```bash # Restore dependencies ./build.sh RestoreMainGameDependencies ./build.sh RestoreCompanionAppDependencies # Build projects ./build.sh BuildMainGameWindows64 ./build.sh BuildCompanionAppAndroidApk ``` -------------------------------- ### Dependency Injection with UniInject in C# Source: https://context7.com/ultrastar-deluxe/play/llms.txt Demonstrates how to use UniInject for dependency injection in Unity. Classes implement INeedInjection and use [Inject] attributes. Injection happens in Awake(), before Start(). Includes examples for managers, scene scripts, and binders. ```csharp using UniInject; using UnityEngine; // Singleton pattern using DontDestroyOnLoadManager public class MyManager : MonoBehaviour { public static MyManager Instance => DontDestroyOnLoadManager.FindComponentOrThrow(); } // Inject dependencies into your scripts public class MySingSceneScript : MonoBehaviour, INeedInjection, IInjectionFinishedListener { [Inject] private SceneNavigator sceneNavigator; [Inject] private SettingsManager settingsManager; [Inject] private SongMetaManager songMetaManager; [Inject] private ThemeManager themeManager; // Called after all injections complete for this object public void OnInjectionFinished() { // Safe to use injected dependencies here Settings settings = settingsManager.Settings; Debug.Log($"Current language: {settings.CultureInfoName}"); Debug.Log($"Current theme: {settings.ThemeName}"); } void Start() { // Injected fields are guaranteed to be set by Start() var songs = songMetaManager.GetSongMetas(); Debug.Log($"Loaded {songs.Count} songs"); } } // Binder example - bind objects for injection in a scene public class MySingSceneBinder : MonoBehaviour, IBinder { [SerializeField] private SongAudioPlayer songAudioPlayer; [SerializeField] private SongVideoPlayer songVideoPlayer; public List GetBindings() { BindingBuilder bb = new(); bb.Bind(songAudioPlayer); bb.Bind(songVideoPlayer); return bb.GetBindings(); } } ``` -------------------------------- ### UltraStar TXT Song File Format Example Source: https://context7.com/ultrastar-deluxe/play/llms.txt This example demonstrates the structure of a typical UltraStar txt song file. It includes metadata headers, note definitions with timing and pitch, and lyrics. The format supports various note types like normal, golden, freestyle, and rap. ```txt #TITLE:My Cool Song (Duett) #ARTIST:My Cool Artist #MP3:audio.ogg #BPM:100 #GAP:7500 #COVER:cover-image.jpg #BACKGROUND:background-image.jpg #VIDEO:video.mp4 #VIDEOGAP:5 #GENRE:Pop #YEAR:2007 #LANGUAGE:English #PREVIEWSTART:30 #MEDLEYSTARTBEAT:200 #MEDLEYENDBEAT:800 #P1:Singer 1 #P2:Singer 2 P1 : 0 5 0 Hello : 10 5 0 world! - 15 : 20 5 0 How * 30 5 2 are * 40 5 4 you? - 45 P2 : 50 5 0 Hello : 60 5 0 world! - 70 E ``` -------------------------------- ### Cloning the UltraStar Play Git Repository Source: https://github.com/ultrastar-deluxe/play/wiki/Download-and-Install This command clones the UltraStar Play project from its official GitHub repository. It requires Git to be installed on your system. After cloning, you will have the complete source code to build or inspect the project. ```git git clone https://github.com/UltraStar-Deluxe/Play.git ``` -------------------------------- ### Serializable Class Example in C# Source: https://github.com/ultrastar-deluxe/play/wiki/Implementation-Details Provides an example of a C# class annotated with [Serializable] to make its properties visible in the Unity inspector. It highlights the difference between serializable properties (with get and set) and non-serializable ones. ```csharp [Serializable] public class Bla { public int MySerializableProperty { get; private set; } public int MyNonSerialzableProperty { get; } public Bla() { MySerializableProperty = 1; MyNonSerialzableProperty = 2; } } ``` -------------------------------- ### UltraStar TXT File Structure Example Source: https://github.com/ultrastar-deluxe/play/wiki/UltraStar-txt-File-Format An example of a typical UltraStar Deluxe `.txt` file, demonstrating the metadata section, player-specific note lines, and phrase endings. ```plaintext #TITLE:My Cool Song (Duett) #ARTIST:My Cool Artist #MP3:audio.ogg #BPM:100 #GAP:7500 #COVER:cover-image.jpg #BACKGROUND:background-image-used-when-video-file-not-working.jpg #GENRE:Pop #YEAR:2007 #LANGUAGE:English P1 : 0 5 0 Hello : 10 5 0 world! - 15 : 20 5 0 How * 30 5 2 are * 40 5 4 you? - 45 P2 : 50 5 0 Hello : 60 5 0 world! - 70 E ``` -------------------------------- ### C# Class and Enum Declaration Example Source: https://github.com/ultrastar-deluxe/play/wiki/Code-Style Demonstrates C# class structure, access modifiers, properties, events, and enum declaration according to UltraStar Play conventions. It shows explicit typing and constructor shorthand. ```csharp public class MySceneControl { public int publicField; int packagePrivate; private int myPrivate; protected int myProtected; public string MyProperty { get; private set; } public event Action ValueChanged; public MySceneControl() { List stringList = new(); } } public enum EDay { Today, Tomorrow } public interface IXmlReader { void ReadXml(string filePath); } ``` -------------------------------- ### Base Unity MonoBehaviour Script for Ultrastar Deluxe Player Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play Companion/Assets/ScriptTemplates/81-C This C# script serves as a base MonoBehaviour for the Ultrastar Deluxe player in Unity. It includes standard Unity lifecycle methods like Start and Update, and implements INeedInjection for dependency injection. No specific functionality is implemented in Start or Update in this base class. ```csharp using System; using System.Collections; using System.Collections.Generic; using System.Linq; using UnityEngine; using UnityEngine.UI; using UniInject; using UniRx; // Disable warning about fields that are never assigned, their values are injected. #pragma warning disable CS0649 public class #SCRIPTNAME# : MonoBehaviour, INeedInjection { private void Start() { } private void Update() { } } ``` -------------------------------- ### Specify Unity Path for Build (Nuke) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Allows specifying the exact path to the Unity executable if it's not automatically detected by the build system. This is crucial in environments with multiple Unity versions or non-standard installations. ```bash ./build.sh BuildMainGameWindows64 \ --unity-executable '/home/user/Unity/Hub/Editor/6000.1.0f1/Editor/Unity' ``` -------------------------------- ### Subscribing to InputActions with UniRx (C#) Source: https://github.com/ultrastar-deluxe/play/wiki/Input-System-(InputActions) Shows how to use the InputManager to get an InputAction and subscribe to its 'Performed' event using UniRx Observables. This pattern is commonly used in scene-specific input control classes. ```csharp InputManager.GetInputAction(R.InputActions.usplay_back).PerformedAsObservable() .Subscribe(_ => highscoreSceneController.FinishScene()); ``` -------------------------------- ### Fixing macOS File Permissions for UltraStar Play Source: https://github.com/ultrastar-deluxe/play/wiki/Download-and-Install This snippet provides commands to resolve file permission issues on macOS when running UltraStar Play. It uses `chmod` to make the application executable and `xattr` to remove quarantine attributes, ensuring the app can be run without security restrictions. Ensure the file names match your downloaded version. ```bash chmod +x UltraStarPlay-v0.9.0-macOS.app chmod +x UltraStarPlay-v0.9.0-macOS.app/Contents/MacOS/UltraStar\ Play xattr -dr com.apple.quarantine UltraStarPlay-v0.9.0-macOS.app ``` -------------------------------- ### Get Translations (API) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Retrieves translation strings for the current language setting of the application. This is a GET request to the translations endpoint. ```bash curl http://localhost:6789/api/rest/translations ``` -------------------------------- ### Get Player Statistics (API) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Fetches statistical data related to player performance and game metrics. This is a GET request to the stats endpoint. ```bash curl http://localhost:6789/api/rest/stats ``` -------------------------------- ### Get Available Microphones (API) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Retrieves a list of available microphones connected to the system. The response is a JSON object containing an 'Items' array, where each item represents a microphone with its 'Name' and 'IsEnabled' status. ```bash curl http://localhost:6789/api/rest/availableMicrophones ``` -------------------------------- ### Website Translation Configuration (next-i18next) Source: https://github.com/ultrastar-deluxe/play/wiki/Translations,-Internationalization-(I18N) Configuration for website internationalization using next-i18next. The `locales` array in `next-i18next.config.js` needs to be updated to include new languages. This setup generates static HTML pages for each language. ```javascript module.exports = { i18n: { locales: ['en', 'fr', 'es'], // Example: Add French and Spanish defaultLocale: 'en', }, }; ``` -------------------------------- ### Get Current Song Queue (API) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Fetches the current list of songs in the playback queue. The response is a JSON object with an 'Items' array, where each item includes 'SongId' and 'PlayerNames' associated with that song. ```bash curl http://localhost:6789/api/rest/songQueue ``` -------------------------------- ### Ultrastar Deluxe Player Script Structure (C#) Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play/Assets/ScriptTemplates/81-C This C# script defines the basic structure for the Ultrastar Deluxe player. It includes necessary Unity and UniInject namespaces, and implements the INeedInjection interface. The Start and Update methods are provided as placeholders for game logic. ```csharp using System; using System.Collections; using System.Collections.Generic; using System.Linq; using UnityEngine; using UnityEngine.UIElements; using UniInject; using UniRx; // Disable warning about fields that are never assigned, their values are injected. #pragma warning disable CS0649 public class #SCRIPTNAME# : MonoBehaviour, INeedInjection { private void Start() { } private void Update() { } } ``` -------------------------------- ### Dependency Injection with UniInject Source: https://context7.com/ultrastar-deluxe/play/llms.txt UltraStar Play utilizes UniInject for managing dependencies. Classes can implement `INeedInjection` and use `[Inject]` attributes to receive dependencies. Injection is performed during `Awake()`, ensuring dependencies are ready before `Start()` methods are called. ```APIDOC ## Dependency Injection with UniInject UltraStar Play uses UniInject for dependency injection. Classes implement `INeedInjection` and use `[Inject]` attributes. Injection occurs during `Awake()`, completing before `Start()` methods run. ### Example Usage ```csharp using UniInject; using UnityEngine; // Singleton pattern using DontDestroyOnLoadManager public class MyManager : MonoBehaviour { public static MyManager Instance => DontDestroyOnLoadManager.FindComponentOrThrow(); } // Inject dependencies into your scripts public class MySingSceneScript : MonoBehaviour, INeedInjection, IInjectionFinishedListener { [Inject] private SceneNavigator sceneNavigator; [Inject] private SettingsManager settingsManager; [Inject] private SongMetaManager songMetaManager; [Inject] private ThemeManager themeManager; // Called after all injections complete for this object public void OnInjectionFinished() { // Safe to use injected dependencies here Settings settings = settingsManager.Settings; Debug.Log($"Current language: {settings.CultureInfoName}"); Debug.Log($"Current theme: {settings.ThemeName}"); } void Start() { // Injected fields are guaranteed to be set by Start() var songs = songMetaManager.GetSongMetas(); Debug.Log($"Loaded {songs.Count} songs"); } } // Binder example - bind objects for injection in a scene public class MySingSceneBinder : MonoBehaviour, IBinder { [SerializeField] private SongAudioPlayer songAudioPlayer; [SerializeField] private SongVideoPlayer songVideoPlayer; public List GetBindings() { BindingBuilder bb = new(); bb.Bind(songAudioPlayer); bb.Bind(songVideoPlayer); return bb.GetBindings(); } } ``` ``` -------------------------------- ### EditorConfig for IDE Code Style Configuration Source: https://github.com/ultrastar-deluxe/play/wiki/Code-Style Shows how the `.editorconfig` file is used to configure IDEs to adhere to the project's code style guidelines. This ensures consistency across different development environments. ```editorconfig # EditorConfig helps maintain consistent coding styles between different # editors and IDEs. The file is processed from the root directory down. # For more information, see http://EditorConfig.org root = true [*] # Indentation indent_style = space indent_size = 4 # Newlines end_of_line = lf insert_final_newline = true # Character encoding charset = utf-8 # Language specific settings for C# [*.cs] # Braces style csharp_style_block_based_functions = true:space # Explicitly typed variables csharp_style_var_when_type_is_known = false # Constructor name shorthand csharp_style_explicit_type_in_object_creation = false # Naming conventions (examples, actual rules are more complex) # dotnet_naming_rule.uppercase_fields.severity = warning # dotnet_naming_rule.uppercase_fields.symbols.field.style = pascal_case # Use private where possible csharp_style_readonly_field_promotion = true # Avoid static where possible # (No direct EditorConfig rule for avoiding static, relies on convention) ``` -------------------------------- ### Command Line Parameters Source: https://context7.com/ultrastar-deluxe/play/llms.txt Information on how to launch UltraStar Play with command-line parameters to customize settings at startup. ```APIDOC ## Command Line Parameters ### Description Launch UltraStar Play with command line parameters to customize settings at startup. ### Usage Examples **Windows - use custom settings file:** ```bash "UltraStar Play.exe" --settingsPath "C:\my-settings.json" ``` **Linux/macOS - use custom settings file:** ```bash ./build.sh RestoreMainGameDependencies ./build.sh RestoreCompanionAppDependencies ``` **Override specific settings via JSON:** ```bash "UltraStar Play.exe" --settingsOverwriteJson '{"GraphicSettings":{"useImageAsCursor":false}}' ``` **Combine both parameters:** ```bash ./build.sh BuildMainGameWindows64 \ --settingsPath "/custom/settings.json" \ --settingsOverwriteJson '{"CultureInfoName":"de","ThemeName":"dark"}' ``` ``` -------------------------------- ### Launch with Custom Settings File (Command Line) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Launches UltraStar Play using a specified JSON file for settings. This allows for persistent custom configurations. The path to the settings file is provided as an argument. ```bash "UltraStar Play.exe" --settingsPath "C:\my-settings.json" ./UltraStar\ Play --settingsPath "/home/user/my-settings.json" ``` -------------------------------- ### Show Build Targets and Help (Nuke) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Displays available build targets and general help information for the Nuke build system. This is the first step to understanding the build process. ```bash ./build.sh --help ./build.ps1 --help ``` -------------------------------- ### Combine Settings Path and Overwrite (Command Line) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Demonstrates how to use both `--settingsPath` and `--settingsOverwriteJson` parameters simultaneously. This allows loading a base settings file and then applying specific overrides. ```bash ./UltraStar\ Play \ --settingsPath "/custom/settings.json" \ --settingsOverwriteJson '{"CultureInfoName":"de","ThemeName":"dark"}' ``` -------------------------------- ### Scene Navigation with SceneData in C# Source: https://context7.com/ultrastar-deluxe/play/llms.txt Illustrates scene navigation using SceneNavigator and SceneData. Shows how to pass data like song information and player profiles when loading scenes, and how to retrieve this data in the destination scene. Includes default data handling. ```csharp using System.Collections.Generic; using UniInject; using UnityEngine; public class SongSelectController : MonoBehaviour, INeedInjection { [Inject] private SceneNavigator sceneNavigator; public void StartSinging(SongMeta selectedSong, List players) { // Create scene data with song and player information SingSceneData singSceneData = new SingSceneData { SongMetas = new List { selectedSong }, SingScenePlayerData = new SingScenePlayerData { PlayerProfiles = players }, PositionInMillis = 0, StartPaused = false }; // Navigate to sing scene with data sceneNavigator.LoadScene(EScene.SingScene, singSceneData); } public void StartMedley(List songs) { SingSceneData medleyData = new SingSceneData { SongMetas = songs, MedleySongIndex = 0 // Marks this as a medley }; sceneNavigator.LoadScene(EScene.SingScene, medleyData); } } // Receiving scene data in destination scene public class SingSceneController : MonoBehaviour, INeedInjection { [Inject] private SceneNavigator sceneNavigator; private SingSceneData singSceneData; void Start() { // Get scene data or use default SingSceneData defaultData = CreateDefaultSingSceneData(); singSceneData = sceneNavigator.GetSceneData(defaultData); // Use the data SongMeta currentSong = singSceneData.SongMetas[0]; Debug.Log($"Now playing: {currentSong.Artist} - {currentSong.Title}"); if (singSceneData.IsMedley) { Debug.Log($"Medley song {singSceneData.MedleySongIndex + 1} of {singSceneData.SongMetas.Count}"); } } private SingSceneData CreateDefaultSingSceneData() { return new SingSceneData { SongMetas = new List(), SingScenePlayerData = new SingScenePlayerData() }; } } ``` -------------------------------- ### Theme Configuration Source: https://context7.com/ultrastar-deluxe/play/llms.txt Information on how to configure and customize the UI appearance using theme JSON files. ```APIDOC ## Theme Configuration ### Description Themes are JSON files used to customize the UI appearance, including colors, backgrounds, and audio. Custom themes should be placed in the platform-specific Themes folder. ### Theme File Structure (Example) ```json { "parentTheme": "vinyl", "styleSheets": [ "stylesheets/my-custom-styles.uss" ], "primaryFontColor": "#F0F0F0", "secondaryFontColor": "#C0C0C0", "warningFontColor": "#FEC84B", "errorFontColor": "#F97066", "lyricsColor": "#E1E1E1E5", "nextLyricsColor": "#E1E1E1E5", "currentNoteLyricsColor": "#FF0000", "previousNoteLyricsColor": "#00FF00", "goldenColor": "#FFD700", "lyricsShadow": true, "dynamicBackground": { "videoPath": "videos/background-loop.mp4", "videoPlaybackSpeed": 0.5, "gradientRampFile": "gradients/blue-purple.png", "gradientType": "Radial", "gradientScale": 4.5, "gradientSmoothness": 0.6, "gradientAnimation": true, "particleFile": "particles/stars.png", "particleOpacity": 0.3, "patternFile": "patterns/dots.png", "patternScale": { "x": 2.0, "y": 2.0 }, "patternScrolling": { "x": 0.02, "y": 0.04 } }, "staticBackground": { "imagePath": "backgrounds/my-background.jpg", "imageScaleMode": "ScaleAndCrop" }, "sceneSpecificBackgrounds": { "MainScene": { "staticBackground": { "imagePath": "backgrounds/main-menu.jpg" } } }, "phraseRatingColors": { "perfect": "#00FF00", "great": "#006600", "good": "#FF00FF", "notBad": "#0000FF", "bad": "#FF0000" }, "microphoneColors": ["#FF0000", "#00FF00", "#0000FF", "#FFFF00"], "backgroundMusic": "music/menu-music.mp3", "defaultControl": { "fontColor": "#FFFFFF", "hoverFontColor": "#FFFF00", "backgroundColor": "#333333", "hoverBackgroundColor": "#444444", "backgroundGradient": "45deg, #101828, #475467", "borderColor": "#666666" } } ``` ### Theme File Locations - **Linux:** `~/.config/unity3d/ultrastar/UltraStar Play/Themes` - **macOS:** `~/Library/Application Support/ultrastar/UltraStar Play/Themes` - **Windows:** `C:\Users\USERNAME\AppData\LocalLow\ultrastar\UltraStar Play\Themes` - **Android:** `INTERNAL_STORAGE/Android/data/com.ultrastar.UltraStarPlay/files/Themes` ``` -------------------------------- ### Configure Game Settings in C# Source: https://context7.com/ultrastar-deluxe/play/llms.txt Demonstrates how to access and modify game settings using the SettingsManager and Settings class in C#. This includes graphics, audio, game, and theme configurations, as well as player profiles and song directories. Settings are persisted as JSON. ```csharp using UniInject; using UnityEngine; using System.Collections.Generic; public class SettingsExample : MonoBehaviour, INeedInjection { [Inject] private SettingsManager settingsManager; void Start() { Settings settings = settingsManager.Settings; // Graphics settings settings.FullScreenMode = EFullScreenMode.Windowed; settings.ScreenResolution = new ScreenResolution(1920, 1080, 60); settings.TargetFps = 60; // Audio settings settings.VolumePercent = 80; settings.MusicVolumePercent = 100; settings.MicrophonePlaybackVolumePercent = 50; settings.BackgroundMusicVolumePercent = 30; settings.PreferPortAudio = false; // Game settings settings.CultureInfoName = "en"; // Language settings.Difficulty = EDifficulty.Medium; settings.ScoreMode = EScoreMode.Individual; settings.PitchDetectionAlgorithm = EPitchDetectionAlgorithm.Dywa; // Theme settings settings.ThemeName = "vinyl"; settings.EnableDynamicThemes = true; settings.AnimatedBackground = true; // Player profiles settings.PlayerProfiles = new List { new PlayerProfile { Name = "Player 1", IsEnabled = true }, new PlayerProfile { Name = "Player 2", IsEnabled = true } }; // Song library settings.SongDirs = new List { "/home/user/UltraStar/Songs", "/media/external/Karaoke" }; // Save settings settingsManager.Save(); } } ``` -------------------------------- ### Log Messages with Serilog in Unity Source: https://github.com/ultrastar-deluxe/play/wiki/Logging-(Serilog) Demonstrates how to use Serilog's static methods for different log levels (Verbose, Debug, Information, Warning, Error, Exception) within a Unity MonoBehaviour. It highlights passing lambdas for lazy evaluation of log messages, which is efficient as messages are only constructed if the log level is enabled. ```csharp public class MyLoggingBehaviour : MonoBehaviour { private void Start() { Log.Verbose(() => "Serilog verbose log message"); Log.Debug(() => "Serilog debug log message"); Log.Information(() => "Serilog info log message"); Debug.Log("Unity info log message"); Log.Warning(() => "Serilog warning log message"); Debug.LogWarning("Unity warning log message"); Log.Error(() => "Serilog error log message"); Debug.LogError("Unity error log message"); Log.Exception(() => new Exception("Serilog exception log message")); Debug.LogException(new Exception("Unity exception message")); } } ``` -------------------------------- ### Loading Scene with Data in C# Source: https://github.com/ultrastar-deluxe/play/wiki/Implementation-Details Illustrates how to load a new scene and pass data to it using SceneNavigator. The SceneNavigator stores SceneData objects, which are then retrieved by the control class of the newly loaded scene. ```csharp SongSelectSceneControl.cs: private void OpenSingSceneWithSelectedSong() { SingSceneData singSceneData = ... SceneNavigator.Instance.LoadScene(EScene.SingScene, singSceneData); } ``` ```csharp SingSceneControl.cs: void Start() { // Load scene data from static reference, or use default if none SingSceneData defaultSingSceneData = ... singSceneData = SceneNavigator.Instance.GetSceneData(defaultSingSceneData); } ``` -------------------------------- ### Referencing InputActions with Constants (C#) Source: https://github.com/ultrastar-deluxe/play/wiki/Input-System-(InputActions) Illustrates the recommended way to reference InputActions in code using generated C# constants from the R-class. This approach enhances type safety and simplifies refactoring compared to using raw string paths. ```csharp R.InputActions.songEditor_copy ``` -------------------------------- ### Accessing Input Device State (C#) Source: https://github.com/ultrastar-deluxe/play/wiki/Input-System-(InputActions) Demonstrates static access to the current state of input devices like keyboards and touchscreens using Unity's Input System. This is useful for direct, immediate input checks. ```csharp Keyboard.current.leftCtrlKey.wasPressedThisFrame Touch.activeTouches.Count ``` -------------------------------- ### Dependency Injection with UniInject in C# Source: https://github.com/ultrastar-deluxe/play/wiki/Implementation-Details Shows how to use UniInject for dependency injection, allowing classes to easily access singleton instances like SceneNavigator. Classes implementing INeedInjection can have their dependencies automatically resolved. ```csharp using UniInject; public class MyCoolScript : INeedInjection { [Inject] private SceneNavigator sceneNavigator; void Start() { // Do something with the sceneNavigator instance. } } ``` -------------------------------- ### Singleton Instance Access in C# Source: https://github.com/ultrastar-deluxe/play/wiki/Implementation-Details Demonstrates how to access a singleton instance using a static getter method provided by DontDestroyOnLoadManager. This pattern ensures a single instance of a class is available throughout the application lifecycle. ```csharp public class SceneNavigator { public static SceneNavigator Instance => DontDestroyOnLoadManager.FindComponentOrThrow(); } ``` -------------------------------- ### Configure Static Background Image Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt Defines parameters for a static background image, including its file path and how it should be scaled to fit the screen. Supported scale modes are 'StretchToFill', 'ScaleAndCrop', and 'ScaleToFit'. ```json { "staticBackground": { "imagePath": "backgrounds/open-sign-1836961_1920.jpg", "imageScaleMode": "ScaleAndCrop" } } ``` -------------------------------- ### Build Companion App (Nuke) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Builds the companion application for Android and iOS platforms. This app likely complements the main game experience. ```bash ./build.sh BuildCompanionAppAndroidApk ./build.sh BuildCompanionAppIos ``` -------------------------------- ### Resolving Input Conflicts with Priority (C#) Source: https://github.com/ultrastar-deluxe/play/wiki/Input-System-(InputActions) Demonstrates how to resolve conflicts where the same action is bound to multiple behaviors by assigning priorities. Higher priority actions can cancel further propagation of the event. ```csharp InputManager.GetInputAction(R.InputActions.usplay_back).PerformedAsObservable().Subscribe(_ => ExitScene()); InputManager.GetInputAction(R.InputActions.usplay_back).PerformedAsObservable(10 /* This is the priority */).Subscribe(_ => { CloseDialog(); InputManager.GetInputAction(R.InputActions.usplay_back).CancelNotifyForThisFrame(); }); ``` -------------------------------- ### Adding Custom Input Action Info (C#) Source: https://github.com/ultrastar-deluxe/play/wiki/Input-System-(InputActions) Shows how to manually add information about available InputActions or custom input handling to be displayed to the user. This is useful for providing user guidance on controls. ```csharp InputManager.AdditionalInputActionInfos.Add(new InputActionInfo("Skip To Next Lyrics", "Navigate Right")); ``` -------------------------------- ### Run Tests with Build Script Source: https://context7.com/ultrastar-deluxe/play/llms.txt Executes game tests using the build.sh script. This is crucial for ensuring code quality and stability before deployment. ```bash ./build.sh TestMainGame ./build.sh TestCompanionApp ``` -------------------------------- ### Build System (Nuke) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Information on using the Nuke build tool for cross-platform builds of UltraStar Play. ```APIDOC ## Build System (Nuke) ### Description The project uses the Nuke build tool for cross-platform builds. Run commands from the project root directory. ### Common Commands **Show available targets and help:** ```bash ./build.sh --help ./build.ps1 --help ``` **Restore dependencies (required before first build):** ```bash ./build.sh RestoreMainGameDependencies ./build.sh RestoreCompanionAppDependencies ``` **Build main game for different platforms:** ```bash ./build.sh BuildMainGameWindows64 ./build.sh BuildMainGameLinux64 ./build.sh BuildMainGameMacOS ./build.sh BuildMainGameAndroidApk ./build.sh BuildMainGameIos ``` **Build companion app:** ```bash ./build.sh BuildCompanionAppAndroidApk ./build.sh BuildCompanionAppIos ``` **Specify Unity installation path if not auto-detected:** ```bash ./build.sh BuildMainGameWindows64 \ --unity-executable '/home/user/Unity/Hub/Editor/6000.1.0f1/Editor/Unity' ``` ``` -------------------------------- ### Override Settings via JSON (Command Line) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Allows overriding specific application settings at startup by providing a JSON string directly as a command-line argument. This is useful for temporary or specific runtime adjustments. ```bash "UltraStar Play.exe" --settingsOverwriteJson '{"GraphicSettings":{"useImageAsCursor":false}}' ``` -------------------------------- ### Build Main Game for Platforms (Nuke) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Initiates the build process for the main UltraStar Play game across various platforms including Windows, Linux, macOS, Android, and iOS. ```bash ./build.sh BuildMainGameWindows64 ./build.sh BuildMainGameLinux64 ./build.sh BuildMainGameMacOS ./build.sh BuildMainGameAndroidApk ./build.sh BuildMainGameIos ``` -------------------------------- ### Restore Dependencies (Nuke) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Restores project dependencies required for building the main game or the companion app. This command should be run before the first build or after changes to dependency configurations. ```bash ./build.sh RestoreMainGameDependencies ./build.sh RestoreCompanionAppDependencies ``` -------------------------------- ### Simulate Input Actions (API) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Allows simulation of user input actions like Enter, Escape, or Spacebar. These are POST requests to the input endpoint. ```bash curl -X POST http://localhost:6789/api/rest/input/enter curl -X POST http://localhost:6789/api/rest/input/escape curl -X POST http://localhost:6789/api/rest/input/space ``` -------------------------------- ### Configure Background Music Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt Specifies the path to a custom background music file to be used in the game. ```json { "backgroundMusic": "music/my-background-music.mp3" } ``` -------------------------------- ### Configure Video Preview Color Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt Sets the color for the video preview in the song select menu. This can also be used to make the preview transparent by including an alpha channel. ```json { "videoPreviewColor": "#00FF0022" } ``` -------------------------------- ### Parse UltraStar Song Files with C# Source: https://context7.com/ultrastar-deluxe/play/llms.txt This C# code snippet demonstrates how to use the `UltraStarSongParser` class to load and parse UltraStar txt song files. It shows how to access song metadata, check for parsing issues, and access lazy-loaded voice and note data. The parser can also handle song content provided as a string. ```csharp using System; using UnityEngine; public class SongLoader : MonoBehaviour { public void LoadSong(string filePath) { // Parse with default config UltraStarSongParserResult result = UltraStarSongParser.ParseFile(filePath); // Access song metadata SongMeta songMeta = result.SongMeta; Debug.Log($"Title: {songMeta.Title}"); Debug.Log($"Artist: {songMeta.Artist}"); Debug.Log($"BPM: {songMeta.TxtFileBpm}"); Debug.Log($"Audio: {songMeta.Audio}"); Debug.Log($"Gap: {songMeta.GapInMillis}ms"); // Check for parsing issues foreach (SongIssue issue in result.SongIssues) { Debug.LogWarning($"Song issue: {issue.Message}"); } // Access voices (lazy-loaded) foreach (Voice voice in songMeta.Voices) { string displayName = songMeta.GetVoiceDisplayName(voice.Id); Debug.Log($"Voice: {displayName}, Sentences: {voice.Sentences.Count}"); } // Parse from string instead of file string txtContent = "#TITLE:Test\n#ARTIST:Test\n#BPM:120\n#MP3:test.mp3\n: 0 4 0 Hello"; UltraStarSongParserResult stringResult = UltraStarSongParser.ParseString(txtContent); } } ``` -------------------------------- ### Configure Scene-Specific Backgrounds Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt Allows overriding the default background for specific scenes. Scene names can be found in the UltraStar Play GitHub repository. ```json { "sceneSpecificBackgrounds": { "MainScene": { "staticBackground": { ... }, "dynamicBackground": { ... } } } } ``` -------------------------------- ### Input Simulation API Source: https://context7.com/ultrastar-deluxe/play/llms.txt Endpoints for simulating user input actions, useful for remote control or testing. ```APIDOC ## POST /api/rest/input/enter ### Description Simulates pressing the 'Enter' key. ### Method POST ### Endpoint /api/rest/input/enter ### Parameters None ### Request Example None ### Response #### Success Response (200) (No specific response body defined, typically indicates success) #### Response Example (Empty or success confirmation) ``` ```APIDOC ## POST /api/rest/input/escape ### Description Simulates pressing the 'Escape' key. ### Method POST ### Endpoint /api/rest/input/escape ### Parameters None ### Request Example None ### Response #### Success Response (200) (No specific response body defined, typically indicates success) #### Response Example (Empty or success confirmation) ``` ```APIDOC ## POST /api/rest/input/space ### Description Simulates pressing the 'Space' key. ### Method POST ### Endpoint /api/rest/input/space ### Parameters None ### Request Example None ### Response #### Success Response (200) (No specific response body defined, typically indicates success) #### Response Example (Empty or success confirmation) ``` -------------------------------- ### Scene Navigation with SceneData Source: https://context7.com/ultrastar-deluxe/play/llms.txt Navigate between scenes and pass data using the `SceneNavigator` and `SceneData` classes. Ensure each scene has appropriate default values for its `SceneData`. ```APIDOC ## Scene Navigation with SceneData Navigate between scenes while passing data using `SceneNavigator` and `SceneData` classes. Each scene should have sensible defaults for its SceneData. ### Example Usage ```csharp using System.Collections.Generic; using UniInject; using UnityEngine; public class SongSelectController : MonoBehaviour, INeedInjection { [Inject] private SceneNavigator sceneNavigator; public void StartSinging(SongMeta selectedSong, List players) { // Create scene data with song and player information SingSceneData singSceneData = new SingSceneData { SongMetas = new List { selectedSong }, SingScenePlayerData = new SingScenePlayerData { PlayerProfiles = players }, PositionInMillis = 0, StartPaused = false }; // Navigate to sing scene with data sceneNavigator.LoadScene(EScene.SingScene, singSceneData); } public void StartMedley(List songs) { SingSceneData medleyData = new SingSceneData { SongMetas = songs, MedleySongIndex = 0 // Marks this as a medley }; sceneNavigator.LoadScene(EScene.SingScene, medleyData); } } // Receiving scene data in destination scene public class SingSceneController : MonoBehaviour, INeedInjection { [Inject] private SceneNavigator sceneNavigator; private SingSceneData singSceneData; void Start() { // Get scene data or use default SingSceneData defaultData = CreateDefaultSingSceneData(); singSceneData = sceneNavigator.GetSceneData(defaultData); // Use the data SongMeta currentSong = singSceneData.SongMetas[0]; Debug.Log($"Now playing: {currentSong.Artist} - {currentSong.Title}"); if (singSceneData.IsMedley) { Debug.Log($"Medley song {singSceneData.MedleySongIndex + 1} of {singSceneData.SongMetas.Count}"); } } private SingSceneData CreateDefaultSingSceneData() { return new SingSceneData { SongMetas = new List(), SingScenePlayerData = new SingScenePlayerData() }; } } ``` ``` -------------------------------- ### Common Debug Console Commands Source: https://context7.com/ultrastar-deluxe/play/llms.txt Lists essential commands for interacting with the UltraStar Play debug console. These commands allow users to view logs, check the current scene, reload the scene, display the FPS counter, and access help. ```text # Common debug console commands # Show log file location logs.path # Show current scene name scene.current # Reload current scene scene.reload # Show FPS counter fps.show # List all available commands help ``` -------------------------------- ### Song Queue API Source: https://context7.com/ultrastar-deluxe/play/llms.txt Endpoints for managing the current song queue, including adding and removing songs. ```APIDOC ## GET /api/rest/songQueue ### Description Retrieves the current song queue. ### Method GET ### Endpoint /api/rest/songQueue ### Parameters None ### Request Example None ### Response #### Success Response (200) - **Items** (array) - A list of songs in the queue. - **SongId** (string) - The unique identifier for the song. - **PlayerNames** (array of strings) - The names of the players associated with the song. #### Response Example ```json { "Items": [ { "SongId": "abc123", "PlayerNames": ["Player 1"] } ] } ``` ``` ```APIDOC ## POST /api/rest/songQueue/entry ### Description Adds a song to the current song queue. ### Method POST ### Endpoint /api/rest/songQueue/entry ### Parameters #### Request Body - **SongId** (string) - Required - The unique identifier for the song to add. - **PlayerNames** (array of strings) - Required - The names of the players. ### Request Example ```json { "SongId": "abc123", "PlayerNames": ["Player 1"] } ``` ### Response #### Success Response (200) (No specific response body defined, typically indicates success) #### Response Example (Empty or success confirmation) ``` ```APIDOC ## DELETE /api/rest/songQueue/entry/{index} ### Description Removes a song from the current song queue by its index. ### Method DELETE ### Endpoint /api/rest/songQueue/entry/{index} ### Parameters #### Path Parameters - **index** (integer) - Required - The index of the song to remove from the queue. ### Request Example None ### Response #### Success Response (200) (No specific response body defined, typically indicates success) #### Response Example (Empty or success confirmation) ``` -------------------------------- ### Theme Configuration JSON Structure Source: https://context7.com/ultrastar-deluxe/play/llms.txt Defines the structure for a custom theme JSON file. This file allows customization of UI elements, fonts, colors, backgrounds (static, dynamic, scene-specific), phrase rating colors, microphone colors, background music, and default control styles. ```json { "parentTheme": "vinyl", "styleSheets": [ "stylesheets/my-custom-styles.uss" ], "primaryFontColor": "#F0F0F0", "secondaryFontColor": "#C0C0C0", "warningFontColor": "#FEC84BB", "errorFontColor": "#F97066", "lyricsColor": "#E1E1E1E5", "nextLyricsColor": "#E1E1E1E5", "currentNoteLyricsColor": "#FF0000", "previousNoteLyricsColor": "#00FF00", "goldenColor": "#FFD700", "lyricsShadow": true, "dynamicBackground": { "videoPath": "videos/background-loop.mp4", "videoPlaybackSpeed": 0.5, "gradientRampFile": "gradients/blue-purple.png", "gradientType": "Radial", "gradientScale": 4.5, "gradientSmoothness": 0.6, "gradientAnimation": true, "particleFile": "particles/stars.png", "particleOpacity": 0.3, "patternFile": "patterns/dots.png", "patternScale": { "x": 2.0, "y": 2.0 }, "patternScrolling": { "x": 0.02, "y": 0.04 } }, "staticBackground": { "imagePath": "backgrounds/my-background.jpg", "imageScaleMode": "ScaleAndCrop" }, "sceneSpecificBackgrounds": { "MainScene": { "staticBackground": { "imagePath": "backgrounds/main-menu.jpg" } } }, "phraseRatingColors": { "perfect": "#00FF00", "great": "#006600", "good": "#FF00FF", "notBad": "#0000FF", "bad": "#FF0000" }, "microphoneColors": ["#FF0000", "#00FF00", "#0000FF", "#FFFF00"], "backgroundMusic": "music/menu-music.mp3", "defaultControl": { "fontColor": "#FFFFFF", "hoverFontColor": "#FFFF00", "backgroundColor": "#333333", "hoverBackgroundColor": "#444444", "backgroundGradient": "45deg, #101828, #475467", "borderColor": "#666666" } } ``` -------------------------------- ### Handling Overlapping InputActions (C#) Source: https://github.com/ultrastar-deluxe/play/wiki/Input-System-(InputActions) Explains how to differentiate between actions where one is a subset of another (e.g., Ctrl+F vs. Ctrl+Shift+F). It uses a 'Where' clause to ensure the more specific action is not triggered when the broader one is intended. ```csharp InputManager.GetInputAction(R.InputActions.stuffWithCtrlShiftF).PerformedAsObservable() .Subscribe(_ => DoStuffA()); InputManager.GetInputAction(R.InputActions.stuffWithCtrlF).PerformedAsObservable() // Only react if other InputAction is not triggered as well .Where(InputManager.GetInputAction(R.InputActions.stuffWithCtrlShiftF).InputAction.ReadValue() == 0) .Subscribe(_ => DoStuffB()); ``` -------------------------------- ### Configure UI Shadow Properties Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt Sets the opacity and offset for UI drop shadows. Opacity can be set to 0 to disable shadows. Offset defines the shadow's position. ```json { "uiShadowOpacity": 0.33, "uiShadowOffset": { "x": -16, "y": 10 } } ``` -------------------------------- ### Configure Custom Song Rating Icons Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt Defines paths to custom icons for song rating emojis. If not provided, default icons will be used. Icons are mapped to different rating levels from 'toneDeaf' to 'ultrastar'. ```json { "songRatingIcons": { "toneDeaf": "icons/theme name/rating_0.png", "amateur": "icons/theme name/rating_1.png", "wannabe": "icons/theme name/rating_2.png", "hopeful": "icons/theme name/rating_3.png", "risingStar": "icons/theme name/rating_4.png", "leadSinger": "icons/theme name/rating_5.png", "superstar": "icons/theme name/rating_6.png", "ultrastar": "icons/theme name/rating_7.png" } } ``` -------------------------------- ### Using Translations in C# Code Source: https://github.com/ultrastar-deluxe/play/wiki/Translations,-Internationalization-(I18N) Shows how to retrieve translated strings in C# scripts using the `I18NManager.GetTranslation` method and the generated `R.String` constants. This prevents typos and improves refactoring capabilities. ```csharp using UnityEngine; public class MyCoolScript : MonoBehaviour, INeedInjection { void Start() { string translatedText = I18NManager.GetTranslation(R.String.mainScene_button_hello); Debug.Log(translatedText); } } ``` -------------------------------- ### Manage Favorites Playlist (API) Source: https://context7.com/ultrastar-deluxe/play/llms.txt Provides endpoints for managing the favorites playlist. You can retrieve the list of favorites, add a song by its ID, or remove a song by its ID. ```bash curl http://localhost:6789/api/rest/playlist/favorites curl -X POST http://localhost:6789/api/rest/playlist/favorites/entry/{songId} curl -X DELETE http://localhost:6789/api/rest/playlist/favorites/entry/{songId} ``` -------------------------------- ### Generating C# Translation Constants (R.String) Source: https://github.com/ultrastar-deluxe/play/wiki/Translations,-Internationalization-(I18N) Demonstrates how to generate C# constants for translation keys using the 'R class > Create all C# constants' menu item. This approach, inspired by Android's R class, provides type-safe access to translations and ensures fallback to English. ```csharp public static partial class R { public static class String { public static readonly string mainScene_button_hello = "mainScene_button_hello"; public static readonly string settings_title = "settings_title"; } } ``` -------------------------------- ### Configure Song Editor Layer Colors Source: https://github.com/ultrastar-deluxe/play/blob/master/UltraStar Play/Assets/StreamingAssets/Themes/example_theme.json.txt Sets specific colors for different layers or functionalities within the song editor, aiding in visual organization. ```json { "songEditorLayerColors": { "P1": "#ccbbaa", "P2": "#aabbff", "MicRecording": "#FF0000", "ButtonRecording": "#00FF00", "CopyPaste": "#FF00FF", "Import": "#FFFF00" } } ```