Ink Scripted Importer #205

SHiLLySiT · 2024-09-02T02:05:12Z

This aims to implement #53, which IMO, has some huge benefits:

There is no longer separate source .INK files and compiled .JSON files that can get out of sync. Which means designers don't need to remember commit both .INK and JSON files, which can happen if they're testing/writing outside Unity with Inky.
No need to deal with managing a ink file compilation queue, and fighting with the Editor. Ink files are compiled when imported, either when added or changed.
You can expose InkFile references instead of generic TextAsset references in game code.
This codebase becomes significantly less complex, and less prone to weird errors that have to deal with compiling assets outside of Unity's normal import process.

This PR is currently in a proof of concept stage: it hasn't been fully tested, but loading and running ink files at runtime and in the Editor is working.

The original implementation was written before Unity supported custom scripted importers, so many of the systems are now obsolete. Since this is a pretty big change, I wanted to open a PR to get an initial review to get some initial thoughts from the maintainers.

Interested in all feedback, but the question at the top of my mind: Do we need to expose includes and master files in the editor? While Ink at a language level still has these concepts, I'm not sure how important it is to expose these in Unity if its no longer important for compilation?

…custom importer

tomkail · 2024-09-02T08:37:35Z

Oh wow thanks for looking into this! I'll take a look this week if I find time. At a glance it looks lovely (so much less code!!)
I've pinged the Unity dev community on Discord (https://discord.gg/inkle) to take a look too, since this is a big change and I'd like as many devs as possible to confirm that it doesn't affect them negatively in any way.

SHiLLySiT · 2024-09-02T14:10:39Z

Totally! I see your message in #ink-unity-integration-dev. I'll keep watch for questions/comments there too. Thanks!

…ince ink files aren't constucted at runtime anymore

SHiLLySiT · 2024-10-06T23:48:42Z

@tomkail Okay I'm moving this out of draft as I've cleaned up the known things I needed to do, but I suspect there may be things I've missed since this was such a huge change. Feel free to tag me on any changes you want after doing a review. I'll loop back when I have the time 🤘

tomkail · 2024-10-07T06:28:03Z

Amazing! Annoyingly nobody has checked this out. How about we stick it on a beta branch and publish it there? Maybe that’ll encourage people.

…

On Mon, Oct 7, 2024 at 00:49 Alex Larioza ***@***.***> wrote: @tomkail <https://github.com/tomkail> Okay I'm moving this out of draft as I've cleaned up the known things I needed to do, but I suspect there may be things I've missed since this was such a huge change. Feel free to tag me on any changes you want after doing a review. I'll loop back when I have the time 🤘 — Reply to this email directly, view it on GitHub <#205 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJR3UED36NFMMKTA7MLXJDZ2HD67AVCNFSM6AAAAABNPMJ5EWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOJVGY2TKOJTGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

SHiLLySiT · 2024-10-08T00:18:51Z

Sounds good to me! I'd rather give more people more time to test it out before its merged into main 😅

I don't appear to have the option to change the base branch to a new (non-existing) branch tho. If you make a beta branch I can update the PR!

SHiLLySiT · 2024-10-10T15:39:05Z

I forgot to update the docs, so I snuck another commit in 👍

ErnSur · 2024-11-09T14:38:25Z

Packages/Ink/Editor/Tools/File Icons/InkBrowserIcons.cs

-				DefaultAsset asset = AssetDatabase.LoadAssetAtPath<DefaultAsset>(path);
-				DrawInkFile(InkLibrary.GetInkFileWithFile(asset), rect);
+				InkFile asset = AssetDatabase.LoadAssetAtPath<InkFile>(path);
+				DrawInkFile(asset, rect);


InkFile is now a Scriptable Object.
No OnDrawProjectWindowItem would be needed if we assign a custom icon to InkFile.cs from the inspector

ErnSur · 2024-11-09T14:42:23Z

Packages/Ink/Editor/Core/Ink Library/InkFile.cs

