Create a "Help" dialog where main functions are described, specially shortcut keys

[daviddq]

Reading through the code I've found a lot of hidden and unexpected functionality. That functionality should be described on a document, specially the shortcuts, preferably within the tool so you can check them by holding F1.

Regarding the keys shortcuts, some of them are counterintuitive since they do not conform to standards. When elaborating such a document, try to identify non standard shortcuts and replace them by standard ones.

[blurymind]

I think it would be nice if you reuse the logic to do a settings dialogue to also do a keyboard shortcuts hints one

[blurymind]

It would be nice if the help also explains the yarn syntax or links to a document that does

[daviddq]

Good idea. Maybe that dialog can have multiple pages with different information.

[blurymind]

yeah, like tabs of sort :)

Keyboard shortcuts, Yarn syntax, etc?

Btw I wrote a short introduction to the syntax for gdevelop users a while ago:
http://wiki.compilgames.net/doku.php/gdevelop5/all-features/dialogue-tree

yarnspinner also has some documentation on it

[blurymind]

trello ticket added here
https://trello.com/c/nDKaG9uR/16-add-a-help-dialog

[daviddq]

@blurymind Please, could you elaborate a summary of the Yarn's syntax so I can add it to the help dialog?

[desplesda]

A complete description of Yarn syntax is available here: https://yarnspinner.dev/docs/syntax

[daviddq]

Thanks a lot, @desplesda. Unfortunately that's too much info for a little help dialog. What I think it would fit perfectly is some kind of syntax cheat sheet, as a quick reference. Does it make sense?

And, of course, there would be a link to the official online help.

[blurymind]

There is an important caveat here. Yarn is using bondagejs to preview stories and some of the yarnSpinner syntax documented there is probably not supported yet.

For example,I believe we cant yet do
You have {$gold} gold pieces.
in bondage and there for in yarn when we preview stories.

I opened a ticket here
hylyh/bondage.js#59
might look into implementing it if nobody else picks it up for a while

I would love to have a discussion opened at the bondagejs tracker about new yarnspinner features that are not yet supported. @desplesda can you leave a comment there if you notice anything else that was recently added to the yarn syntax spec

[daviddq]

Shortcuts seem not to be supported either:

Where do you want to go:
->north
->south
->east
->west

[desplesda]

The two main things that were recently added to the Yarn language in Yarn Spinner v1.1 are in-line expressions ( You have {$gold} gold pieces) and format functions (I have [plural {$apple_count} one="an apple" other="% apples"]). Everything else is basically the same since bondage.js started development.

[desplesda]

I'll write a short cheat-sheet summary of Yarn syntax. Roughly how much space is available to show it in?

[blurymind]

Shortcuts seem not to be supported either:

Where do you want to go:
->north
->south
->east
->west

Bondagejs supports that, but it has a bug where if you dont indent the text it will see it as a syntax error. See hylyh/bondage.js#31

Both things will need to be addressed in bondagejs. The parser code is a bit tricky for me, but I have gotten to know it a bit better over the years. Not sure if I can fix those things by myself

In any case I am raising these points now due to bugs gdevelop users have submitted to us at its tracker. They read yarn spinner's documentation and then find out bondagejs has a few gotchas that havent been ironed out yet and report them as gdevelop bugs without knowing anything about bondage or yarnspinner.

If we could run yarnSpinner in js applications that would let me swap out bondagejs with it, but my understanding is that it is currently limited to unity.
It would be amazing if yarn editor used yarn spinner instead of bondagejs. It seems better supported

[daviddq]

I'll write a short cheat-sheet summary of Yarn syntax. Roughly how much space is available to show it in?

That's very dependent on platform, resolution...

This is so far the layout for fullscreen desktop.

[daviddq]

I'll write a short cheat-sheet summary of Yarn syntax.

Any news on this, @desplesda ?

[desplesda]

Expect this in the next day or two!

[blurymind]

