{"id":13662366,"url":"https://github.com/pschraut/UnityCommandLine","last_synced_at":"2025-04-25T10:31:03.129Z","repository":{"id":49649746,"uuid":"270063591","full_name":"pschraut/UnityCommandLine","owner":"pschraut","description":"A command-line parser for Unity 2019.3 and newer in the style of PlayerPrefs. ","archived":false,"fork":false,"pushed_at":"2023-04-16T15:01:03.000Z","size":115,"stargazers_count":56,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-09T11:13:23.285Z","etag":null,"topics":["gamedev","unity","unity3d","unity3d-plugin"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pschraut.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-06-06T18:10:09.000Z","updated_at":"2024-06-16T21:00:43.000Z","dependencies_parsed_at":"2024-04-21T11:45:47.427Z","dependency_job_id":"59a16a56-4466-42c2-b2eb-e5b7aa544122","html_url":"https://github.com/pschraut/UnityCommandLine","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschraut%2FUnityCommandLine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschraut%2FUnityCommandLine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschraut%2FUnityCommandLine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pschraut%2FUnityCommandLine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pschraut","download_url":"https://codeload.github.com/pschraut/UnityCommandLine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223996557,"owners_count":17238327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gamedev","unity","unity3d","unity3d-plugin"],"created_at":"2024-08-02T05:01:56.696Z","updated_at":"2024-11-10T18:30:16.622Z","avatar_url":"https://github.com/pschraut.png","language":"C#","funding_links":[],"categories":["C\\#"],"sub_categories":[],"readme":"# CommandLine for Unity\n\nThe CommandLine for Unity package provides the ability to query key-value pairs, very similar to Unity's [PlayerPrefs](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html) API.\nThe CommandLine options can be stored in a text file, for example:\n```csharp\n-InfiniteHealth true\n//-InfiniteArmor true\n-DamageMultiplier 8.5\n```\nIn order to query if ```-InfiniteHealth``` is set, you use:\n```csharp\nCommandLine.GetBool(\"-InfiniteHealth\", false);\n```\nThe first argument ```-InfiniteHealth``` represents the key. The second argument, in this case ```false```, represents the default value that is returned, \nif the key could not be found in the commandline.\n\nCommandLine supports the following types:\n* ```float```\n* ```int```\n* ```bool```\n* ```enum```\n* ```string``` (use quotes to provide strings with spaces)\n\nCommandLine supports C-like comments in your text file:\n* ```// line comments```\n* ```/* block comments */```\n\n\n# Installation\n\nAs of Unity 2019.3, Unity supports to add packages from git through the Package Manager window. \nIn Unity's Package Manager, choose \"Add package from git URL\" and insert one of the Package URL's you can find below.\n\n## Package URL's\n\n| Version  |     Link      |\n|----------|---------------|\n| 1.2.0 | https://github.com/pschraut/UnityCommandLine.git#1.2.0 |\n| 1.1.0 | https://github.com/pschraut/UnityCommandLine.git#1.1.0 |\n| 1.0.0 | https://github.com/pschraut/UnityCommandLine.git#1.0.0 |\n\n\n# Credits\n\nIf you find this package useful, please mention my name in your credits screen.\nSomething like \"CommandLine by Peter Schraut\" or \"Thanks to Peter Schraut\" would be very much appreciated.\n\n\n# Integration\n\n* Create a text file in your project that is used to provide commandline options. I prefer ```Assets/StreamingAssets/CommandLine.txt```, but you can use any path you like.\n* Load the commandline file using your favorite API during application/game startup.\n* Call ```CommandLine.Init(text)``` with the text of the commandline file.\n* Call ```CommandLine.GetBool(key, defaultValue)``` and friends to query commandline options.\n\nPlease see the video below where I show the integration steps.\n\n[![](http://img.youtube.com/vi/HdA2vDiHHWM/0.jpg)](http://www.youtube.com/watch?v=HdA2vDiHHWM \"\")\n\n# Examples\n\n## How to load from file\nThe simplest way to load a commandline file is to use ```System.IO```, which works on many or perhaps most platforms.\n\nHowever, on Android you can't use ```System.IO``` and you must use ```UnityWebRequest``` instead, which isn't shown in the example below.\n\nOn some systems/consoles that require to mount a device before you can access it, you probably can't use the exact \ncode below as well and need to modify the ```RuntimeInitializeLoadType``` option or call that method in your own application startup \ncode.\n```csharp\n[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)]\nstatic void LoadCommandLine()\n{\n    // Use commandline options passed to the application\n    var text = System.Environment.CommandLine + \"\\n\";\n\n    // Load the commandline file content.\n    // You need to adjust the path to where the file is located in your project.\n    var path = System.IO.Path.Combine(Application.streamingAssetsPath, \"CommandLine.txt\");\n    if (System.IO.File.Exists(path))\n    {\n        text += System.IO.File.ReadAllText(path);\n    }\n    else\n    {\n#if UNITY_EDITOR || DEVELOPMENT_BUILD\n        Debug.LogErrorFormat(\"Could not find commandline file '{0}'.\", path);\n#endif\n    }\n\n    // Initialize the CommandLine\n    Oddworm.Framework.CommandLine.Init(text);\n}\n```\nUsing the [StreamingAssets](https://docs.unity3d.com/Manual/StreamingAssets.html) folder has the benefit that you can modify the commandline file in a build as well.\nYou don't need to create a new build, if you just want to start the game with different commandline options.\n\nI don't provide a built-in method to load the CommandLine, because file loading code is very often project specific.\n\n\n## I don't need a commandline file, I just want the options passed to the application\nOK, in this case it's even simpler:\n```csharp\n[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)]\nstatic void LoadCommandLine()\n{\n    Oddworm.Framework.CommandLine.Init(System.Environment.CommandLine);\n}\n```\nWhile the above code does work in a build perfectly, but in the editor, it only uses the commandline options that were passed to the Unity editor.\n\n\n## How to use it\nOnce the CommandLine has been initialized, see example above, you can query it pretty much the same way\nyou use Unity's [PlayerPrefs](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html).\n\nLet's assume the CommandLine.txt file contains these options:\n```csharp\n-InfiniteHealth true\n//-InfiniteArmor true\n-DamageMultiplier 8.5\n```\nI prefer to write one option per line, but you can also have multiple options on the same line.\n```csharp\n-InfiniteHealth true /*-InfiniteArmor true*/ -DamageMultiplier 8.5\n```\n\nThe C# code to query above options would be:\n```csharp\nusing UnityEngine;\nusing Oddworm.Framework;\n\npublic class CommandLineExample : MonoBehaviour\n{\n    void Start()\n    {\n        var infiniteHealth = CommandLine.GetBool(\"-InfiniteHealth\", false);\n        Debug.LogFormat(\"InfiniteHealth: {0}\", infiniteHealth);\n\n        var infiniteArmor = CommandLine.GetBool(\"-InfiniteArmor\", false);\n        Debug.LogFormat(\"InfiniteArmor: {0}\", infiniteArmor);\n\n        var damageMultiplier = CommandLine.GetFloat(\"-DamageMultiplier\", 1);\n        Debug.LogFormat(\"DamageMultiplier: {0}\", damageMultiplier);\n    }\n}\n```\nThe output of above code is:\n```\nInfiniteHealth: True\nInfiniteArmor: False\nDamageMultiplier: 8.5\n```\n```InfiniteArmor``` is false, because the commandline option was commented out \nvia ```//``` and thus the specified default value ```false``` was used instead.\n\nThe ```-``` symbol infront of each commandline option is just my personal preference, but it could be any other symbol too,\n or you could drop it entirely. The CommandLine code is not bound to any prefix.\nIf you don't like prefixes, just don't use them. If you prefer different symbol(s), you can use them too. \n\n## How to query enum options\nLet's assume the CommandLine.txt file contains these options:\n```csharp\n-Fruit Pineapple\n-Fruits \"Apple, Coconut, Kiwi\"\n```\n\nThe C# code to query above options would be:\n```csharp\nenum Fruit\n{\n    None,\n    Banana,\n    Apple,\n    Coconut,\n    Pineapple,\n    Kiwi\n}\n\nCommandLine.GetEnum\u003cFruit\u003e(\"-Fruit\", Fruit.None);\n\n\n[System.Flags]\nenum Fruits\n{\n    Banana = 1 \u003c\u003c Fruit.Banana,\n    Apple = 1 \u003c\u003c Fruit.Apple,\n    Coconut = 1 \u003c\u003c Fruit.Coconut,\n    Pineapple = 1 \u003c\u003c Fruit.Pineapple,\n    Kiwi = 1 \u003c\u003c Fruit.Kiwi\n}\n\nCommandLine.GetEnum\u003cFruits\u003e(\"-Fruits\", 0);\n```\n\n\n## Disable CommandLine\nYou can turn off CommandLine with:\n```csharp\nCommandLine.isEnabled = false;\n```\nThis will cause:\n* CommandLine.HasKey returns false\n* CommandLine.Get... calls return the default value\n* CommandLine.onInitialize gets still invoked\n\n\n## Strip CommandLine code from release builds\nIf you don't want to support CommandLine in release builds or whatever specific builds you might have, \nyou can add ```ODDWORM_COMMANDLINE_DISABLE``` to the ```Scripting Define Symbols``` found under \n```Edit \u003e Project Settings \u003e Player \u003e Other```.\n\nThis will cause:\n* CommandLine.isEnabled returns false\n* CommandLine.HasKey returns false\n* CommandLine.Get... calls return the default value\n* CommandLine method bodies are stripped\n* CommandLine.onInitialize gets still invoked\n\n## Full example\nThe full example in a single text block can be found below. Copy/paste, save it as ```CommandLineExample.cs``` in your project and you're good to go.\n```csharp\nusing UnityEngine;\nusing Oddworm.Framework;\n\npublic class CommandLineExample : MonoBehaviour\n{\n    void Start()\n    {\n        CommandLine.isEnabled = true;\n\n        var infiniteHealth = CommandLine.GetBool(\"-InfiniteHealth\", false);\n        Debug.LogFormat(\"InfiniteHealth: {0}\", infiniteHealth);\n\n        var infiniteArmor = CommandLine.GetBool(\"-InfiniteArmor\", false);\n        Debug.LogFormat(\"InfiniteArmor: {0}\", infiniteArmor);\n\n        var damageMultiplier = CommandLine.GetFloat(\"-DamageMultiplier\", 1);\n        Debug.LogFormat(\"DamageMultiplier: {0}\", damageMultiplier);\n    }\n\n    // On many platforms you can simply use System.IO to load a file as shown below.\n    // On Android you can't use System.IO though, you need to use UnityWebRequest instead.\n    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)]\n    static void LoadCommandLine()\n    {\n        // Use commandline options passed to the application\n        var text = System.Environment.CommandLine + \"\\n\";\n\n        // Load the commandline file content.\n        // You need to adjust the path to where the file is located in your project.\n        var path = System.IO.Path.Combine(Application.streamingAssetsPath, \"CommandLine.txt\");\n        if (System.IO.File.Exists(path))\n        {\n            text += System.IO.File.ReadAllText(path);\n        }\n        else\n        {\n    #if UNITY_EDITOR || DEVELOPMENT_BUILD\n            Debug.LogErrorFormat(\"Could not find commandline file '{0}'.\", path);\n    #endif\n        }\n\n        // Initialize the CommandLine\n        Oddworm.Framework.CommandLine.Init(text);\n    }\n\n#if UNITY_EDITOR\n    [UnityEditor.MenuItem(\"File/Open Commandline\", priority = 1000)]\n    static void OpenCommandLineMenuItem()\n    {\n        // The CommandLine.txt file location\n        var path = System.IO.Path.Combine(Application.streamingAssetsPath, \"CommandLine.txt\");\n\n        // If the directory does not exist, create it.\n        var directory = System.IO.Path.GetDirectoryName(path);\n        if (!System.IO.Directory.Exists(directory))\n            System.IO.Directory.CreateDirectory(directory);\n\n        // If the CommandLine.txt does not exist, create it.\n        if (!System.IO.File.Exists(path))\n        {\n            System.IO.File.WriteAllText(path, \"Need help? See https://github.com/pschraut/UnityCommandLine\", System.Text.Encoding.UTF8);\n            UnityEditor.AssetDatabase.Refresh();\n        }\n\n        // Open the CommandLine.txt file\n        UnityEditor.EditorUtility.OpenWithDefaultApp(path);\n    }\n#endif\n}\n\n```\n\n\n# Tips\n\n## Menu Item\nCreate a menu item to easily open the commandline text file in your project.\n```csharp\n#if UNITY_EDITOR\n[UnityEditor.MenuItem(\"File/Open Commandline\", priority = 1000)]\nstatic void OpenCommandLineMenuItem()\n{\n    // The CommandLine.txt file location\n    var path = System.IO.Path.Combine(Application.streamingAssetsPath, \"CommandLine.txt\");\n\n    // If the directory does not exist, create it.\n    var directory = System.IO.Path.GetDirectoryName(path);\n    if (!System.IO.Directory.Exists(directory))\n        System.IO.Directory.CreateDirectory(directory);\n\n    // If the CommandLine.txt does not exist, create it.\n    if (!System.IO.File.Exists(path))\n    {\n        System.IO.File.WriteAllText(path, \"Need help? Please see https://github.com/pschraut/UnityCommandLine\", System.Text.Encoding.UTF8);\n        UnityEditor.AssetDatabase.Refresh();\n    }\n\n    // Open the CommandLine.txt file\n    UnityEditor.EditorUtility.OpenWithDefaultApp(path);\n}\n#endif\n```\n\n## PlayMode Inspector\nIf you have my [PlayMode Inspector](https://github.com/pschraut/UnityPlayModeInspector) packages installed, \nyou can also see the internals of CommandLine as shown in the image below. \nFor this open PlayMode Inspector from ```Window \u003e Analysis \u003e PlayMode Inspector``` and use the ```Static...``` drop-down to select\n```CommandLine.PlayModeInspectorMethod```.\n![alt text](Documentation~/images/playmodeinspector.png \"PlayMode Inspector\")\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpschraut%2FUnityCommandLine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpschraut%2FUnityCommandLine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpschraut%2FUnityCommandLine/lists"}