Narrator - The Ink narrative scripting language runtime

[astrochili]

Background

Half a year ago I wanted to make a text adventure game with Defold and I thought, “How will I write the content?”. I found the Ink language very attractive for my task and decided to make a library for integration Ink to Lua and Defold.

Narrator

Narrator is the Ink language parser and runtime implementation in Lua.

Ink is a powerful narrative scripting language. You can find more information about how to write Ink scripts here. There is also Inky editor with useful features to test and debug Ink scripts.

Narrator allows to convert raw Ink scripts to the book (a lua table) and play it as story.

• A book is a passive model on the shelf like a game level.
• A story is a runtime state of the book reading like a game process.

Example

local narrator = require('narrator.narrator')
local book

-- Parse and save a book with io module
book = narrator.parseFile('assets.book', { save = true })

-- Or load and parse the Ink file from the custom resource
local content = sys.load_resource('/assets/book.ink')
book = narrator.parseBook(content)

-- Or parse a book from the string with Ink content
book = narrator.parseBook('Hello world!')

-- Or load a book from the saved lua module
book = require('assets.book')
	
-- Init a story
local story = narrator.initStory(book)

-- Begin the story
story:begin()

while story:canContinue() do
	-- Get current paragraphs to output
	local paragraphs = story:continue()

	-- Output text to the player
	for _, paragraph in ipairs(paragraphs) do
		print(paragraph.text)
	end

	-- If there is no choice, it seems the game is over
	if not story:canChoose() then
		break
	end

	-- Get available choices and output them to the player
	local choices = story:getChoices()
	for i, choice in ipairs(choices) do
		print(i .. ') ' .. choice)
	end

	-- Send an answer to the story to generate new paragraphs
	local answer = 1
	story:choose(answer)
end

Installation

Add links to the zip-archives of the latest versions of narrator and defold-lpeg to your Defold project as dependencies.

https://github.com/astrochili/narrator/archive/master.zip
https://github.com/astrochili/defold-lpeg/archive/master.zip

Documentation

Full documentation and the list of supported Ink features is available in the GitHub repository.

[Pawel]

Awesome work! I was hoping to make support for Ink in my Defork, but I never had enough time for it! Thank you very much for sharing this!

[gianmichele]

AWESOME! Thanks so much for this

[astrochili]

Thank you guys! Any feedback is very welcome.

I plan to make a game with Ink in the next half of a year Or I will try it in the game jam.

Anyway, I have covered the library with a lot of tests, so it should work stably.

[AarrrBee]

@astrochili responding to your question on the other thread
We use Narrator in our game Rare Pets, although the expressiveness of ink was probably overkill for our needs. But it’s good to have it in right from the beginning, we can expand it later.

[astrochili]

Oh, that’s awesome! Could I add a link to the game in the showcase section of README.md as an example of using it in production, albeit for simple needs?

[AarrrBee]

Yes go ahead. And thanks for making the extension.