@desplesda @hylyh @daviddq

we/bondagejs uses
«if $myYarnVariable == aValue»
yarspinner uses
«if $myYarnVariable is aValue»
https://yarnspinner.dev/docs/writing/controlling/#if-statements-and-options

any reason bondagejs and yarnspinner do this differently?

Btw I kept getting reports about stuff people try from yarnspinner's doc on bondagejs in gdevelop - not working. So I removed the link to yarnSpinner's doc from
http://wiki.compilgames.net/doku.php/gdevelop5/all-features/dialogue-tree

[desplesda]

Both of these expressions are equivalent in Yarn Spinner. is is a synonym for ==. I believe this is the case in bondage.js as well.

[blurymind]

I think the
«if $myYarnVariable is aValue»
syntax will not work in bondagejs and therefor in yarnEditor's playtesting, but correct me if I'm wrong :)

[daviddq]

Both (all) Yarn parser implementations should stick to the same grammar. Otherwise products will start to diverge, they won't fix it (to keep supporting their respective existing user base) and it will soon become a mess.

[desplesda]

Absolutely agreed. (I'm starting to put together plans for an updated Yarn Spinner javascript runtime based on the grammar spec that the C# parser is generated from now, for this very reason.)

[desplesda]

To @blurymind's point: My preference is that == is the main way to express equivalences in the language; is and eq as a synonym for == is only permitted for historical reasons.

[blurymind]

@desplesda does yarnSpinner have a javascript runtime that can be used in place of bondagejs? :)

Right now all this stuff has to be implemented on both, which is kind of a pain in the neck.
Bondagejs is behind in features and syntax flexibility

[desplesda]

Not yet. But I want there to be one.

[blurymind]

Until then we are limited to fixing these in bondagejs if we want to have them supported properly
https://github.com/hylyh/bondage.js

before being able to add them to the help in yarn editor, let's stick to what bondagejs can do and not list stuff that is not supported yet

If yarnSpinner is written in C# is there no way to transpile it into javascript somehow? I suppose its not simple to do :)

[desplesda]

The Yarn Spinner grammar is written in ANTLR, which assists in ports to other languages. Something I've been playing with is using Mono's WASM support to provide a temporary bridge that runs the existing C# compiler toolchain in JS.

[blurymind]

Do we have an online example somewhere? If it becomes possible to run it in JS, we will be able to replace bondagejs with it and support all the stuff that doesnt work atm - both in yarn editor and in gdevelop

[desplesda]

Not yet, but I'm pleased to hear there's interest! Once I have something running, I'll put together a repo hosted under this org. (My time is currently a bit divided between Yarn Spinner, Night in the Woods, and admin stuff, but I'm trying to put as much attention on this as I can, since it's an increasingly important need.)

[desplesda]

Ok, I wrote up a cheat-sheet style summary of the language. The whole thing is valid Yarn syntax.

Lines of dialogue are just text. One line of dialogue per one line of text. 
Like this one.

You can add a line ID to the end of a line, to uniquely identify it! #line:a1b2c3

You can add options. These wait until the end of the node before they appear.

// If selected, the node West will run
[[Would you like to go west?|West]] 

// If selected, the node East will run
[[Would you like to go east?|East]]

You can store information in variables:
<<set $knows_variables = true>>

You can then use this information in your scripts:
<<if $knows_variables == true>>
    Nice! 'elseif' can be used here, too!
<<else>>
    Dang!
<<endif>>

You can use custom commands in your scripts, to tell your game what to do. It's up to your game to define them.
<<walk_to Mae car>>
<<fade_down>>

You can do maths with variables and values:
<<if 1 + 2 / 4 * 3 % 2>>
    You can store true/false, text, and numbers inside variables:
    <<set $character_name = "Bob">>
    <<set $gold_coints = 51>>
    <<set $yarn_is_cool = true>>
<<endif>>