-
-
-
+	public class InkFile : ScriptableObject {


I'm not familiar with the way the project is maintained but this is a breaking change so it would be nice to bump the major version in the package manifest.

{ "name": "com.inkle.ink-unity-integration", "version": "2.0.0", ... }

ErnSur

I left some general comments, moving to scripted importers is a natural step forward for the library but it looks like it will require breaking changes.
This could be a chance for some cleanups and other breaking changes around the codebase.
Let me know if you want more feedback, I'm interested in closer collaboration.

ErnSur · 2024-11-09T14:48:49Z

Packages/Ink/Editor/Core/InkImporter.cs

+/// Automatically compiles .ink assets each time they are imported, and creates an InkFile asset.
+/// </summary>
+[ScriptedImporter(1, "ink")]
+public class InkImporter : ScriptedImporter


missing namespace: Ink.UnityIntegration

ErnSur · 2024-11-09T14:52:11Z

Packages/Ink/Editor/Core/InkImporter.cs

+        var compiler = new Compiler(inputString, new Compiler.Options
+        {
+            countAllVisits = true,
+            fileHandler = new UnityInkFileHandler(Path.GetDirectoryName(absolutePath)),
+            errorHandler = (string message, ErrorType type) => {
+                InkCompilerLog log;
+                if(InkCompilerLog.TryParse(message, out log)) {
+                    if(string.IsNullOrEmpty(log.relativeFilePath)) log.relativeFilePath = Path.GetFileName(absolutePath);
+                    switch (log.type)
+                    {
+                        case ErrorType.Error: 
+                            inkFile.errors.Add(log); 
+                            Debug.LogError("Ink "+log.type+" for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+":"+log.lineNumber+")", inkFile);
+                            break;
+                        case ErrorType.Warning: 
+                            inkFile.warnings.Add(log); 
+                            Debug.LogWarning("Ink "+log.type+" for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+" "+log.lineNumber+")", inkFile);
+                            break;
+                        case ErrorType.Author: 
+                            inkFile.todos.Add(log);
+                            if (InkSettings.instance.printInkLogsInConsoleOnCompile)
+                            {
+                                Debug.Log("Ink Log for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+" "+log.lineNumber+")", inkFile);
+                            }
+                            break;
+                    }
+
+                } else {
+                    Debug.LogWarning("Couldn't parse log "+message);
+                }
+            }
+        });


Could be extracted to a new method for readability, same with errorHandler inside it

Suggested change

var compiler = new Compiler(inputString, new Compiler.Options

{

countAllVisits = true,

fileHandler = new UnityInkFileHandler(Path.GetDirectoryName(absolutePath)),

errorHandler = (string message, ErrorType type) => {

InkCompilerLog log;

if(InkCompilerLog.TryParse(message, out log)) {

if(string.IsNullOrEmpty(log.relativeFilePath)) log.relativeFilePath = Path.GetFileName(absolutePath);

switch (log.type)

{

case ErrorType.Error:

inkFile.errors.Add(log);

Debug.LogError("Ink "+log.type+" for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+":"+log.lineNumber+")", inkFile);

break;

case ErrorType.Warning:

inkFile.warnings.Add(log);

Debug.LogWarning("Ink "+log.type+" for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+" "+log.lineNumber+")", inkFile);

break;

case ErrorType.Author:

inkFile.todos.Add(log);

if (InkSettings.instance.printInkLogsInConsoleOnCompile)

{

Debug.Log("Ink Log for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+" "+log.lineNumber+")", inkFile);

}

break;

}

} else {

Debug.LogWarning("Couldn't parse log "+message);

}

}

});

var compiler = CreateCompiler(inputString, absolutePath, inkFile);

ErnSur · 2024-11-09T15:04:08Z

Packages/Ink/Editor/Core/InkImporter.cs

+                            Debug.LogError("Ink "+log.type+" for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+":"+log.lineNumber+")", inkFile);
+                            break;
+                        case ErrorType.Warning: 
+                            inkFile.warnings.Add(log); 
+                            Debug.LogWarning("Ink "+log.type+" for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+" "+log.lineNumber+")", inkFile);
+                            break;
+                        case ErrorType.Author: 
+                            inkFile.todos.Add(log);
+                            if (InkSettings.instance.printInkLogsInConsoleOnCompile)
+                            {
+                                Debug.Log("Ink Log for "+Path.GetFileName(absolutePath)+": "+log.content + " (at "+log.relativeFilePath+" "+log.lineNumber+")", inkFile);
+                            }
+                            break;
+                    }
+
+                } else {
+                    Debug.LogWarning("Couldn't parse log "+message);


For The AssetImportContext.LogImportError() could be used for handling all of the importer errors.
Unity handles UI for displaying errors logged this way in the importer header. This in turn could eliminate the need for custom error UI in the Ink File Editor

ErnSur · 2024-11-09T20:10:28Z

Packages/Ink/Editor/Core/Ink Settings/InkSettings.cs

@@ -68,17 +68,6 @@ public string templateFilePath {
 				else return AssetDatabase.GetAssetPath(templateFile);


the templateFile should probably change type to the ScriptableObject imported by the InkImporter

ErnSur · 2024-11-09T20:12:02Z

Packages/Ink/Editor/Core/Ink Library/InkFile.cs

+		public static System.Version inkVersionCurrent = new System.Version(1,2,0);
+		public static System.Version unityIntegrationVersionCurrent = new System.Version(1,2,1);


It would be best to put it somewhere else

ErnSur · 2024-11-09T20:15:16Z

Packages/Ink/Editor/Core/Ink Library/InkFile.cs

-	// Helper class for ink files that maintains INCLUDE connections between ink files
+	/// <summary>
+    /// ScriptableObject that serves as the imported version of .ink files.
+    /// </summary>
 	[Serializable]


Serializable is redundant on a scriptable object

ErnSur · 2024-11-09T20:23:11Z

Packages/Ink/Editor/Core/Ink Library/InkFile.cs

Looks like the static nested class InkIncludeParser is still inside the type but its not used (could be removed).

ErnSur · 2024-11-09T20:24:12Z

Packages/Ink/Editor/Core/InkImporter.cs

+[ScriptedImporter(1, "ink")]
+public class InkImporter : ScriptedImporter
+{
+    public override void OnImportAsset(AssetImportContext ctx)


If compiling output of one ink file depends on another ink file then the AssetImportContext.DependsOnSourceAsset should be used for proper importer behavior.

ErnSur · 2024-11-09T20:30:46Z

Packages/Ink/Editor/Core/InkImporter.cs

+/// Automatically compiles .ink assets each time they are imported, and creates an InkFile asset.
+/// </summary>
+[ScriptedImporter(1, "ink")]
+public class InkImporter : ScriptedImporter


A complimentary InkImporterEditor : ScriptedImporterEditor could be created for better UX.

ErnSur · 2024-11-09T20:40:20Z

Packages/Ink/Editor/Tools/Ink Inspector/InkInspector.cs

I would suggest writing new UI code with UI Toolkit.
it's impossible given that the package manifest says unity 2018 is still supported.
That's a separate topic, but maybe a poll on discord could be useful to see if users really need a support for very old editor versions.
IMO bumping minimal version to 2021.3+ would be a sensible decision.

SHiLLySiT added 12 commits September 1, 2024 15:55

move version vars to ink file

e11d4e2

first pass on pruning compiler system that will become obsolete with …

18c0d21

…custom importer

added ink scripted importer, changed inkfile into a scriptable object

c4fc4fc

updated ink player to play InkFiles directly

aaa4b87

remove now obsolete JSON files from demo

65e81b8

updated demo script to use InkFile directly

3665b32

added additional ink files for testing includes

53e3dd6

updated demo scene

f14e5d9

fixed ink file inspector

43f111d

fixed ink compiler errors not being show in inspector or console

d10d988

addressing remaining FIXMEs

69b8a41

removed master and include files

794c17b

SHiLLySiT marked this pull request as draft September 2, 2024 02:12

SHiLLySiT added 8 commits October 6, 2024 15:30

fixed ink file inspector always disabled

0204945

log story validation exceptions to console for easier debugging

56d6041

removed code that allowed playing a JSON string without an ink file s…

38b73a4

…ince ink files aren't constucted at runtime anymore

switched demo scene back to default ink story

bb45d14

cleaner intialization for storyJson

85d9a70

removed now obsolete settings from settings asset

4b8c16e

restored old log message format

64c4cf6

reimplemented the printInkLogsInConsoleOnCompile flag in ink settings

73fe62a

SHiLLySiT marked this pull request as ready for review October 6, 2024 23:45

updated docs + comments

4073f34

ErnSur reviewed Nov 9, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Ink Scripted Importer #205

Ink Scripted Importer #205

SHiLLySiT commented Sep 2, 2024

tomkail commented Sep 2, 2024

SHiLLySiT commented Sep 2, 2024

SHiLLySiT commented Oct 6, 2024

tomkail commented Oct 7, 2024 via email

SHiLLySiT commented Oct 8, 2024 •

edited

Loading

SHiLLySiT commented Oct 10, 2024

ErnSur Nov 9, 2024 •

edited

Loading

ErnSur Nov 9, 2024 •

edited

Loading

ErnSur left a comment •

edited

Loading

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

ErnSur Nov 9, 2024

		@@ -68,17 +68,6 @@ public string templateFilePath {
		else return AssetDatabase.GetAssetPath(templateFile);

		public static System.Version inkVersionCurrent = new System.Version(1,2,0);
		public static System.Version unityIntegrationVersionCurrent = new System.Version(1,2,1);

Ink Scripted Importer #205

Are you sure you want to change the base?

Ink Scripted Importer #205

Conversation

SHiLLySiT commented Sep 2, 2024

tomkail commented Sep 2, 2024

SHiLLySiT commented Sep 2, 2024

SHiLLySiT commented Oct 6, 2024

tomkail commented Oct 7, 2024 via email

SHiLLySiT commented Oct 8, 2024 • edited Loading

SHiLLySiT commented Oct 10, 2024

ErnSur Nov 9, 2024 • edited Loading

Choose a reason for hiding this comment

ErnSur Nov 9, 2024 • edited Loading

Choose a reason for hiding this comment

ErnSur left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SHiLLySiT commented Oct 8, 2024 •

edited

Loading

ErnSur Nov 9, 2024 •

edited

Loading

ErnSur Nov 9, 2024 •

edited

Loading

ErnSur left a comment •

edited

Loading