-> Shortcut options let you offer choices in the middle of dialogue.
    Indent the line after it, and it will only run if the user chose the option.
    Shortcut options are presented right away, like lines.
    -> You can put other options inside them, too!
        Wow!
-> You can add a condition to the end of a shortcut option. <<if $yarn_is_cool == false>> // will never run

You can jump straight to a node:
[[GameOver]]

You can embed expressions in lines, {$character_name}.

You can pluralise [plural {$num_words} one="a word" other="words"], depending on your locale.

[daviddq]

@desplesda Awesome! Thanks a lot. Do you mind if I rephrase some sentences to adapt them to the format? (only if really needed, I still don't know).

[blurymind]

Can you also for my sake try playtesting in the yarn editor everything that is in the helpme :)

[blurymind]

Remember people will raise bugs if they find that some syntax in the helpme doesn't work when they playtest it. Bondagejs can't pluralize or do any of the new yarn spinner things

[daviddq]

Although I see your point, as a user the purpose of writing stories in Yarn Editor is running them on my game, not to play test them. Therefore, I want to make use of all the features that Yarn language provides. There's no point on having a "play test" that can't "play test" all the features.

Proposals:

1. improve bondage.js (long term)
2. replace bondage.js. Can we integrate an external fully compatible runner? (mid term)
3. warn in the help dialog which features can be play tested and which can't (short term)
4. completely remove the features from the help dialog (short term)

[blurymind]

Yarn editor bundled in gdevelop should not have in it's helpme syntax features that will not run in gdevelop. If we want those, someone should add them to bondagejs first. Or maybe the help me should have a hint for those that they only work in unity and none of the other game engines.

My suggestion is to only mention in the helpme features that work in bondagejs for now. And later one when they become available in playtesting, add them to the helpme

[blurymind]

Since we use bondagejs inside yarn itself, to fix some play testing bugs in yarn editor, we have to now fix them in bondagejs.

You can have a look at the source code if you are curious.
https://github.com/hylyh/bondage.js
@hylyh usually responds to PRs fairly quickly - same week even from my experience :)

Check out runner.js and results.js, then have a look at the actual parsing part, which happens inside the lexer/parser folders. All of that stuff is manually declared. I feel that if we could share a declaration file or something like that between yarnSpinner and bondagejs - we would have a much more consistent support.

[daviddq]

Yarn editor bundled in gdevelop...

That sounds like there should be a GDevelop branch of the editor. For now let's remove the offending help paragraphs. Please, could you enumerate which features do I have to remove ?

[blurymind]

Yarn editor bundled in gdevelop...

That sounds like there should be a GDevelop branch of the editor. For now let's remove the offending help paragraphs. Please, could you enumerate which features do I have to remove ?

its using the vanilla version of yarn, which supports the same syntax. I am absolutely against creating forks for every instance of yarnEditor getting bundled somewhere.Instead the master version should be made easy to bundle in various other web apps. Lets avoid creating any forks please!

Regardless of that, the story previewer in yarnEditor will fail always when you pass it syntax that is not supported by bondagejs. My advice is not to include such syntax in the helpme, as it would make yarnEditor look broken when playtesting. You are basically telling our users how to crash yarnEditor in its own helpme, knowingly that the unsupported syntax would do that or not work.

Such syntax in the example we got is

 You can jump straight to a node:
[[GameOver]]

You can embed expressions in lines, {$character_name}.
You can pluralise [plural {$num_words} one="a word" other="words"], depending on your locale.

I think[[GameOver]]would work if it has a title on the left
[[game over|GameOver]]

Again,test it by playtesting it in yarnEditor! The {$character_name} syntax will probably not even get properly colour coded in yarnEditor. Thats completely missing atm.

You can include a link to yarnSpinner's documentation in the help me, but please note next to it that some syntax works only in Unity atm. Our documentation should be upfront about what features are supported, until we make those available for all platforms.

Lets make yarnEditor game engine agnostic, but at least consistent with itself.