diff --git a/Docs/about/images/B03899_MockupCover_Cookbook.jpg b/Docs/about/images/B03899_MockupCover_Cookbook.jpg new file mode 100644 index 00000000..500c6eac Binary files /dev/null and b/Docs/about/images/B03899_MockupCover_Cookbook.jpg differ diff --git a/Docs/about/images/community.jpeg b/Docs/about/images/community.jpeg new file mode 100644 index 00000000..bfe9c0f9 Binary files /dev/null and b/Docs/about/images/community.jpeg differ diff --git a/Docs/about/images/fungus-town.png b/Docs/about/images/fungus-town.png new file mode 100644 index 00000000..c0d96c6a Binary files /dev/null and b/Docs/about/images/fungus-town.png differ diff --git a/Docs/about/index.md b/Docs/about/index.md new file mode 100644 index 00000000..4c959e74 --- /dev/null +++ b/Docs/about/index.md @@ -0,0 +1,108 @@ +# About Fungus {#about} + +
+ + +## What is Fungus? + + + +Follow @gofungus + +
+ + + +## Who's it for? +Fungus is popular with writers, illustrators, animators and game designers, especially visual novel & interactive fiction authors. Many people using Fungus are creating games in Unity for the very first time. It is a popular choice for game jams and game design courses. +
 
+ +## Free & Open Source + +We believe that interactive storytelling should be accessible to everyone, so Fungus is 100% free & open source. It works great with both the free and pro versions of Unity 3D. Fungus is inspired by other great open source storytelling tools like [Twine], [Ren'Py] and [Scratch]. + +
 
+ + + +## Community + +The Fungus community is very welcoming and helpful to newcomers. Many people using Fungus have never used Unity or even made a game before, so feel free to ask questions on our [community forum]. Helping other people with their questions is a fantastic and very welcome way to contribute back to the community. + +
 
+ +## Features + +
+ +
+ +Fungus allows you to easily add storytelling features to your Unity games with no coding, via an intuitive visual scripting system. + +- Suitable for making visual novels, RPGs, hidden object, puzzle and interactive fiction games. +- Flowchart-based character dialogue +- Internationalization of your character dialogue. +- Easy control of sprites, camera and audio to help tell your story +- Works for both 2D and 3D Unity games +- Integrates easily with other Unity code and simple to extend. +- Powerful Lua scripting support for more experienced users +- 100% free and open source + +## Contribute + +We welcome all sorts of contributions to Fungus. You can report bugs, suggest new features, contribute source code, write an article, help answer questions on the forums or even just tell your friends about the project! + +- Issue Tracker: [GitHub issue tracker] +- Source Code: [GitHub code repository] + +## Credits + +[Chris Gregan] is the main author and maintainer of Fungus. He's co-founder of [Snozbot], along with [John O' Kane] and [Ronan Pearce]. + + +[Dr. Matt Smith] has kindly contributed the written documentation for the Fungus project. If you're new to Unity development then a great source of information, ideas and sample projects is his [Unity 5.x Cookbook], by Matt and [Chico Queiroz]. + +[Paul Mc Grath] is Animator / Designer / Film-maker at Whackala. He contributed the [tutorial videos] for this site as well as creating the [Fungus Training Course]. + +Special thanks also to [Vicky Lee] and [Coding Grace] who have helped us to organise loads of Fungus workshops, + +Fungus wouldn't be possible without all the awesome people in our community who have contributed to the project and supported us in myriad ways. Thank you all! + +## License + +The Fungus software is licensed under the [Open Source MIT License]. +
+The Fungus documentation is licensed under the [Creative Commons Attribution-NonCommercial License]. + +[Snozbot]: http://snozbot.com +[Chris Gregan]: http://twitter.com/gofungus +[John O' Kane]: https://twitter.com/johnokane +[Ronan Pearce]: https://twitter.com/ronanpearce +[Vicky Lee]: https://twitter.com/whykay +[Paul Mc Grath]: http://whackala.com +[Coding Grace]: https://www.codinggrace.com +[tutorial videos]: ../tutorial_videos/index.md +[Fungus Training Course]: ../training_course/index.md +[FungusGames.com]: http://www.fungusgames.com +[community forum]: http://fungusgames.com/forum +[Twine]: http://twinery.org +[Ren'Py]: https://www.renpy.org +[Scratch]: https://scratch.mit.edu +[GitHub issue tracker]: https://github.com/snozbot/fungus/issues +[GitHub code repository]: https://github.com/snozbot/fungus +[chris@snozbot.com]: chris@snozbot.com +[Dr. Matt Smith]: https://github.com/dr-matt-smith/ +[Creative Commons Attribution-NonCommercial License]: https://creativecommons.org/licenses/by-nc/3.0/ +[Open Source MIT License]: https://github.com/snozbot/fungus/blob/master/LICENSE +[Unity 5.x Cookbook]: https://www.packtpub.com/game-development/unity-5x-cookbook +[ITB]: http://www.itb.ie/ +[matt book cover image]: ./images/B03899_MockupCover_Cookbook.jpg +[Chico Queiroz]: https://www.linkedin.com/in/chicoqueiroz diff --git a/Docs/advanced/narrative_parser_tokens.md b/Docs/advanced/narrative_parser_tokens.md new file mode 100644 index 00000000..34067e64 --- /dev/null +++ b/Docs/advanced/narrative_parser_tokens.md @@ -0,0 +1,34 @@ +# Narrative Parser Tags + +The following tokens can be used within Story Text to do things such as change the styling of text or clear the contents of a dialog area on input and much more. + +* {b} Bold Text {/b} +* {i} Italic Text {/i} +* {color=red} Color Text (color){/color} +* {size=30} Text size {/size} +* {s}, {s=60} Writing speed (chars per sec){/s} +* {w}, {w=0.5} Wait (seconds) +* {wi} Wait for input +* {wc} Wait for input and clear +* {wp}, {wp=0.5} Wait on punctuation (seconds){/wp} +* {c} Clear +* {x} Exit, advance to the next command without waiting for input +* {vpunch=10,0.5} Vertically punch screen (intensity,time) +* {hpunch=10,0.5} Horizontally punch screen (intensity,time) +* {punch=10,0.5} Punch screen (intensity,time) +* {flash=0.5} Flash screen (duration) +* {audio=AudioObjectName} Play Audio Once +* {audioloop=AudioObjectName} Play Audio Loop +* {audiopause=AudioObjectName} Pause Audio +* {audiostop=AudioObjectName} Stop Audio +* {m=MessageName} Broadcast message +* {$VarName} Substitute variable + +Examples: + +``` +This is a line of dialog. +{wc} +This is another line of dialog with some {b}bold{/b} styling. +This is another line of dialog with some {color=blue}blue{/b} text. +``` diff --git a/Docs/articles/index.md b/Docs/articles/index.md new file mode 100644 index 00000000..ddadf941 --- /dev/null +++ b/Docs/articles/index.md @@ -0,0 +1,42 @@ +# Community Articles {#articles} + +If you've created an article or video about Fungus let us know on the forum and we'll add it here. + +## Morning Fun Games + +- [Custom Dialog Like A Comic](https://www.youtube.com/watch?v=RdCAjpQ3iGE) + +## Sercan Altun + +- [Input Dialog & Writing Custom Commands](http://sercanaltun.com/blog/fungus-game-input-dialog-writing-custom-commands) +- [Loading Characters Dynamically](http://sercanaltun.com/blog/fungus-game-loading-characters-dynamically) + +## David Arcila + +- [Game Development Resources](https://game-development.zeef.com/david.arcila?utm_source=Facebook&utm_medium=Post&utm_content=game-development&utm_campaign=Rob#block_60669) + +## David Sherlock + +[http://davidsherlock.co.uk](http://davidsherlock.co.uk) + +- [Creating Revision Apps as Text Adventures](http://davidsherlock.co.uk/creating-revision-apps-as-text-adventures/) +- [More attempts to create revision apps using free resources](http://davidsherlock.co.uk/more-attempts-to-create-revision-apps-using-free-resources) +- [Creating your own hidden object game](http://davidsherlock.co.uk/starting-your-own-hidden-object-game) +- [Setting up Unity and Fungus to make #appliedgames](https://youtu.be/t1zf4Qq_GS8) + +## Leah Lee + +[http://leahlee.studio](http://leahlee.studio) + +- [Fungus Research](http://leahlee.studio/fungus-research-week-1) +- [Contributing to Fungus](http://leahlee.studio/contributing-to-fungus-for-unity-week-2/) +- [Using a video as a texture](http://leahlee.studio/using-a-video-as-a-texture) + +## Konrad Gadzina + +- [Visual scripting w Unity (Polish)](https://www.youtube.com/watch?v=sXRt7pKT4ls&feature=youtu.be) + +## Chen + +[2D text adventure game dialogue system in Unity 5 (Chinese)](https://www.youtube.com/playlist?list=PLYGd-m5DMaRZgSXtQ4JX3uEKXN67_Jzrp) + diff --git a/Docs/blocks/images/001_3_block_types/1_event_block.png b/Docs/blocks/images/001_3_block_types/1_event_block.png new file mode 100644 index 00000000..77bc1c6b Binary files /dev/null and b/Docs/blocks/images/001_3_block_types/1_event_block.png differ diff --git a/Docs/blocks/images/001_3_block_types/2_branching_block.png b/Docs/blocks/images/001_3_block_types/2_branching_block.png new file mode 100644 index 00000000..a55a40b7 Binary files /dev/null and b/Docs/blocks/images/001_3_block_types/2_branching_block.png differ diff --git a/Docs/blocks/images/001_3_block_types/3_standard_block.png b/Docs/blocks/images/001_3_block_types/3_standard_block.png new file mode 100644 index 00000000..24600331 Binary files /dev/null and b/Docs/blocks/images/001_3_block_types/3_standard_block.png differ diff --git a/Docs/blocks/images/002_call_other_blocks/1_start.png b/Docs/blocks/images/002_call_other_blocks/1_start.png new file mode 100644 index 00000000..dbb2b001 Binary files /dev/null and b/Docs/blocks/images/002_call_other_blocks/1_start.png differ diff --git a/Docs/blocks/images/002_call_other_blocks/2_block2.png b/Docs/blocks/images/002_call_other_blocks/2_block2.png new file mode 100644 index 00000000..0baebea7 Binary files /dev/null and b/Docs/blocks/images/002_call_other_blocks/2_block2.png differ diff --git a/Docs/blocks/images/002_call_other_blocks/3_menu_call.png b/Docs/blocks/images/002_call_other_blocks/3_menu_call.png new file mode 100644 index 00000000..00c03b69 Binary files /dev/null and b/Docs/blocks/images/002_call_other_blocks/3_menu_call.png differ diff --git a/Docs/blocks/images/002_call_other_blocks/4_call_block.png b/Docs/blocks/images/002_call_other_blocks/4_call_block.png new file mode 100644 index 00000000..4c913a15 Binary files /dev/null and b/Docs/blocks/images/002_call_other_blocks/4_call_block.png differ diff --git a/Docs/blocks/images/002_call_other_blocks/5_arrow.png b/Docs/blocks/images/002_call_other_blocks/5_arrow.png new file mode 100644 index 00000000..a17a042a Binary files /dev/null and b/Docs/blocks/images/002_call_other_blocks/5_arrow.png differ diff --git a/Docs/blocks/images/003_highlight_green_arrow/5_arrow.png b/Docs/blocks/images/003_highlight_green_arrow/5_arrow.png new file mode 100644 index 00000000..3dbd33b6 Binary files /dev/null and b/Docs/blocks/images/003_highlight_green_arrow/5_arrow.png differ diff --git a/Docs/blocks/images/004_menu_maths/10_correct.png b/Docs/blocks/images/004_menu_maths/10_correct.png new file mode 100644 index 00000000..196adfa8 Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/10_correct.png differ diff --git a/Docs/blocks/images/004_menu_maths/11_wrong.png b/Docs/blocks/images/004_menu_maths/11_wrong.png new file mode 100644 index 00000000..ed0172a1 Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/11_wrong.png differ diff --git a/Docs/blocks/images/004_menu_maths/1_correct_block.png b/Docs/blocks/images/004_menu_maths/1_correct_block.png new file mode 100644 index 00000000..124ce25d Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/1_correct_block.png differ diff --git a/Docs/blocks/images/004_menu_maths/2_edited_say.png b/Docs/blocks/images/004_menu_maths/2_edited_say.png new file mode 100644 index 00000000..bceaa29d Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/2_edited_say.png differ diff --git a/Docs/blocks/images/004_menu_maths/3_flowchart_menu.png b/Docs/blocks/images/004_menu_maths/3_flowchart_menu.png new file mode 100644 index 00000000..0170deba Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/3_flowchart_menu.png differ diff --git a/Docs/blocks/images/004_menu_maths/4_menu_correct.png b/Docs/blocks/images/004_menu_maths/4_menu_correct.png new file mode 100644 index 00000000..b4f3d96d Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/4_menu_correct.png differ diff --git a/Docs/blocks/images/004_menu_maths/5_connected_blocks.png b/Docs/blocks/images/004_menu_maths/5_connected_blocks.png new file mode 100644 index 00000000..59e7ca07 Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/5_connected_blocks.png differ diff --git a/Docs/blocks/images/004_menu_maths/6_add_menu.png b/Docs/blocks/images/004_menu_maths/6_add_menu.png new file mode 100644 index 00000000..7e19dbd4 Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/6_add_menu.png differ diff --git a/Docs/blocks/images/004_menu_maths/7_wrong_block.png b/Docs/blocks/images/004_menu_maths/7_wrong_block.png new file mode 100644 index 00000000..6a04b667 Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/7_wrong_block.png differ diff --git a/Docs/blocks/images/004_menu_maths/8_three_block_menu.png b/Docs/blocks/images/004_menu_maths/8_three_block_menu.png new file mode 100644 index 00000000..8cdfd038 Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/8_three_block_menu.png differ diff --git a/Docs/blocks/images/004_menu_maths/9_menu_running.png b/Docs/blocks/images/004_menu_maths/9_menu_running.png new file mode 100644 index 00000000..ea8fbe9f Binary files /dev/null and b/Docs/blocks/images/004_menu_maths/9_menu_running.png differ diff --git a/Docs/blocks/images/005_blocks/1_block.png b/Docs/blocks/images/005_blocks/1_block.png new file mode 100644 index 00000000..d5beea2a Binary files /dev/null and b/Docs/blocks/images/005_blocks/1_block.png differ diff --git a/Docs/blocks/images/005_blocks/2_properties.png b/Docs/blocks/images/005_blocks/2_properties.png new file mode 100644 index 00000000..7c5b93eb Binary files /dev/null and b/Docs/blocks/images/005_blocks/2_properties.png differ diff --git a/Docs/blocks/images/006_block_create/1_add_block_button.png b/Docs/blocks/images/006_block_create/1_add_block_button.png new file mode 100644 index 00000000..1c62b06d Binary files /dev/null and b/Docs/blocks/images/006_block_create/1_add_block_button.png differ diff --git a/Docs/blocks/images/006_block_create/2_new_block_created.png b/Docs/blocks/images/006_block_create/2_new_block_created.png new file mode 100644 index 00000000..b1c81051 Binary files /dev/null and b/Docs/blocks/images/006_block_create/2_new_block_created.png differ diff --git a/Docs/blocks/images/007_block_delete/1_delete_menu.png b/Docs/blocks/images/007_block_delete/1_delete_menu.png new file mode 100644 index 00000000..bdcf596d Binary files /dev/null and b/Docs/blocks/images/007_block_delete/1_delete_menu.png differ diff --git a/Docs/blocks/images/007_block_delete/2_block_deleted.png b/Docs/blocks/images/007_block_delete/2_block_deleted.png new file mode 100644 index 00000000..7d66327b Binary files /dev/null and b/Docs/blocks/images/007_block_delete/2_block_deleted.png differ diff --git a/Docs/blocks/images/008_create_flowchart/1_tools_create.png b/Docs/blocks/images/008_create_flowchart/1_tools_create.png new file mode 100644 index 00000000..8b39aa1e Binary files /dev/null and b/Docs/blocks/images/008_create_flowchart/1_tools_create.png differ diff --git a/Docs/blocks/images/008_create_flowchart/2_flowchart_gameobject.png b/Docs/blocks/images/008_create_flowchart/2_flowchart_gameobject.png new file mode 100644 index 00000000..12ce2cf3 Binary files /dev/null and b/Docs/blocks/images/008_create_flowchart/2_flowchart_gameobject.png differ diff --git a/Docs/blocks/images/008_create_flowchart/3_flowchart_properties copy.png b/Docs/blocks/images/008_create_flowchart/3_flowchart_properties copy.png new file mode 100644 index 00000000..2031827e Binary files /dev/null and b/Docs/blocks/images/008_create_flowchart/3_flowchart_properties copy.png differ diff --git a/Docs/blocks/images/008_create_flowchart/3_flowchart_properties.png b/Docs/blocks/images/008_create_flowchart/3_flowchart_properties.png new file mode 100644 index 00000000..0a03f271 Binary files /dev/null and b/Docs/blocks/images/008_create_flowchart/3_flowchart_properties.png differ diff --git a/Docs/blocks/images/009_block_duplicate/1_duplicate_menu.png b/Docs/blocks/images/009_block_duplicate/1_duplicate_menu.png new file mode 100644 index 00000000..21e9a335 Binary files /dev/null and b/Docs/blocks/images/009_block_duplicate/1_duplicate_menu.png differ diff --git a/Docs/blocks/images/009_block_duplicate/2_duplicate_created.png b/Docs/blocks/images/009_block_duplicate/2_duplicate_created.png new file mode 100644 index 00000000..b7f7a0d4 Binary files /dev/null and b/Docs/blocks/images/009_block_duplicate/2_duplicate_created.png differ diff --git a/Docs/blocks/images/010_block_move/1_move1.png b/Docs/blocks/images/010_block_move/1_move1.png new file mode 100644 index 00000000..654cc796 Binary files /dev/null and b/Docs/blocks/images/010_block_move/1_move1.png differ diff --git a/Docs/blocks/images/010_block_move/2_move2.png b/Docs/blocks/images/010_block_move/2_move2.png new file mode 100644 index 00000000..169cb506 Binary files /dev/null and b/Docs/blocks/images/010_block_move/2_move2.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/1_move1.png b/Docs/blocks/images/010_block_move/GIFs/1_move1.png new file mode 100644 index 00000000..654cc796 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/1_move1.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.52.57.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.52.57.png new file mode 100644 index 00000000..c2376c09 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.52.57.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.00.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.00.png new file mode 100644 index 00000000..5869bee3 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.00.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.02.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.02.png new file mode 100644 index 00000000..b46028c4 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.02.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.03.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.03.png new file mode 100644 index 00000000..370deda3 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.03.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.05.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.05.png new file mode 100644 index 00000000..f27c5f80 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.05.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.06.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.06.png new file mode 100644 index 00000000..28c97708 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.06.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.08.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.08.png new file mode 100644 index 00000000..afd46ead Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.08.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.09.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.09.png new file mode 100644 index 00000000..fcc03f03 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.09.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.11.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.11.png new file mode 100644 index 00000000..4afe2149 Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.11.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.14.png b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.14.png new file mode 100644 index 00000000..7c6f070c Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/Screen Shot 2015-06-11 at 13.53.14.png differ diff --git a/Docs/blocks/images/010_block_move/GIFs/animated_block_move.psd b/Docs/blocks/images/010_block_move/GIFs/animated_block_move.psd new file mode 100644 index 00000000..e16ddd1a Binary files /dev/null and b/Docs/blocks/images/010_block_move/GIFs/animated_block_move.psd differ diff --git a/Docs/blocks/images/010_block_move/animated_block_move.gif b/Docs/blocks/images/010_block_move/animated_block_move.gif new file mode 100644 index 00000000..82fa83dd Binary files /dev/null and b/Docs/blocks/images/010_block_move/animated_block_move.gif differ diff --git a/Docs/blocks/images/011_block_name/2_inspect_block.png b/Docs/blocks/images/011_block_name/2_inspect_block.png new file mode 100644 index 00000000..444b0d2a Binary files /dev/null and b/Docs/blocks/images/011_block_name/2_inspect_block.png differ diff --git a/Docs/blocks/images/011_block_name/3_rename.png b/Docs/blocks/images/011_block_name/3_rename.png new file mode 100644 index 00000000..a21828a0 Binary files /dev/null and b/Docs/blocks/images/011_block_name/3_rename.png differ diff --git a/Docs/blocks/images/011_block_name/4_description.png b/Docs/blocks/images/011_block_name/4_description.png new file mode 100644 index 00000000..42429897 Binary files /dev/null and b/Docs/blocks/images/011_block_name/4_description.png differ diff --git a/Docs/blocks/images/012_define_event/1_define_event.png b/Docs/blocks/images/012_define_event/1_define_event.png new file mode 100644 index 00000000..70ebfe85 Binary files /dev/null and b/Docs/blocks/images/012_define_event/1_define_event.png differ diff --git a/Docs/blocks/index.md b/Docs/blocks/index.md new file mode 100644 index 00000000..be6a4134 --- /dev/null +++ b/Docs/blocks/index.md @@ -0,0 +1,311 @@ +# Blocks {#blocks} + +A fundamental concept of Fungus is the **Block**. Blocks contain your Fungus Commands, and reside inside Flowcharts. + + +## Blocks (and how to inspect Block properties) + +Blocks are found inside Flowcharts. Blocks are where your Fungus Commands are stored. Each Block can contain 1 or more Fungus Commands: +![block](./images/005_blocks/1_block.png "block") +To inspect the properties of a Block do the following: + +1. (setup) Create a Fungus Flowchart. + +1. Click to select the default Block in the new Flowchart. You should see the Block's properties displayed in the Inspector window: +
+![block properties](./images/005_blocks/2_properties.png "block properties") +
+
+ + +## Setting Block name and description + +When working with more than one Block, its important to name each Block in a meaningful way. To rename a Block do the following: + +1. (setup) Create a Fungus Flowchart. + +1. Click to select the default Block in the new Flowchart. The selected block has a green outline. + +1. You should see the Block's properties displayed in the Inspector window: +
+![block properties](./images/011_block_name/2_inspect_block.png "block properties") +
+
+ +1. In the Inspector change the text for the Block Name property to "Say Hello". + +1. You should now see the Block has been renamed in the Flowchart window: +
+![block renamed](./images/011_block_name/3_rename.png "block renamed") +
+
+ +1. Now add a detailed description about the Block in the Description property in the Inspector window: +
+![block description](./images/011_block_name/4_description.png "block description") + + +## Creating a block + +To create a new Block do the following: + +1. (setup) Create a Fungus Flowchart (or be viewing the Flowchart for your current project). + +1. Click the Add New Block button (the plus-sign "+") in the top-left of the Fungus Flowchart window: +
+![add block button](./images/006_block_create/1_add_block_button.png "add block button") +
+
+ +1. A new Block should have been added to your Flowchart (with the default name "New Block", or "New Block1/2/3 etc." so each name is unique) +
+![new block](./images/006_block_create/2_new_block_created.png "new block") + +Note - a good time to choose a meaningful name a Block is immediately after creating a new Block ... + + +## Delete a Block + +To delete a Block from the current Flowchart, do the following: + +1. (setup) Create a Fungus Flowchart (or be viewing the Flowchart for your current project). + +1. Right-mouse-click over the Block you wish to delete, and choose menu: ```Delete```: +
+![delete block](./images/007_block_delete/1_delete_menu.png "delete block") +
+
+ +1. The Block should now have been removed from the Flowchart: +
+![deleted block](./images/007_block_delete/2_block_deleted.png "deleted block") + + + +## Duplicate a Block + +To duplicate (clone / make an exact copy of) a Block from the current Flowchart, do the following: + +1. (setup) Create a Fungus Flowchart (or be viewing the Flowchart for your current project). + +1. Right-mouse-click over the Block you wish to duplicate, and choose menu: ```Duplicate```: +
+![duplicate block](./images/009_block_duplicate/1_duplicate_menu.png "duplicate block") +
+
+ +1. A copy of the Block should now have been added to the Flowchart (with "(copy)" appended the name of the duplicate): +
+![duplicated block](./images/009_block_duplicate/2_duplicate_created.png "duplicated block") + +Note - a good time to choose a meaningful name a Block is immediately after duplicating one ... + + +## Moving blocks + +To move / rearrange Blocks in the Flowchart window do the following: + +1. (setup) Create a Fungus Flowchart (or be viewing the Flowchart for your current project). + +1. Move a Block by clicking-and-dragging with the left mouse button: +
+![move block](./images/010_block_move/1_move1.png "move block") +
+
+ +1. When you release the mouse button the Block will remain where it was dragged: +
+![release block](./images/010_block_move/2_move2.png "release block") +
+ +
+![animated move block](./images/010_block_move/animated_block_move.gif "animated move block") +
+ + +## The 3 types of Block (Event Block, Branching Block, Standard Block) + +Fungus Flowcharts visually differentiate three differents kinds of Block behavior: + +1. Event Block - blue rounded rectangle (Block execution triggered by an event) + +1. Branching Block - orange polygon (passes control to 2 or more other Blocks, and not and Event Block) + +1. Standard Block - yellow rectangle (no event, passes control to 0 or 1 other blocks) + +### 1: Event Block - blue rounded rectangle +One way Fungus decides when to start executing the Commands inside a Block is if a Block has defined an Execute On Event. If a Block has any of the possible Execute On Events chosen (such as Game Started, Message Received, Sprite Drag Completed, Key Pressed etc.) then this Block will be displayed as a **blue rounded rectangle**: + +![event block](./images/001_3_block_types/1_event_block.png "event block") + +As we can see, the default Block created with every new Flowchart automatically defines the Game Started Execute On Event, so this default Block always is displayed as an Event Block. + +NOTE: A Block with an Execute On Event will always appear as an Event Block in the Flowchart, regardless of whether its Commands contain menus or calls to 2 or more Blocks). In other words, in terms of Flowchart appearance, display of an Event Block overrides display of a Branching Block. + +### 2: Branching Block - orange polygon +If a Block is *not* an Event Block, and its Commands include Calls and/or Menu commands to execute Commands in 2 or more other Blocks, then in the Flowchart window this Block will be displayed as a Branching Block, visually appearing as an **orange polygon**. + +![branching block](./images/001_3_block_types/2_branching_block.png "branching block") + +### 3: Standard Block - yellow rectangle +If a Block is *neither* an Event Block *nor* a Command Block, then it is a Standard Block, and will be displayed as an **yellow rectangle**. + +![standard block](./images/001_3_block_types/3_standard_block.png "standard block") + + +## Connections between Blocks: Flow of Execution + +A whole scene's logic can rarely fit all into a single Block, therefore we need ways for one Block to pass execution control to other Blocks. There are several ways to do this, the most common being: + +1. the Call Command + +1. the Menu Command + + +## Executing Commands in another Block with the Call Command +The Call Command tells Fungus to go and start executing the Commands in named Block. There are several ways to do this, we can tell Fungus to Stop execution completely in the current Block, and just pass control to named Block. We can also tell Fungus to go and completed all Commands in the named Block, and when they are finished, to then continue executing any remaining commands in the current Block. Finally, and perhaps the most complicated/sophisticated technique, we can tell Fungus to both started executing Commands in a named Block WHILE simultaneously continuing to execute remaining Commands in the current Block. + +To pass control to another Block, and stop executing Commands in the current Block, do the following: + +1. (setup) If you have not already done so: Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename this Block "Start". + +1. Add to Block "Start" a Say Command with the Story Text "I am in Start". +
+![block start](./images/002_call_other_blocks/1_start.png "block start") +
+
+ +1. Add a new Block to your Flowchart named "Block2". + +1. Add to Block "Block2" a Say Command with the Story Text "I am in Block2". +
+![block 2](./images/002_call_other_blocks/2_block2.png "block 2") +
+
+ +1. Add to Block "Block2" a Call Command, by choosing menu: ```Flow | Call```: +
+![flow call](./images/002_call_other_blocks/3_menu_call.png "flow call") +
+
+ +1. With this Call Command Selected, in the Inspector choose Block2 from the list of Blocks for property **Target Block**: +
+![call block menu](./images/002_call_other_blocks/4_call_block.png "call block menu") +
+
+ +1. Note: We will keep the default of **Target Flowchart** (None), which means the current Flowchart. + +1. Note: We will keep the default of **Call Mode** Stop, which means that execution in the current Block (Start) will stop once execution of the called Block has begun. + +1. You should now see an arrow in the Flowchart window, connecting Block "Start" with Block "Block2". This visually tells us (the game developer) that a Call or Menu Command is present inside Block "Start" that tells Fungus to execute commands in Block "Block2": +
+![arrow between blocks](./images/002_call_other_blocks/5_arrow.png "arrow between blocks") +
+
+ + +## Executing Commands in another Block with Menu Commands + +Let's use a Say command above to ask a tricky mathematical question, and demonstrate the Menu command by offering the user a choice been "correct' and "incorrect" answers. Menu commands transfer control to another block - so we'll need to add 2 new blocks to correspond to the 2 answers. +Do the following: + +1. (setup) Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename the Block in the Flowchart to "Question". + +1. Create a Say command, with **Story Text** to ask the question: "Is 2 + 2?". + +2. Uncheck the "Wait For Click" checkbox (this is so we see the menu options immediately after the Say command has displayed the question): +
+![maths say command](./images/004_menu_maths/2_edited_say.png "maths say command") +
+
+ +3. Create a new Block, named "Correct" which contains a **Say** command with the text "Well done, you are very mathematical!". Click the plus-sign button in the Flowchart window to add a new Block to the Flowchart, rename it "Correct" and then add that Say command: +
+![correct block](./images/004_menu_maths/1_correct_block.png "correct block") +
+
+ +4. Select the "Question" block, and add a Menu command by clicking the plus-sign add Command button in the Inspector and then choosing menu: ```Narrative | Menu```. +
+![add menu command](./images/004_menu_maths/6_add_menu.png "add menu command") +
+
+ +5. With this new Menu command selected (green) in the top half of the Inspector window, set the **Text** to "Yes" and the **Target Block** to your new "Correct" block: +
+![menu command](./images/004_menu_maths/4_menu_correct.png "menu command") +
+
+ +6. You should now see how the 'flow' of commands can change from Block "hello" to Block "Correct" in the Flowchart window: +
+![flow between blocks in Flowchart](./images/004_menu_maths/5_connected_blocks.png "flow between blocks in Flowchart") +
+
+ +7. Add a second new Block named "Wrong", containing a Say command with text "Bad luck, perhaps consider a non-mathematical career path..." +
+![block for wrong answer](./images/004_menu_maths/7_wrong_block.png "block for wrong answer") +
+
+ +8. Now we need to add another Menu command to our "hello" block, offering the user the "No" answer to our maths question, and passing control to Block "Wrong" if they disagree that 2 + 2 = 4. Select the "hello" block, and add a Menu command. With this new Menu command selected (green) in the top half of the Inspector window, set the **Text** to "No" and the **Target Block** to your new "Wrong" block. + +9. You should now see in the Flowchart window how block "hello" can pass control to either block "Correct" or Block "Wrong" - depending on which menu answer the user selects. +
+![block connected to 2 others](./images/004_menu_maths/8_three_block_menu.png "block connected to 2 others") +
+
+ +10. Run the scene, and you should see the Say question appear at the bottom of the screen, and also the two Menu buttons "Yes" and "No" in the middle of the screen. Clicking "Yes" then runs the "Correct" Block's commands, and clicking "No" runs the "Wrong" block's commands: +
+![menu running](./images/004_menu_maths/9_menu_running.png "menu running") +
+
+ +
+![correct screen](./images/004_menu_maths/10_correct.png "correct screen") +
+
+ + +
+![wrong screen](./images/004_menu_maths/11_wrong.png "wrong screen") +
+
+ + +## Highlighting connection between blocks by selecting command + +In the Inspector window, if you select a Call or Menu Command (executing Commands in another Block in **the same Flowchart**), then you'll see the arrow between the 2 Blocks highlighted in GREEN: + +![green arrow highlight](./images/003_highlight_green_arrow/5_arrow.png "green arrow highlight") + + +## Setting a Block event handler + +Events are one way to declare when you want execution of the Commands in a Block to begin. Typical events include: + +- Game Started +- Flowchart enabled +- Message Received +- Key Pressed (Up / Down / Repeat) +- Sprite clicking / drag-dropping interactions + +The most common Event used to define when a Block should start execution is, of course, the **Game Started** event. Each new Flowchart automatically starts with a single empty Block that is defined to begin execution when the game starts: + +![event block](./images/001_3_block_types/1_event_block.png "event block") + +To change the Event defined for a Block, or to assign an event for a Block that had None, do the following: + +1. Select the Block in the Flowchart window. + +1. In the Inspector window, for property **Execute On Event** choose from the popup menu the desired Event: + +![define event](./images/012_define_event/1_define_event.png "define event") diff --git a/Docs/command_reference b/Docs/command_reference new file mode 100644 index 00000000..f3caa4b2 --- /dev/null +++ b/Docs/command_reference @@ -0,0 +1,15 @@ +# Command Reference + +* @subpage animation_commands +* @subpage audio_commands +* @subpage camera_commands +* @subpage flow_commands +* @subpage itween_commands +* @subpage narrative_commands +* @subpage scripting_commands +* @subpage sprite_commands +* @subpage variable_commands +* @subpage core_events +* @subpage input_events +* @subpage sprite_events +* @subpage narrative_parser_tokens \ No newline at end of file diff --git a/Docs/commands/animation_commands.md b/Docs/commands/animation_commands.md new file mode 100644 index 00000000..511c65ec --- /dev/null +++ b/Docs/commands/animation_commands.md @@ -0,0 +1,53 @@ +## Play Anim State +Plays a state of an animator according to the state name + +Property | Type | Description + --- | --- | --- +Animator | Fungus.AnimatorData | Reference to an Animator component in a game object +State Name | Fungus.StringData | Name of the state you want to play +Layer | Fungus.IntegerData | Layer to play animation on +Time | Fungus.FloatData | Start time of animation + +## Reset Anim Trigger +Resets a trigger parameter on an Animator component. + +Property | Type | Description + --- | --- | --- +_animator | Fungus.AnimatorData | Reference to an Animator component in a game object +_parameter Name | Fungus.StringData | Name of the trigger Animator parameter that will be reset + +## Set Anim Bool +Sets a boolean parameter on an Animator component to control a Unity animation + +Property | Type | Description + --- | --- | --- +_animator | Fungus.AnimatorData | Reference to an Animator component in a game object +_parameter Name | Fungus.StringData | Name of the boolean Animator parameter that will have its value changed +Value | Fungus.BooleanData | The boolean value to set the parameter to + +## Set Anim Float +Sets a float parameter on an Animator component to control a Unity animation + +Property | Type | Description + --- | --- | --- +_animator | Fungus.AnimatorData | Reference to an Animator component in a game object +_parameter Name | Fungus.StringData | Name of the float Animator parameter that will have its value changed +Value | Fungus.FloatData | The float value to set the parameter to + +## Set Anim Integer +Sets an integer parameter on an Animator component to control a Unity animation + +Property | Type | Description + --- | --- | --- +_animator | Fungus.AnimatorData | Reference to an Animator component in a game object +_parameter Name | Fungus.StringData | Name of the integer Animator parameter that will have its value changed +Value | Fungus.IntegerData | The integer value to set the parameter to + +## Set Anim Trigger +Sets a trigger parameter on an Animator component to control a Unity animation + +Property | Type | Description + --- | --- | --- +_animator | Fungus.AnimatorData | Reference to an Animator component in a game object +_parameter Name | Fungus.StringData | Name of the trigger Animator parameter that will have its value changed + diff --git a/Docs/commands/audio_commands.md b/Docs/commands/audio_commands.md new file mode 100644 index 00000000..3531a676 --- /dev/null +++ b/Docs/commands/audio_commands.md @@ -0,0 +1,60 @@ +## Control Audio +Plays, loops, or stops an audiosource. Any AudioSources with the same tag as the target Audio Source will automatically be stoped. + +Property | Type | Description + --- | --- | --- +Control | Fungus.ControlAudio+ControlType | What to do to audio +_audio Source | Fungus.AudioSourceData | Audio clip to play +Start Volume | System.Single | Start audio at this volume +End Volume | System.Single | End audio at this volume +Fade Duration | System.Single | Time to fade between current volume level and target volume level. +Wait Until Finished | System.Boolean | Wait until this command has finished before executing the next command. + +## Play Music +Plays looping game music. If any game music is already playing, it is stopped. Game music will continue playing across scene loads. + +Property | Type | Description + --- | --- | --- +Music Clip | UnityEngine.AudioClip | Music sound clip to play +At Time | System.Single | Time to begin playing in seconds. If the audio file is compressed, the time index may be inaccurate. +Loop | System.Boolean | The music will start playing again at end. +Fade Duration | System.Single | Length of time to fade out previous playing music. + +## Play Sound +Plays a once-off sound effect. Multiple sound effects can be played at the same time. + +Property | Type | Description + --- | --- | --- +Sound Clip | UnityEngine.AudioClip | Sound effect clip to play +Volume | System.Single | Volume level of the sound effect +Wait Until Finished | System.Boolean | Wait until the sound has finished playing before continuing execution. + +## Play Usfxr Sound +Plays a usfxr synth sound. Use the usfxr editor [Tools > Fungus > Utilities > Generate usfxr Sound Effects] to create the SettingsString. Set a ParentTransform if using positional sound. See https://github.com/zeh/usfxr for more information about usfxr. + +Property | Type | Description + --- | --- | --- +Parent Transform | UnityEngine.Transform | Transform to use for positional audio +_ Settings String | Fungus.StringDataMulti | Settings string which describes the audio +Wait Duration | System.Single | Time to wait before executing the next command + +## Set Audio Pitch +Sets the global pitch level for audio played with Play Music and Play Sound commands. + +Property | Type | Description + --- | --- | --- +Pitch | System.Single | Global pitch level for audio played using the Play Music and Play Sound commands +Fade Duration | System.Single | Time to fade between current pitch level and target pitch level. +Wait Until Finished | System.Boolean | Wait until the pitch change has finished before executing next command + +## Set Audio Volume +Sets the global volume level for audio played with Play Music and Play Sound commands. + +Property | Type | Description + --- | --- | --- +Volume | System.Single | Global volume level for audio played using Play Music and Play Sound +Fade Duration | System.Single | Time to fade between current volume level and target volume level. +Wait Until Finished | System.Boolean | Wait until the volume fade has completed before continuing. + +## Stop Music +Stops the currently playing game music. diff --git a/Docs/commands/camera_commands.md b/Docs/commands/camera_commands.md new file mode 100644 index 00000000..4942788a --- /dev/null +++ b/Docs/commands/camera_commands.md @@ -0,0 +1,58 @@ +## Fade Screen +Draws a fullscreen texture over the scene to give a fade effect. Setting Target Alpha to 1 will obscure the screen, alpha 0 will reveal the screen. If no Fade Texture is provided then a default flat color texture is used. + +Property | Type | Description + --- | --- | --- +Duration | System.Single | Time for fade effect to complete +Target Alpha | System.Single | Current target alpha transparency value. The fade gradually adjusts the alpha to approach this target value. +Wait Until Finished | System.Boolean | Wait until the fade has finished before executing next command +Fade Color | UnityEngine.Color | Color to render fullscreen fade texture with when screen is obscured. +Fade Texture | UnityEngine.Texture2D | Optional texture to use when rendering the fullscreen fade effect. + +## Fade To View +Fades the camera out and in again at a position specified by a View object. + +Property | Type | Description + --- | --- | --- +Duration | System.Single | Time for fade effect to complete +Fade Out | System.Boolean | Fade from fully visible to opaque at start of fade +Target View | Fungus.View | View to transition to when Fade is complete +Wait Until Finished | System.Boolean | Wait until the fade has finished before executing next command +Fade Color | UnityEngine.Color | Color to render fullscreen fade texture with when screen is obscured. +Fade Texture | UnityEngine.Texture2D | Optional texture to use when rendering the fullscreen fade effect. +Target Camera | UnityEngine.Camera | Camera to use for the fade. Will use main camera if set to none. + +## Fullscreen +Sets the application to fullscreen, windowed or toggles the current state. +## Move To View +Moves the camera to a location specified by a View object. + +Property | Type | Description + --- | --- | --- +Duration | System.Single | Time for move effect to complete +Target View | Fungus.View | View to transition to when move is complete +Wait Until Finished | System.Boolean | Wait until the fade has finished before executing next command +Target Camera | UnityEngine.Camera | Camera to use for the pan. Will use main camera if set to none. + +## Shake Camera +Applies a camera shake effect to the main camera. + +Property | Type | Description + --- | --- | --- +Duration | System.Single | Time for camera shake effect to complete +Amount | UnityEngine.Vector2 | Magnitude of shake effect in x & y axes +Wait Until Finished | System.Boolean | Wait until the shake effect has finished before executing next command + +## Start Swipe +Activates swipe panning mode where the player can pan the camera within the area between viewA & viewB. + +Property | Type | Description + --- | --- | --- +View A | Fungus.View | Defines one extreme of the scrollable area that the player can pan around +View B | Fungus.View | Defines one extreme of the scrollable area that the player can pan around +Duration | System.Single | Time to move the camera to a valid starting position between the two views +Speed Multiplier | System.Single | Multiplier factor for speed of swipe pan +Target Camera | UnityEngine.Camera | Camera to use for the pan. Will use main camera if set to none. + +## Stop Swipe +Deactivates swipe panning mode. diff --git a/Docs/commands/event_handlers/core_events.md b/Docs/commands/event_handlers/core_events.md new file mode 100644 index 00000000..6fcb67c2 --- /dev/null +++ b/Docs/commands/event_handlers/core_events.md @@ -0,0 +1,11 @@ +## Flowchart Enabled +The block will execute when the Flowchart game object is enabled. +## Game Started +The block will execute when the game starts playing. +## Message Received +The block will execute when the specified message is received from a Send Message command. + +Property | Type | Description + --- | --- | --- +Message | System.String | Fungus message to listen for + diff --git a/Docs/commands/event_handlers/input_events.md b/Docs/commands/event_handlers/input_events.md new file mode 100644 index 00000000..ed4f78c5 --- /dev/null +++ b/Docs/commands/event_handlers/input_events.md @@ -0,0 +1,8 @@ +## Key Pressed +The block will execute when a key press event occurs. + +Property | Type | Description + --- | --- | --- +Key Press Type | Fungus.KeyPressed+KeyPressType | The type of keypress to activate on +Key Code | UnityEngine.KeyCode | Keycode of the key to activate on + diff --git a/Docs/commands/event_handlers/sprite_events.md b/Docs/commands/event_handlers/sprite_events.md new file mode 100644 index 00000000..b5c0bab4 --- /dev/null +++ b/Docs/commands/event_handlers/sprite_events.md @@ -0,0 +1,40 @@ +## Drag Cancelled +The block will execute when the player drags an object and releases it without dropping it on a target object. + +Property | Type | Description + --- | --- | --- +Draggable Object | Fungus.Draggable2D | Draggable object to listen for drag events on + +## Drag Completed +The block will execute when the player drags an object and successfully drops it on a target object. + +Property | Type | Description + --- | --- | --- +Draggable Object | Fungus.Draggable2D | Draggable object to listen for drag events on +Target Object | UnityEngine.Collider2D | Drag target object to listen for drag events on + +## Drag Entered +The block will execute when the player is dragging an object which starts touching the target object. + +Property | Type | Description + --- | --- | --- +Draggable Object | Fungus.Draggable2D | Draggable object to listen for drag events on +Target Object | UnityEngine.Collider2D | Drag target object to listen for drag events on + +## Drag Exited +The block will execute when the player is dragging an object which stops touching the target object. + +Property | Type | Description + --- | --- | --- +Draggable Object | Fungus.Draggable2D | Draggable object to listen for drag events on +Target Object | UnityEngine.Collider2D | Drag target object to listen for drag events on + +## Drag Started +The block will execute when the player starts dragging an object. +## Object Clicked +The block will execute when the user clicks or taps on the clickable object. + +Property | Type | Description + --- | --- | --- +Clickable Object | Fungus.Clickable2D | Object that the user can click or tap on + diff --git a/Docs/commands/flow_commands.md b/Docs/commands/flow_commands.md new file mode 100644 index 00000000..78052452 --- /dev/null +++ b/Docs/commands/flow_commands.md @@ -0,0 +1,116 @@ +## Break +Force a loop to terminate immediately. +## Call +Execute another block in the same Flowchart as the command, or in a different Flowchart. + +Property | Type | Description + --- | --- | --- +Target Flowchart | Fungus.Flowchart | Flowchart which contains the block to execute. If none is specified then the current Flowchart is used. +Target Block | Fungus.Block | Block to start executing +Start Index | System.Int32 | Command index to start executing +Call Mode | Fungus.Call+CallMode | Select if the calling block should stop or continue executing commands, or wait until the called block finishes. + +## Else +Marks the start of a command block to be executed when the preceding If statement is False. +## Else If +Marks the start of a command block to be executed when the preceding If statement is False and the test expression is true. + +Property | Type | Description + --- | --- | --- +Variable | Fungus.Variable | Variable to use in expression +Boolean Data | Fungus.BooleanData | Boolean value to compare against +Integer Data | Fungus.IntegerData | Integer value to compare against +Float Data | Fungus.FloatData | Float value to compare against +String Data | Fungus.StringDataMulti | String value to compare against +Compare Operator | Fungus.CompareOperator | The type of comparison to be performed + +## End +Marks the end of a conditional block. +## If +If the test expression is true, execute the following command block. + +Property | Type | Description + --- | --- | --- +Variable | Fungus.Variable | Variable to use in expression +Boolean Data | Fungus.BooleanData | Boolean value to compare against +Integer Data | Fungus.IntegerData | Integer value to compare against +Float Data | Fungus.FloatData | Float value to compare against +String Data | Fungus.StringDataMulti | String value to compare against +Compare Operator | Fungus.CompareOperator | The type of comparison to be performed + +## Jump +Move execution to a specific Label command in the same block + +Property | Type | Description + --- | --- | --- +_target Label | Fungus.StringData | Name of a label in this block to jump to + +## Label +Marks a position in the command list for execution to jump to. + +Property | Type | Description + --- | --- | --- +Key | System.String | Display name for the label + +## Load Scene +Loads a new Unity scene and displays an optional loading image. This is useful for splitting a large game across multiple scene files to reduce peak memory usage. Previously loaded assets will be released before loading the scene to free up memory.The scene to be loaded must be added to the scene list in Build Settings. + +Property | Type | Description + --- | --- | --- +_scene Name | Fungus.StringData | Name of the scene to load. The scene must also be added to the build settings. +Loading Image | UnityEngine.Texture2D | Image to display while loading the scene + +## Quit +Quits the application. Does not work in Editor or Webplayer builds. Shouldn't generally be used on iOS. +## Send Message +Sends a message to either the owner Flowchart or all Flowcharts in the scene. Blocks can listen for this message using a Message Received event handler. + +Property | Type | Description + --- | --- | --- +Message Target | Fungus.SendMessage+MessageTarget | Target flowchart(s) to send the message to +_message | Fungus.StringData | Name of the message to send + +## Stop +Stop executing the Block that contains this command. +## Stop Block +Stops executing the named Block + +Property | Type | Description + --- | --- | --- +Flowchart | Fungus.Flowchart | Flowchart containing the Block. If none is specified, the parent Flowchart is used. +Block Name | Fungus.StringData | Name of the Block to stop + +## Stop Flowchart +Stops execution of all Blocks in a Flowchart + +Property | Type | Description + --- | --- | --- +Stop Parent Flowchart | System.Boolean | Stop all executing Blocks in the Flowchart that contains this command +Target Flowcharts | System.Collections.Generic.List`1[Fungus.Flowchart] | Stop all executing Blocks in a list of target Flowcharts + +## Wait +Waits for period of time before executing the next command in the block. + +Property | Type | Description + --- | --- | --- +_duration | Fungus.FloatData | Duration to wait for + +## WaitInput +Waits for a period of time or for player input before executing the next command in the block. + +Property | Type | Description + --- | --- | --- +Duration | System.Single | Duration to wait for. If negative will wait until player input occurs. + +## While +Continuously loop through a block of commands while the condition is true. Use the Break command to force the loop to terminate immediately. + +Property | Type | Description + --- | --- | --- +Variable | Fungus.Variable | Variable to use in expression +Boolean Data | Fungus.BooleanData | Boolean value to compare against +Integer Data | Fungus.IntegerData | Integer value to compare against +Float Data | Fungus.FloatData | Float value to compare against +String Data | Fungus.StringDataMulti | String value to compare against +Compare Operator | Fungus.CompareOperator | The type of comparison to be performed + diff --git a/Docs/commands/itween_commands.md b/Docs/commands/itween_commands.md new file mode 100644 index 00000000..c83acea9 --- /dev/null +++ b/Docs/commands/itween_commands.md @@ -0,0 +1,268 @@ +## Look From +Instantly rotates a GameObject to look at the supplied Vector3 then returns it to it's starting rotation over time. + +Property | Type | Description + --- | --- | --- +_from Transform | Fungus.TransformData | Target transform that the GameObject will look at +_from Position | Fungus.Vector3Data | Target world position that the GameObject will look at, if no From Transform is set +Axis | Fungus.iTweenAxis | Restricts rotation to the supplied axis only +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Look To +Rotates a GameObject to look at a supplied Transform or Vector3 over time. + +Property | Type | Description + --- | --- | --- +_to Transform | Fungus.TransformData | Target transform that the GameObject will look at +_to Position | Fungus.Vector3Data | Target world position that the GameObject will look at, if no From Transform is set +Axis | Fungus.iTweenAxis | Restricts rotation to the supplied axis only +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Move Add +Moves a game object by a specified offset over time. + +Property | Type | Description + --- | --- | --- +_offset | Fungus.Vector3Data | A translation offset in space the GameObject will animate to +Space | UnityEngine.Space | Apply the transformation in either the world coordinate or local cordinate system +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Move From +Moves a game object from a specified position back to its starting position over time. The position can be defined by a transform in another object (using To Transform) or by setting an absolute position (using To Position, if To Transform is set to None). + +Property | Type | Description + --- | --- | --- +_from Transform | Fungus.TransformData | Target transform that the GameObject will move from +_from Position | Fungus.Vector3Data | Target world position that the GameObject will move from, if no From Transform is set +Is Local | System.Boolean | Whether to animate in world space or relative to the parent. False by default. +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Move To +Moves a game object to a specified position over time. The position can be defined by a transform in another object (using To Transform) or by setting an absolute position (using To Position, if To Transform is set to None). + +Property | Type | Description + --- | --- | --- +_to Transform | Fungus.TransformData | Target transform that the GameObject will move to +_to Position | Fungus.Vector3Data | Target world position that the GameObject will move to, if no From Transform is set +Is Local | System.Boolean | Whether to animate in world space or relative to the parent. False by default. +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Punch Position +Applies a jolt of force to a GameObject's position and wobbles it back to its initial position. + +Property | Type | Description + --- | --- | --- +_amount | Fungus.Vector3Data | A translation offset in space the GameObject will animate to +Space | UnityEngine.Space | Apply the transformation in either the world coordinate or local cordinate system +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Punch Rotation +Applies a jolt of force to a GameObject's rotation and wobbles it back to its initial rotation. + +Property | Type | Description + --- | --- | --- +_amount | Fungus.Vector3Data | A rotation offset in space the GameObject will animate to +Space | UnityEngine.Space | Apply the transformation in either the world coordinate or local cordinate system +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Punch Scale +Applies a jolt of force to a GameObject's scale and wobbles it back to its initial scale. + +Property | Type | Description + --- | --- | --- +_amount | Fungus.Vector3Data | A scale offset in space the GameObject will animate to +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Rotate Add +Rotates a game object by the specified angles over time. + +Property | Type | Description + --- | --- | --- +_offset | Fungus.Vector3Data | A rotation offset in space the GameObject will animate to +Space | UnityEngine.Space | Apply the transformation in either the world coordinate or local cordinate system +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Rotate From +Rotates a game object from the specified angles back to its starting orientation over time. + +Property | Type | Description + --- | --- | --- +_from Transform | Fungus.TransformData | Target transform that the GameObject will rotate from +_from Rotation | Fungus.Vector3Data | Target rotation that the GameObject will rotate from, if no From Transform is set +Is Local | System.Boolean | Whether to animate in world space or relative to the parent. False by default. +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Rotate To +Rotates a game object to the specified angles over time. + +Property | Type | Description + --- | --- | --- +_to Transform | Fungus.TransformData | Target transform that the GameObject will rotate to +_to Rotation | Fungus.Vector3Data | Target rotation that the GameObject will rotate to, if no To Transform is set +Is Local | System.Boolean | Whether to animate in world space or relative to the parent. False by default. +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Scale Add +Changes a game object's scale by a specified offset over time. + +Property | Type | Description + --- | --- | --- +_offset | Fungus.Vector3Data | A scale offset in space the GameObject will animate to +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Scale From +Changes a game object's scale to the specified value and back to its original scale over time. + +Property | Type | Description + --- | --- | --- +_from Transform | Fungus.TransformData | Target transform that the GameObject will scale from +_from Scale | Fungus.Vector3Data | Target scale that the GameObject will scale from, if no From Transform is set +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Scale To +Changes a game object's scale to a specified value over time. + +Property | Type | Description + --- | --- | --- +_to Transform | Fungus.TransformData | Target transform that the GameObject will scale to +_to Scale | Fungus.Vector3Data | Target scale that the GameObject will scale to, if no To Transform is set +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Shake Position +Randomly shakes a GameObject's position by a diminishing amount over time. + +Property | Type | Description + --- | --- | --- +_amount | Fungus.Vector3Data | A translation offset in space the GameObject will animate to +Is Local | System.Boolean | Whether to animate in world space or relative to the parent. False by default. +Axis | Fungus.iTweenAxis | Restricts rotation to the supplied axis only +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Shake Rotation +Randomly shakes a GameObject's rotation by a diminishing amount over time. + +Property | Type | Description + --- | --- | --- +_amount | Fungus.Vector3Data | A rotation offset in space the GameObject will animate to +Space | UnityEngine.Space | Apply the transformation in either the world coordinate or local cordinate system +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Shake Scale +Randomly shakes a GameObject's rotation by a diminishing amount over time. + +Property | Type | Description + --- | --- | --- +_amount | Fungus.Vector3Data | A scale offset in space the GameObject will animate to +_target Object | Fungus.GameObjectData | Target game object to apply the Tween to +_tween Name | Fungus.StringData | An individual name useful for stopping iTweens by name +_duration | Fungus.FloatData | The time in seconds the animation will take to complete +Ease Type | Fungus.iTween+EaseType | The shape of the easing curve applied to the animation +Loop Type | Fungus.iTween+LoopType | The type of loop to apply once the animation has completed +Stop Previous Tweens | System.Boolean | Stop any previously added iTweens on this object before adding this iTween +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command + +## Stop Tween +Stops an active iTween by name. + +Property | Type | Description + --- | --- | --- +_tween Name | Fungus.StringData | Stop and destroy any Tweens in current scene with the supplied name + +## Stop Tweens +Stop all active iTweens in the current scene. diff --git a/Docs/commands/narrative_commands.md b/Docs/commands/narrative_commands.md new file mode 100644 index 00000000..c670bf5a --- /dev/null +++ b/Docs/commands/narrative_commands.md @@ -0,0 +1,101 @@ +## Clear Menu +Clears the options from a menu dialogue + +Property | Type | Description + --- | --- | --- +Menu Dialog | Fungus.MenuDialog | Menu Dialog to clear the options on + +## Control Stage +Controls the stage on which character portraits are displayed. + +Property | Type | Description + --- | --- | --- +Stage | Fungus.Stage | Stage to display characters on +Replaced Stage | Fungus.Stage | Stage to swap with +Use Default Settings | System.Boolean | Use Default Settings +Fade Duration | System.Single | Fade Duration +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command +Display | Fungus.StageDisplayType | Display type + +## Conversation +Do multiple say and portrait commands in a single block of text. Format is: [character] [portrait] [stage position] [: Story text] +## Menu +Displays a button in a multiple choice menu + +Property | Type | Description + --- | --- | --- +Text | System.String | Text to display on the menu button +Description | System.String | Notes about the option text for other authors, localization, etc. +Target Block | Fungus.Block | Block to execute when this option is selected +Hide If Visited | System.Boolean | Hide this option if the target block has been executed previously +Interactable | Fungus.BooleanData | If false, the menu option will be displayed but will not be selectable +Set Menu Dialog | Fungus.MenuDialog | A custom Menu Dialog to use to display this menu. All subsequent Menu commands will use this dialog. + +## Menu Timer +Displays a timer bar and executes a target block if the player fails to select a menu option in time. + +Property | Type | Description + --- | --- | --- +_duration | Fungus.FloatData | Length of time to display the timer for +Target Block | Fungus.Block | Block to execute when the timer expires + +## Portrait +Controls a character portrait. + +Property | Type | Description + --- | --- | --- +Stage | Fungus.Stage | Stage to display portrait on +Character | Fungus.Character | Character to display +Replaced Character | Fungus.Character | Character to swap with +Portrait | UnityEngine.Sprite | Portrait to display +Offset | Fungus.PositionOffset | Move the portrait from/to this offset position +From Position | UnityEngine.RectTransform | Move the portrait from this position +To Position | UnityEngine.RectTransform | Move the portrait to this positoin +Facing | Fungus.FacingDirection | Direction character is facing +Use Default Settings | System.Boolean | Use Default Settings +Fade Duration | System.Single | Fade Duration +Move Duration | System.Single | Movement Duration +Shift Offset | UnityEngine.Vector2 | Shift Offset +Move | System.Boolean | Move +Shift Into Place | System.Boolean | Start from offset +Wait Until Finished | System.Boolean | Wait until the tween has finished before executing the next command +Display | Fungus.DisplayType | Display type + +## Say +Writes text in a dialog box. + +Property | Type | Description + --- | --- | --- +Description | System.String | Notes about this story text for other authors, localization, etc. +Character | Fungus.Character | Character that is speaking +Portrait | UnityEngine.Sprite | Portrait that represents speaking character +Voice Over Clip | UnityEngine.AudioClip | Voiceover audio to play when writing the text +Show Always | System.Boolean | Always show this Say text when the command is executed multiple times +Show Count | System.Int32 | Number of times to show this Say text when the command is executed multiple times +Extend Previous | System.Boolean | Type this text in the previous dialog box. +Fade When Done | System.Boolean | Fade out the dialog box when writing has finished and not waiting for input. +Wait For Click | System.Boolean | Wait for player to click before continuing. +Stop Voiceover | System.Boolean | Stop playing voiceover when text finishes writing. +Set Say Dialog | Fungus.SayDialog | Sets the active Say dialog with a reference to a Say Dialog object in the scene. All story text will now display using this Say Dialog. + +## Set Language +Set the active language for the scene. A Localization object with a localization file must be present in the scene. + +Property | Type | Description + --- | --- | --- +_language Code | Fungus.StringData | Code of the language to set. e.g. ES, DE, JA + +## Set Menu Dialog +Sets a custom menu dialog to use when displaying multiple choice menus + +Property | Type | Description + --- | --- | --- +Menu Dialog | Fungus.MenuDialog | The Menu Dialog to use for displaying menu buttons + +## Set Say Dialog +Sets a custom say dialog to use when displaying story text + +Property | Type | Description + --- | --- | --- +Say Dialog | Fungus.SayDialog | The Say Dialog to use for displaying Say story text + diff --git a/Docs/commands/scripting_commands.md b/Docs/commands/scripting_commands.md new file mode 100644 index 00000000..90d3cca2 --- /dev/null +++ b/Docs/commands/scripting_commands.md @@ -0,0 +1,103 @@ +## Comment +Use comments to record design notes and reminders about your game. + +Property | Type | Description + --- | --- | --- +Commenter Name | System.String | Name of Commenter +Comment Text | System.String | Text to display for this comment + +## Call Method +Calls a named method on a GameObject using the GameObject.SendMessage() system. + +Property | Type | Description + --- | --- | --- +Target Object | UnityEngine.GameObject | Target monobehavior which contains the method we want to call +Method Name | System.String | Name of the method to call +Delay | System.Single | Delay (in seconds) before the method will be called + +## Debug Log +Writes a log message to the debug console. + +Property | Type | Description + --- | --- | --- +Log Type | Fungus.DebugLog+DebugLogType | Display type of debug log info +Log Message | Fungus.StringDataMulti | Text to write to the debug log. Supports variable substitution, e.g. {$Myvar} + +## Destroy +Destroys a specified game object in the scene. + +Property | Type | Description + --- | --- | --- +_target Game Object | Fungus.GameObjectData | Reference to game object to destroy + +## Execute Lua +Executes a Lua code chunk using a Lua Environment. + +Property | Type | Description + --- | --- | --- +Lua Environment | Fungus.LuaEnvironment | Lua Environment to use to execute this Lua script +Lua File | UnityEngine.TextAsset | A text file containing Lua script to execute. +Lua Script | System.String | Lua script to execute. This text is appended to the contents of Lua file (if one is specified). +Run As Coroutine | System.Boolean | Execute this Lua script as a Lua coroutine +Wait Until Finished | System.Boolean | Pause command execution until the Lua script has finished execution +Return Variable | Fungus.Variable | A Flowchart variable to store the returned value in. + +## Invoke Event +Calls a list of component methods via the Unity Event System (as used in the Unity UI). This command is more efficient than the Invoke Method command but can only pass a single parameter and doesn't support return values. + +Property | Type | Description + --- | --- | --- +Delay | System.Single | Delay (in seconds) before the methods will be called +Static Event | UnityEngine.Events.UnityEvent | List of methods to call. Supports methods with no parameters or exactly one string, int, float or object parameter. +Boolean Parameter | Fungus.BooleanData | Boolean parameter to pass to the invoked methods. +Boolean Event | Fungus.InvokeEvent+BooleanEvent | List of methods to call. Supports methods with one boolean parameter. +Integer Parameter | Fungus.IntegerData | Integer parameter to pass to the invoked methods. +Integer Event | Fungus.InvokeEvent+IntegerEvent | List of methods to call. Supports methods with one integer parameter. +Float Parameter | Fungus.FloatData | Float parameter to pass to the invoked methods. +Float Event | Fungus.InvokeEvent+FloatEvent | List of methods to call. Supports methods with one float parameter. +String Parameter | Fungus.StringDataMulti | String parameter to pass to the invoked methods. +String Event | Fungus.InvokeEvent+StringEvent | List of methods to call. Supports methods with one string parameter. + +## Invoke Method +Invokes a method of a component via reflection. Supports passing multiple parameters and storing returned values in a Fungus variable. + +Property | Type | Description + --- | --- | --- +Target Object | UnityEngine.GameObject | GameObject containing the component method to be invoked +Target Component Assembly Name | System.String | Name of assembly containing the target component +Target Component Fullname | System.String | Full name of the target component +Target Component Text | System.String | Display name of the target component +Target Method | System.String | Name of target method to invoke on the target component +Target Method Text | System.String | Display name of target method to invoke on the target component +Method Parameters | Fungus.InvokeMethodParameter[] | List of parameters to pass to the invoked method +Save Return Value | System.Boolean | If true, store the return value in a flowchart variable of the same type. +Return Value Variable Key | System.String | Name of Fungus variable to store the return value in +Return Value Type | System.String | The type of the return value +Show Inherited | System.Boolean | If true, list all inherited methods for the component +Call Mode | Fungus.Call+CallMode | The coroutine call behavior for methods that return IEnumerator + +## Open URL +Opens the specified URL in the browser. + +Property | Type | Description + --- | --- | --- +Url | Fungus.StringData | URL to open in the browser + +## Set Active +Sets a game object in the scene to be active / inactive. + +Property | Type | Description + --- | --- | --- +_target Game Object | Fungus.GameObjectData | Reference to game object to enable / disable +Active State | Fungus.BooleanData | Set to true to enable the game object + +## Spawn Object +Spawns a new object based on a reference to a scene or prefab game object. + +Property | Type | Description + --- | --- | --- +_source Object | Fungus.GameObjectData | Game object to copy when spawning. Can be a scene object or a prefab. +_parent Transform | Fungus.TransformData | Transform to use for position of newly spawned object. +_spawn Position | Fungus.Vector3Data | Local position of newly spawned object. +_spawn Rotation | Fungus.Vector3Data | Local rotation of newly spawned object. + diff --git a/Docs/commands/sprite_commands.md b/Docs/commands/sprite_commands.md new file mode 100644 index 00000000..0ffb4fb7 --- /dev/null +++ b/Docs/commands/sprite_commands.md @@ -0,0 +1,68 @@ +## Fade Sprite +Fades a sprite to a target color over a period of time. + +Property | Type | Description + --- | --- | --- +Sprite Renderer | UnityEngine.SpriteRenderer | Sprite object to be faded +_duration | Fungus.FloatData | Length of time to perform the fade +_target Color | Fungus.ColorData | Target color to fade to. To only fade transparency level, set the color to white and set the alpha to required transparency. +Wait Until Finished | System.Boolean | Wait until the fade has finished before executing the next command + +## Set Clickable 2D +Sets a Clickable2D component to be clickable / non-clickable. + +Property | Type | Description + --- | --- | --- +Target Clickable2 D | Fungus.Clickable2D | Reference to Clickable2D component on a gameobject +Active State | Fungus.BooleanData | Set to true to enable the component + +## Set Collider +Sets all collider (2d or 3d) components on the target objects to be active / inactive + +Property | Type | Description + --- | --- | --- +Target Objects | System.Collections.Generic.List`1[UnityEngine.GameObject] | A list of gameobjects containing collider components to be set active / inactive +Target Tag | System.String | All objects with this tag will have their collider set active / inactive +Active State | Fungus.BooleanData | Set to true to enable the collider components + +## Set Draggable 2D +Sets a Draggable2D component to be draggable / non-draggable. + +Property | Type | Description + --- | --- | --- +Target Draggable2 D | Fungus.Draggable2D | Reference to Draggable2D component on a gameobject +Active State | Fungus.BooleanData | Set to true to enable the component + +## Set Mouse Cursor +Sets the mouse cursor sprite. + +Property | Type | Description + --- | --- | --- +Cursor Texture | UnityEngine.Texture2D | Texture to use for cursor. Will use default mouse cursor if no sprite is specified +Hot Spot | UnityEngine.Vector2 | The offset from the top left of the texture to use as the target point + +## Set Sorting Layer +Sets the Renderer sorting layer of every child of a game object. Applies to all Renderers (including mesh, skinned mesh, and sprite). + +Property | Type | Description + --- | --- | --- +Target Object | UnityEngine.GameObject | Root Object that will have the Sorting Layer set. Any children will also be affected +Sorting Layer | System.String | The New Layer Name to apply + +## Set Sprite Order +Controls the render order of sprites by setting the Order In Layer property of a list of sprites. + +Property | Type | Description + --- | --- | --- +Target Sprites | System.Collections.Generic.List`1[UnityEngine.SpriteRenderer] | List of sprites to set the order in layer property on +Order In Layer | Fungus.IntegerData | The order in layer value to set on the target sprites + +## Show Sprite +Makes a sprite visible / invisible by setting the color alpha. + +Property | Type | Description + --- | --- | --- +Sprite Renderer | UnityEngine.SpriteRenderer | Sprite object to be made visible / invisible +_visible | Fungus.BooleanData | Make the sprite visible or invisible +Affect Children | System.Boolean | Affect the visibility of child sprites + diff --git a/Docs/commands/tests_commands.md b/Docs/commands/tests_commands.md new file mode 100644 index 00000000..8118b25b --- /dev/null +++ b/Docs/commands/tests_commands.md @@ -0,0 +1,6 @@ +## Fail +Fails the current integration test +## Pass +Passes the current integration test +## TestNarrative +Test command for narrative integration tests diff --git a/Docs/commands/ui_commands.md b/Docs/commands/ui_commands.md new file mode 100644 index 00000000..014da5c2 --- /dev/null +++ b/Docs/commands/ui_commands.md @@ -0,0 +1,54 @@ +## Fade UI +Fades a UI object + +Property | Type | Description + --- | --- | --- +Target Objects | System.Collections.Generic.List`1[UnityEngine.GameObject] | List of objects to be affected by the tween +Tween Type | LeanTweenType | Type of tween easing to apply +Wait Until Finished | Fungus.BooleanData | Wait until this command completes before continuing execution +Duration | Fungus.FloatData | Time for the tween to complete + +## Get Text +Gets the text property from a UI Text object and stores it in a string variable. + +Property | Type | Description + --- | --- | --- +Target Text Object | UnityEngine.GameObject | Text object to get text value from +String Variable | Fungus.StringVariable | String variable to store the text value in + +## Set Interactable +Set the interactable sate of selectable objects. + +Property | Type | Description + --- | --- | --- +Target Objects | System.Collections.Generic.List`1[UnityEngine.GameObject] | List of objects to be affected by the command +Interactable State | Fungus.BooleanData | Controls if the selectable UI object be interactable or not + +## Set Slider Value +Sets the value property of a slider object + +Property | Type | Description + --- | --- | --- +Slider | UnityEngine.UI.Slider | Target slider object to set the value on +Value | Fungus.FloatData | Float value to set the slider value to. + +## Set Text +Sets the text property on a UI Text object and/or an Input Field object. + +Property | Type | Description + --- | --- | --- +Target Text Object | UnityEngine.GameObject | Text object to set text on. Can be a UI Text, Text Field or Text Mesh object. +Text | Fungus.StringDataMulti | String value to assign to the text object +Description | System.String | Notes about this story text for other authors, localization, etc. + +## Write +Writes content to a UI Text or Text Mesh object. + +Property | Type | Description + --- | --- | --- +Text Object | UnityEngine.GameObject | Text object to set text on. Text, Input Field and Text Mesh objects are supported. +Text | Fungus.StringDataMulti | String value to assign to the text object +Description | System.String | Notes about this story text for other authors, localization, etc. +Clear Text | System.Boolean | Clear existing text before writing new text +Wait Until Finished | System.Boolean | Wait until this command finishes before executing the next command + diff --git a/Docs/commands/variable_commands.md b/Docs/commands/variable_commands.md new file mode 100644 index 00000000..2e7fe675 --- /dev/null +++ b/Docs/commands/variable_commands.md @@ -0,0 +1,76 @@ +## Delete Save Key +Deletes a saved value from permanent storage. + +Property | Type | Description + --- | --- | --- +Key | System.String | Name of the saved value. Supports variable substition e.g. "player_{$PlayerNumber} + +## Load Variable +Loads a saved value and stores it in a Boolean, Integer, Float or String variable. If the key is not found then the variable is not modified. + +Property | Type | Description + --- | --- | --- +Key | System.String | Name of the saved value. Supports variable substition e.g. "player_{$PlayerNumber}" +Variable | Fungus.Variable | Variable to store the value in. + +## Random Float +Sets an float variable to a random value in the defined range. + +Property | Type | Description + --- | --- | --- +Variable | Fungus.FloatVariable | The variable whos value will be set +Min Value | Fungus.FloatData | Minimum value for random range +Max Value | Fungus.FloatData | Maximum value for random range + +## Random Integer +Sets an integer variable to a random value in the defined range. + +Property | Type | Description + --- | --- | --- +Variable | Fungus.IntegerVariable | The variable whos value will be set +Min Value | Fungus.IntegerData | Minimum value for random range +Max Value | Fungus.IntegerData | Maximum value for random range + +## Read Text File +Reads in a text file and stores the contents in a string variable + +Property | Type | Description + --- | --- | --- +Text File | UnityEngine.TextAsset | Text file to read into the string variable +String Variable | Fungus.StringVariable | String variable to store the tex file contents in + +## Reset +Resets the state of all commands and variables in the Flowchart. + +Property | Type | Description + --- | --- | --- +Reset Commands | System.Boolean | Reset state of all commands in the script +Reset Variables | System.Boolean | Reset variables back to their default values + +## Save Variable +Save an Boolean, Integer, Float or String variable to persistent storage using a string key. The value can be loaded again later using the Load Variable command. You can also use the Set Save Profile command to manage separate save profiles for multiple players. + +Property | Type | Description + --- | --- | --- +Key | System.String | Name of the saved value. Supports variable substition e.g. "player_{$PlayerNumber} +Variable | Fungus.Variable | Variable to read the value from. Only Boolean, Integer, Float and String are supported. + +## Set Save Profile +Sets the active profile that the Save Variable and Load Variable commands will use. This is useful to crete multiple player save games. Once set, the profile applies across all Flowcharts and will also persist across scene loads. + +Property | Type | Description + --- | --- | --- +Save Profile Name | System.String | Name of save profile to make active. + +## Set Variable +Sets a Boolean, Integer, Float or String variable to a new value using a simple arithmetic operation. The value can be a constant or reference another variable of the same type. + +Property | Type | Description + --- | --- | --- +Variable | Fungus.Variable | The variable whos value will be set +Set Operator | Fungus.SetVariable+SetOperator | The type of math operation to be performed +Boolean Data | Fungus.BooleanData | Boolean value to set with +Integer Data | Fungus.IntegerData | Integer value to set with +Float Data | Fungus.FloatData | Float value to set with +String Data | Fungus.StringDataMulti | String value to set with + diff --git a/Docs/conduct/index.md b/Docs/conduct/index.md new file mode 100644 index 00000000..8fc7abe6 --- /dev/null +++ b/Docs/conduct/index.md @@ -0,0 +1,32 @@ +# TL;DR +Be nice to each other :) + +# Code of conduct +We want an open and respectful community at Fungus. So we would ask you when communicating (for example, posting on our Forums, Comments or github repository ) to be friendly and helpful. We find, for most people, this is not a problem. Our list of guidelines below is not exhaustive but should give a strong indication of what we consider acceptable community behaviour. + +## Be welcoming +We welcome and support people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability. + +## Be respectful +It's ok to disagree with someone. It's not ok to personally attack someone. Instead, focus on helping to resolve issues and learning from mistakes. + +Bullying or Harassment will not be tolerated +The following behaviours are not acceptable: + +- Violent threats or language directed against another person. +- Sexist, racist, or otherwise discriminatory jokes and language. +- Posting sexually explicit or violent material. +- Posting (or threatening to post) other people's personally identifying information ("doxing"). +- Sharing private content, such as emails sent privately or non-publicly, or unlogged forums such as IRC channel history. +- Personal insults, especially those using racist or sexist terms. +- Unwelcome sexual attention. +- Excessive or unnecessary profanity. +- Repeated harassment of others. In general, if someone asks you to stop, then stop. +- Advocating for, or encouraging, any of the above behaviour. + +## Assume Good Intentions +Give people the benefit of the doubt. If you believe they have acted against the code of conduct, please refer them to this document. Remember, although English is the primary language of Fungus development, that not all members have English as their primary language. + +Thanks to [http://www.apache.org/foundation/policies/conduct.html](http://www.apache.org/foundation/policies/conduct.html) and [https://www.djangoproject.com/conduct](https://www.djangoproject.com/conduct) for inspiration and content. + +If you have any questions about these guidelines please contact us. \ No newline at end of file diff --git a/Docs/conversation/index.md b/Docs/conversation/index.md new file mode 100644 index 00000000..09977463 --- /dev/null +++ b/Docs/conversation/index.md @@ -0,0 +1,66 @@ +# The Conversation system {#conversation} + +The Say and Portrait commands are a powerful way to build character dialogue, but it can be tedious to add large amounts of dialogue this way. + +The Conversation system provides a simplified format that allows you to quickly control: + +- Which character is speaking +- Which portrait image to use (either on the Say Dialog or on the Stage portrait) +- Which stage position to move to the character to (if using the Stage) +- When to hide a character + +To create a conversation, add the Conversation command (Narrative > Conversation) to a Block and enter the conversation text. + +# Example + +```text +john bored left: Oh, so that's how you use the Conversation command. +sherlock eyeroll right: Yes, well done John. +You catch on quickly don't you? +hide john "offscreen left": I sure do. + +-- This is a comment, it doesn't appear in the conversation + +john angry middle: Wait, what! +left: There's no need to be rude Sherlock! +bored: Not like that would stop you. + +sherlock excited: AHA! So that's how you do a conversation from Lua! +Fascinating. +john: Yes, riveting. + +john hide: +sherlock hide: +``` + +# Format + +The format for conversation text is: +```text +[character] [portrait] [position] [hide] : [Dialogue text] +``` + +- character: The gameobject name or Name Text value of the speaking character. +- portrait: The name of a sprite in the character's Portraits list. +- position: The name of a position object in the Stage (e.g. Left, Middle, Right, Offscreen Left, Offscreen Right) +- hide: Hides the character + +Parameters go on the left of the colon and the dialogue text goes on the right. You can omit any parameter and specify them in any order. Parameters are separated by spaces. If you need to use a name which contains spaces, wrap it in quotation marks e.g. "John Watson". Parameters are case insensitive. Blank lines and comment lines starting with -- are ignored. A line of dialogue text on its own will be spoken by the most recent character. You can omit dialogue text, but remember you still need to add the : character at the end of the line. + +# String substitution + +You can use the normal string subsitution syntax {$VarName} anywhere in the conversation text. For example if you have a string Flowchart variable called PlayerName you can embed this in a conversation like this: + +```text +john: Hi there {$PlayerName}. +``` + +# Localization + +You can use the string substitution feature above with a [Lua string table](../fungus_lua/string_table.md) to localize the conversation for multiple languages. + +The Conversation system does not work with the Localization component in Fungus because the syntax makes it difficult to localize that way. + +# Lua + +The conversation system can also be used [from Lua](../fungus_lua/controlling_fungus.md#conversation-function). diff --git a/Docs/download/images/001_install/0_asset_store.png b/Docs/download/images/001_install/0_asset_store.png new file mode 100644 index 00000000..84e321c8 Binary files /dev/null and b/Docs/download/images/001_install/0_asset_store.png differ diff --git a/Docs/download/images/001_install/1_unityimport.png b/Docs/download/images/001_install/1_unityimport.png new file mode 100644 index 00000000..b6168b39 Binary files /dev/null and b/Docs/download/images/001_install/1_unityimport.png differ diff --git a/Docs/download/images/001_install/2_packagecontents.png b/Docs/download/images/001_install/2_packagecontents.png new file mode 100644 index 00000000..8f41a690 Binary files /dev/null and b/Docs/download/images/001_install/2_packagecontents.png differ diff --git a/Docs/download/images/001_install/3_fungusproject.png b/Docs/download/images/001_install/3_fungusproject.png new file mode 100644 index 00000000..b926cb38 Binary files /dev/null and b/Docs/download/images/001_install/3_fungusproject.png differ diff --git a/Docs/download/images/001_install/4_downloads.png b/Docs/download/images/001_install/4_downloads.png new file mode 100644 index 00000000..f21872cf Binary files /dev/null and b/Docs/download/images/001_install/4_downloads.png differ diff --git a/Docs/download/images/001_install/5_assetstore_package.png b/Docs/download/images/001_install/5_assetstore_package.png new file mode 100644 index 00000000..0593feb0 Binary files /dev/null and b/Docs/download/images/001_install/5_assetstore_package.png differ diff --git a/Docs/download/images/001_install/6_asset_store_details.png b/Docs/download/images/001_install/6_asset_store_details.png new file mode 100644 index 00000000..4ef6e1df Binary files /dev/null and b/Docs/download/images/001_install/6_asset_store_details.png differ diff --git a/Docs/download/index.md b/Docs/download/index.md new file mode 100644 index 00000000..9ad66c66 --- /dev/null +++ b/Docs/download/index.md @@ -0,0 +1,52 @@ +# Download {#download} + +This page desribes how to download and install Unity and Fungus. + +# Video Tutorial + + + +# How do I install Fungus? + +1. Install the latest version of [Unity](http://unity3D.com/get-unity). +3. Launch Unity and create a new Project by selecting File > New Project. +4. Select 'Use Defaults for 2D' when creating the new project. + +To install Fungus from the Asset Store (recommended): + +1. Open the Asset Store window in Unity +2. Search for Fungus, or use [this link](http://u3d.as/f0T) +3. Download and import Fungus to your project using the Asset Store window. + +To install Fungus from the latest release on Github: + +1. Download the latest Fungus .unitypackage from [Github](https://github.com/FungusGames/Fungus/releases/latest) +2. Import Fungus into the new project by selecting Assets > Import Package > Custom Package. + +First steps: + +1. Display the Flowchart editor window by selecting Window > Tools > Fungus > Flowchart Window. +2. For convenience, you should dock the Flowchart window somewhere in the editor window. +3. In the project window, open The Hunter example scene (FungusExamples > TheHunter > TheHunter.unity). +4. Press play and click through the example game. + +Try playing the other example scenes and watch how the gameplay is controlled by the flowchart in the Fungus Script window. + +# How do I upgrade an existing Fungus project ? + +To upgrade an existing project to the latest version of Fungus. + +1. Take a backup of your project. No really, do it! +2. We recommend updating to the latest version of [Unity](http://unity3D.com/get-unity). +3. Delete the Fungus and FungusExamples folders from your project. +4. Download and import the latest version of Fungus. + +We try to maintain backwards compatibility between releases but sometimes breaking changes are necessary. If you're having trouble upgrading your project just ask for assistance on the forum. + +# Fungus System Requirements + +- We recommend installing the latest version of Unity 3D. +- Fungus requires at least Unity 5.0 and is not compatible with Unity 4.x or earlier. +- Fungus works with both the PC & Mac versions of Unity +- Fungus works with both the free Personal and Professional editions of Unity +- Official Unity list of system requirements [available here](http://unity3d.com/unity/system-requirements). \ No newline at end of file diff --git a/Docs/event_handlers/core_events.md b/Docs/event_handlers/core_events.md new file mode 100644 index 00000000..6fcb67c2 --- /dev/null +++ b/Docs/event_handlers/core_events.md @@ -0,0 +1,11 @@ +## Flowchart Enabled +The block will execute when the Flowchart game object is enabled. +## Game Started +The block will execute when the game starts playing. +## Message Received +The block will execute when the specified message is received from a Send Message command. + +Property | Type | Description + --- | --- | --- +Message | System.String | Fungus message to listen for + diff --git a/Docs/event_handlers/input_events.md b/Docs/event_handlers/input_events.md new file mode 100644 index 00000000..ed4f78c5 --- /dev/null +++ b/Docs/event_handlers/input_events.md @@ -0,0 +1,8 @@ +## Key Pressed +The block will execute when a key press event occurs. + +Property | Type | Description + --- | --- | --- +Key Press Type | Fungus.KeyPressed+KeyPressType | The type of keypress to activate on +Key Code | UnityEngine.KeyCode | Keycode of the key to activate on + diff --git a/Docs/event_handlers/sprite_events.md b/Docs/event_handlers/sprite_events.md new file mode 100644 index 00000000..b5c0bab4 --- /dev/null +++ b/Docs/event_handlers/sprite_events.md @@ -0,0 +1,40 @@ +## Drag Cancelled +The block will execute when the player drags an object and releases it without dropping it on a target object. + +Property | Type | Description + --- | --- | --- +Draggable Object | Fungus.Draggable2D | Draggable object to listen for drag events on + +## Drag Completed +The block will execute when the player drags an object and successfully drops it on a target object. + +Property | Type | Description + --- | --- | --- +Draggable Object | Fungus.Draggable2D | Draggable object to listen for drag events on +Target Object | UnityEngine.Collider2D | Drag target object to listen for drag events on + +## Drag Entered +The block will execute when the player is dragging an object which starts touching the target object. + +Property | Type | Description + --- | --- | --- +Draggable Object | Fungus.Draggable2D | Draggable object to listen for drag events on +Target Object | UnityEngine.Collider2D | Drag target object to listen for drag events on + +## Drag Exited +The block will execute when the player is dragging an object which stops touching the target object. + +Property | Type | Description + --- | --- | --- +Draggable Object | Fungus.Draggable2D | Draggable object to listen for drag events on +Target Object | UnityEngine.Collider2D | Drag target object to listen for drag events on + +## Drag Started +The block will execute when the player starts dragging an object. +## Object Clicked +The block will execute when the user clicks or taps on the clickable object. + +Property | Type | Description + --- | --- | --- +Clickable Object | Fungus.Clickable2D | Object that the user can click or tap on + diff --git a/Docs/event_handlers/ui_events.md b/Docs/event_handlers/ui_events.md new file mode 100644 index 00000000..15813283 --- /dev/null +++ b/Docs/event_handlers/ui_events.md @@ -0,0 +1,14 @@ +## Button Clicked +The block will execute when the user clicks on the target UI button object. + +Property | Type | Description + --- | --- | --- +Target Button | UnityEngine.UI.Button | The UI Button that the user can click on + +## End Edit +The block will execute when the user finishes editing the text in the input field. + +Property | Type | Description + --- | --- | --- +Target Input Field | UnityEngine.UI.InputField | The UI Input Field that the user can enter text into + diff --git a/Docs/faq/index.md b/Docs/faq/index.md new file mode 100644 index 00000000..6300d8cf --- /dev/null +++ b/Docs/faq/index.md @@ -0,0 +1,58 @@ +# Frequently Asked Questions {#faq} + +## What is Fungus ? +Fungus is a free open source tool for creating storytelling games, with a strong focus on accessibility for novice game developers. Users all over the world are now using it to create a wonderfully diverse range of storytelling games. + +## Who makes Fungus ? +Fungus is developed by [Snozbot](http://snozbot.com), a small independent games company. Chris Gregan is the main developer of Fungus. + +## Where do I get Fungus ? +Fungus is available on the [Unity Asset Store](http://u3d.as/f0T) and in the download section of this website. + +## Is Fungus really free to use? +Yes. Fungus has an Open Source M.I.T. license. You can use Fungus with any version of the Unity game engine, including the freely available personal edition. + +## Can I sell the apps I make with Fungus ? +Yes. We do not charge a license fee. + +## What platforms does Fungus support ? +Fungus runs on any platform supported by the Unity game engine. See here for a list of supported platforms. + +## Do I need to be a programmer to use Fungus ? +No. Fungus can be used to make a variety of story-driven games with no coding required. + +## Is Fungus useful for programmers ? +Yes. Fungus provides an easy way to add visual novel features to any Unity game. It is also possible to extend Fungus to customise the workflow for your team. Checkout the documentation and tutorials for more information. + +## Where can I learn more about Fungus ? +We provide extensive tutorials and documentation on our website here. There is also a comprehensive online training course suitable for beginners at Udemy. + +## I've made something cool with Fungus. Wanna see? +Most definitely! Please tweet @gofungus and/or post an item in the announcements section of our forum. + +## How can I upload my Fungus game for others to see? +After creating a build, you can use a hosting service such as [itch.io](http://itch.io), [gamejolt.com](http://gamejolt.com) or [newgrounds.com](http://newgrounds.com) + +## How can I suggest new features for Fungus ? +Please use the forum to request new features. You can also checkout our github issues list to see what we have planned. + +## How do I report a bug in Fungus? +Please use the forum to report bugs. + +## How long will I have to wait for a bug-fix ? +If a bug is critical and we can't offer a sensible workaround, we will try to fix it as soon as possible. Otherwise, we will aim to fix the issue in the next release. + +## Can I get my hands on beta versions of Fungus ? +The very latest version is always available at our [github repository](https://github.com/snozbot/fungus) + +## How can I contribute to Fungus? +There are lots of ways to help the Fungus community to grow + +1. Answer questions and post tips on the forum +2. Contribute code either via a Github pull request or post code snippets in the forums. +3. Improve the documentation by editing the [fungus-site repo](https://github.com/snozbot/fungus-site) and send in a pull request. +4. Let us know on the forum if you've made a game with Fungus so we can add it to the site. +5. If you write an article, blog post, podcast, etc. about Fungus send it in and we'll add it to the [community articles](../articles/index.md) section. + +## Are you planning to integrate Fungus into other game engines ? +Not currently. We're sticking with Unity for the foreseeable future. \ No newline at end of file diff --git a/Docs/flowcharts/images/001_what_is/1_example_flowchart.png b/Docs/flowcharts/images/001_what_is/1_example_flowchart.png new file mode 100644 index 00000000..a77c8796 Binary files /dev/null and b/Docs/flowcharts/images/001_what_is/1_example_flowchart.png differ diff --git a/Docs/flowcharts/images/002_docking/1_menu.png b/Docs/flowcharts/images/002_docking/1_menu.png new file mode 100644 index 00000000..00462ddb Binary files /dev/null and b/Docs/flowcharts/images/002_docking/1_menu.png differ diff --git a/Docs/flowcharts/images/002_docking/2_window copy.png b/Docs/flowcharts/images/002_docking/2_window copy.png new file mode 100644 index 00000000..c9793eb5 Binary files /dev/null and b/Docs/flowcharts/images/002_docking/2_window copy.png differ diff --git a/Docs/flowcharts/images/002_docking/2_window.png b/Docs/flowcharts/images/002_docking/2_window.png new file mode 100644 index 00000000..61d7918e Binary files /dev/null and b/Docs/flowcharts/images/002_docking/2_window.png differ diff --git a/Docs/flowcharts/images/002_docking/3_docked.png b/Docs/flowcharts/images/002_docking/3_docked.png new file mode 100644 index 00000000..2b84fa20 Binary files /dev/null and b/Docs/flowcharts/images/002_docking/3_docked.png differ diff --git a/Docs/flowcharts/images/003_panning/1_pan1.png b/Docs/flowcharts/images/003_panning/1_pan1.png new file mode 100644 index 00000000..65cd1b51 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/1_pan1.png differ diff --git a/Docs/flowcharts/images/003_panning/2_pan2.png b/Docs/flowcharts/images/003_panning/2_pan2.png new file mode 100644 index 00000000..bece1516 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/2_pan2.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.24.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.24.png new file mode 100644 index 00000000..0de3df88 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.24.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.25.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.25.png new file mode 100644 index 00000000..b3cc6466 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.25.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.27.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.27.png new file mode 100644 index 00000000..a5d09d36 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.27.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.28.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.28.png new file mode 100644 index 00000000..b27f2be3 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.28.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.29.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.29.png new file mode 100644 index 00000000..efba0cc4 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.29.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.30.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.30.png new file mode 100644 index 00000000..cbc56f32 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.30.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.31.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.31.png new file mode 100644 index 00000000..d885edf7 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.31.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.32.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.32.png new file mode 100644 index 00000000..8cdb65e4 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.32.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.34.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.34.png new file mode 100644 index 00000000..098846d7 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.34.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.35.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.35.png new file mode 100644 index 00000000..6b319aa1 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.35.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.36.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.36.png new file mode 100644 index 00000000..6cdb22f4 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.36.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.38.png b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.38.png new file mode 100644 index 00000000..24b56ca1 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/Screen Shot 2015-06-11 at 12.39.38.png differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/animated_drag_to_pan.psd b/Docs/flowcharts/images/003_panning/GIFs/animated_drag_to_pan.psd new file mode 100644 index 00000000..503f1225 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/animated_drag_to_pan.psd differ diff --git a/Docs/flowcharts/images/003_panning/GIFs/start.png b/Docs/flowcharts/images/003_panning/GIFs/start.png new file mode 100644 index 00000000..31f30540 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/GIFs/start.png differ diff --git a/Docs/flowcharts/images/003_panning/animated_drag_to_pan.gif b/Docs/flowcharts/images/003_panning/animated_drag_to_pan.gif new file mode 100644 index 00000000..2d947977 Binary files /dev/null and b/Docs/flowcharts/images/003_panning/animated_drag_to_pan.gif differ diff --git a/Docs/flowcharts/images/004_zooming/1_zoom1.png b/Docs/flowcharts/images/004_zooming/1_zoom1.png new file mode 100644 index 00000000..13003f44 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/1_zoom1.png differ diff --git a/Docs/flowcharts/images/004_zooming/2_zoom2.png b/Docs/flowcharts/images/004_zooming/2_zoom2.png new file mode 100644 index 00000000..31e017fd Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/2_zoom2.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.19.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.19.png new file mode 100644 index 00000000..fddcba63 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.19.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.24.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.24.png new file mode 100644 index 00000000..fddcba63 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.24.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.30.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.30.png new file mode 100644 index 00000000..8d60043e Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.30.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.33.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.33.png new file mode 100644 index 00000000..0153247a Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.33.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.34.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.34.png new file mode 100644 index 00000000..30bcd35c Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.34.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.35.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.35.png new file mode 100644 index 00000000..b6b10a69 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.35.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.36.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.36.png new file mode 100644 index 00000000..8135c989 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.36.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.37.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.37.png new file mode 100644 index 00000000..93e75e70 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.37.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.38.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.38.png new file mode 100644 index 00000000..f797131c Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.38.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.39.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.39.png new file mode 100644 index 00000000..e33a2705 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.39.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.40.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.40.png new file mode 100644 index 00000000..f14d8eb8 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.40.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.41.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.41.png new file mode 100644 index 00000000..6d0b4378 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.41.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.43.png b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.43.png new file mode 100644 index 00000000..60065e38 Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/Screen Shot 2015-06-11 at 13.07.43.png differ diff --git a/Docs/flowcharts/images/004_zooming/GIFs/animated_zoom.psd b/Docs/flowcharts/images/004_zooming/GIFs/animated_zoom.psd new file mode 100644 index 00000000..31e3e04e Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/GIFs/animated_zoom.psd differ diff --git a/Docs/flowcharts/images/004_zooming/animated_zoom.gif b/Docs/flowcharts/images/004_zooming/animated_zoom.gif new file mode 100644 index 00000000..5b43df7a Binary files /dev/null and b/Docs/flowcharts/images/004_zooming/animated_zoom.gif differ diff --git a/Docs/flowcharts/images/005_create_flowchart/1_tools_create.png b/Docs/flowcharts/images/005_create_flowchart/1_tools_create.png new file mode 100644 index 00000000..8b39aa1e Binary files /dev/null and b/Docs/flowcharts/images/005_create_flowchart/1_tools_create.png differ diff --git a/Docs/flowcharts/images/005_create_flowchart/2_flowchart_gameobject.png b/Docs/flowcharts/images/005_create_flowchart/2_flowchart_gameobject.png new file mode 100644 index 00000000..12ce2cf3 Binary files /dev/null and b/Docs/flowcharts/images/005_create_flowchart/2_flowchart_gameobject.png differ diff --git a/Docs/flowcharts/images/005_create_flowchart/3_flowchart_properties copy.png b/Docs/flowcharts/images/005_create_flowchart/3_flowchart_properties copy.png new file mode 100644 index 00000000..2031827e Binary files /dev/null and b/Docs/flowcharts/images/005_create_flowchart/3_flowchart_properties copy.png differ diff --git a/Docs/flowcharts/images/005_create_flowchart/3_flowchart_properties.png b/Docs/flowcharts/images/005_create_flowchart/3_flowchart_properties.png new file mode 100644 index 00000000..0a03f271 Binary files /dev/null and b/Docs/flowcharts/images/005_create_flowchart/3_flowchart_properties.png differ diff --git a/Docs/flowcharts/index.md b/Docs/flowcharts/index.md new file mode 100644 index 00000000..ecd93164 --- /dev/null +++ b/Docs/flowcharts/index.md @@ -0,0 +1,82 @@ +# Flowcharts {#flowcharts} + +A fundamental concept of Fungus is the **Flowchart**. Scenes can contain a single Flowchart or multiple Flowcharts. + + +## What is a Flowchart? + +A Fungus **Flowchart** contains the Blocks in which all your Fungus Commands are located. A Unity scene can contain multiple Flowcharts, and commands can be executing simultaneously in different Flowcharts. However, for many games it is sufficient for one Block in one Flowcart to be executing at any one time. + +Here is an example of a Fungus Flowchart: +
+![flowchart example](./images/001_what_is/1_example_flowchart.png "flowchart example") +
+ + + +## Opening and docking the Flowchart window +You'll need the Fungus Flowchart window when working with Fungus. Open and dock this window somewhere handy by following these steps: + +1. Choose menu: ``Tools | Fungus | Flowchart Window`` +
+![Menu open Fungus window](./images/002_docking/1_menu.png "Menu open Fungus window") +
+
+ +2. Drag-and-drop the Flowchart window to the location you wish to dock it: +
+![Drag Fungus window](./images/002_docking/2_window.png "Drag Fungus window") +
+
+ +3. The Flowchart window is now docked and part of your Unity window layout: +
+![Docked Fungus window](./images/002_docking/3_docked.png "Docked Fungus window") + + + +## Creating a Flowchart +To create a Fungus Flowchart do the following: + +1. Choose menu: ```Tools | Fungus | Create Flowchart``` +
+![menu create Flowchart](./images/005_create_flowchart/1_tools_create.png "menu create Flowchart") +
+
+ +2. A new **Flowchart** gameObject should appear in the Hierarchy window. +
+![new Flowchart gameobject](./images/005_create_flowchart/2_flowchart_gameobject.png "new Flowchart gameobject") +
+
+ +3. Select the **Flowchart** gameObject in the Hierarchy window, and you'll see the **Flowchart's** properties in the Inspector Window: +
+![Flowchart properties](./images/005_create_flowchart/3_flowchart_properties.png "Flowchart properties") +
+
+ +4. If you have not already displayed the Flowchart Window, you can do so by clicking the Flowchart Window button in the Inspector. + +5. As you can see, when a new Flowchat is created a single command Block named "New Block" is automatically created, with the Event handler "Game Started" (so it will start executing Fungus commands as soon as the scene goes into **Play Mode**). + + +## Panning the Flowchart window +Panning means moving the contents of the Flowchart window as if they are on a piece of paper. Click and drag with the RIGHT mouse button to pan the contents of the Flowchart window. + +![pan flowchart 1](./images/003_panning/1_pan1.png "pan flowchart 1") + +![pan flowchart 2](./images/003_panning/2_pan2.png "pan flowchart 2") + +![pan flowchart animated](./images/003_panning/animated_drag_to_pan.gif "pan flowchart animated") + + + +## Zooming the Flowchart window +Zooming refers to making the contents larger or smaller. To zoom the Flowchart window contents either click and drag the UI slider, or use the mouse wheel (or trackpad). + +![zoom flowchart 1](./images/004_zooming/1_zoom1.png "zoom flowchart 1") + +![zoom flowchart 2](./images/004_zooming/2_zoom2.png "zoom flowchart 2") + +![zoom flowchart 2](./images/004_zooming/animated_zoom.gif "zoom flowchart animated") diff --git a/Docs/forum/index.md b/Docs/forum/index.md new file mode 100644 index 00000000..e9c44c4a --- /dev/null +++ b/Docs/forum/index.md @@ -0,0 +1,9 @@ + +## Welcome +We aim to help everybody who's using Fungus, no matter what your experience level. If you're stuck just ask! + +## Code of conduct +We would ask that all users of the community forum respect our [code of conduct](../conduct/index.md). + +fungus + diff --git a/Docs/fungus_lua/controlling_fungus.md b/Docs/fungus_lua/controlling_fungus.md new file mode 100644 index 00000000..edee75d7 --- /dev/null +++ b/Docs/fungus_lua/controlling_fungus.md @@ -0,0 +1,266 @@ +# Controlling Fungus + +The Fungus module provides several functions for working with the standard Fungus narrative features and flowcharts. + +You can control Say and Menu dialogs in much the same way you use Say and Menu commands in a normal Fungus flowchart. + +When you use the menu() function, you supply another Lua function to call when that menu option is selected. Make sure to define the function higher up in the file before referencing it in a menu() call. If you don't explicitly set a SayDialog or MenuDialog object to use default ones are created automatically. + +# Narrative example + +This example Lua script demonstrates some of the Say and Menu dialog functions. To try it out, add a Lua object to the scene (Tools > Fungus > Create > Lua) and copy this script into the Lua Script text box. You may also need to add an EventSystem object in the scene (GameObject > UI > Event System) so that the menu buttons will respond to user input. + +```lua +-- Display text in a SayDialog +say("Hi there") +say "This syntax also works for say commands" + +-- Display a list of options in a MenuDialog +-- (Note the curly braces here!) +local choice = choose{ "Go left", "Go right" } + +if choice == 1 then + say("You chose left") +elseif choice == 2 then + say("You chose right") +end +``` + +Note: The curly braces syntax means that the list of options is passed as a single table parameter to the choose() function. It's a shortcut for writing this: +```lua +local choice = choose( {"Go left", "Go right"} ) +``` + +# Say Dialog functions + +To use a custom SayDialog: + +1. Add as SayDialog to the scene (Tools > Fungus > Create > SayDialog) +2. Select the Lua object in the hierarchy and find the LuaBindings component. +3. Add a binding to the SayDialog game object, and select the SayDialog component. N.B. Make sure to select the correct component! +4. In Lua script, you can now activate this SayDialog using the setsaydialog() function, by passing the key of the SayDialog binding. + +To change the behaviour of the say() function, e.g. to not wait for input when done, do this: +```lua +sayoptions.waitforinput = false +``` + +You can bind Character objects in a similar fashion, and set the speaking character using the setcharacter() function. + +This is the list of available functions for controlling SayDialogs. + +```lua +-- Options for configuring Say Dialog behaviour +sayoptions.clearprevious = true | false +sayoptions.waitforinput = true | false +sayoptions.fadewhendone = true | false +sayoptions.stopvoiceover = true | false + +-- Set the active saydialog to use with the say function +-- saydialog: A binding to a SayDialog component +setsaydialog(saydialog) + +-- Gets the active say dialog, or creates one if none exists yet +getsaydialog() + +-- Set the active character on the Say Dialog +-- character: A Fungus.Character component +-- portrait: The name of a sprite in the character's portrait list +setcharacter(character, portrait) + +-- Write text to the active Say Dialog +-- text: A string to write to the say dialog +-- voice: A voiceover audioclip to play +say(text, voiceclip) +``` + +# Menu Dialog functions + +You setup custom MenuDialogs in the same manner as SayDialogs, use the setmenudialog() function to set the active MenuDialog. + +The easiest way to display a list of options is using the choose() function. Remember that in Lua array indices start at 1 instead of 0 like in most other languages. + +You can set an option to be displayed but not selectable by prepending it with the ~ character. + +```lua +local choice = choose { "Option 1", "Option 2", "~Option 3" } + +if choice == 1 then + say "Chose option 1" +elseif choice == 2 then + say "Chose option 2" +end +-- Option 3 is displayed but can't be selected + +say "End options" +``` + +A useful pattern is to use choose() together with Lua's goto statement and labels. This can be handy for 'flattening out' nested menu options. The [goto statement](http://lua-users.org/wiki/GotoStatement) doesn't support jumping into the scope of a local variable, but it's easy to work around this by declaring the local variable in the outer scope. You could also use a global variable (by not using the local keyword). + +```lua +local choice = 0 + +choice = choose { "Option A", "Option B" } +if choice == 1 then goto optionA end +if choice == 2 then goto optionB end + +::optionA:: +say "Chose option A" +goto endoptions + +::optionB:: +choice = choose { "Option C", "Option D" } +if choice == 1 then goto optionC end +if choice == 2 then goto optionD end +goto endoptions + +::optionC:: +say "Chose option C" +goto endoptions + +::optionD:: +say "Chose option D" +goto endoptions + +::endoptions:: +say "End options" +``` + +The menu() and menutimer() functions provide an alternative way to use the MenuDialog. These functions return immediately, and a callback function is called when the player selects an option from the menu. + +This is the list of available MenuDialog functions. + +```lua +-- Set the active menudialog to use with the menu function +setmenudialog(menudialog) + +-- Gets the active menu dialog, or creates one if none exists yet +getmenudialog() + +-- Display a list of menu options and wait for user to choose one. +-- When an option starts with the ~ character it will be displayed but not be selectable. +-- Returns the index of the selected option. +-- Returns 0 if options list is empty. Note: Lua array indices start at 1, not 0). +-- options: an array of option strings. e.g. { "Option 1", "Option 2" } +choose(options) + +-- Display a list of menu options and wait for user to choose one, or for a timer to expire. +-- When an option starts with the ~ character it will be displayed but not be selectable. +-- Returns the index of the selected option, or the defaultoption if the timer expires. +-- Returns 0 if options list is empty. Note: Lua array indices start at 1, not 0). +-- options: an array of option strings. e.g. { "Option 1", "Option 2" } +-- duration: Time player has to pick an option. +-- defaultoption: Option index to return if the timer expires. +choosetimer(options, duration, defaultoption) + +-- Display a menu button +-- text: text to display on the button +-- callback: function to call when this option is selected +-- interactive (optional): if false, displays the option as disabled +menu(text, callback, interactive) + +-- Display a timer during which the player has to choose an option. +-- duration: The length of time to display the timer. +-- callback: Function to call if the timer expires before an option is selected. +menutimer(duration, callback) + +-- Clear all currently displayed menu options +clearmenu() +``` + +# Portrait functions + +Stage portraits can be controlled by using the stage. + +First, add your characters and stage to the LuaBindings list. + +![Lua Stage Binding](images/lua_stage_binding.png) + +Then, in a lua script, use the stage commands show, showPortrait and hide to control the portraits on stage. + +```lua +-- Show a character at this stage position +stage.show(character, "left") + +-- show a character with a specific portrait and move it +-- from one stage position to another. +stage.show(character, "happy", "offscreen right", "right") + +-- show a specific portrait +stage.showPortrait(character, "amused") + +-- hide a character +stage.hide(character) + +-- Hide a character fading out to a position +stage.hide(character, "offscreen left") +``` +You can also specify any Portrait option available by using named arguments. + +```lua +stage.show{character=character, fromPosition="left", toPosition="right"} + +stage.show{character=character, portrait="angry"} + +stage.hide{character=character} +``` + +# Conversation function + +The conversation() function allows you to perform long dialogue exchanges with a single function call. Lua's multiline string syntax [[ ]] is handy here. As the conversation() function takes a single string parameter you can also omit the usual function parentheses. + +```text +conversation [[ +john: Hello! +sherlock: Greetings. +]] +``` + +The conversation system is [documented here](../conversation/index.html#lua). + +# Flowchart functions + +We've added special functions for say() and menu() because these are so common in Fungus games. To execute any other commands in Fungus from Lua, you must do it in conjunction with a Flowchart & Block, like this: + +1. Add a Flowchart and a Block (e.g. "MyBlock") in the scene. +2. Add the Fungus commands you want to execute from Lua in the Block. (e.g Play Sound) +3. Add a Lua object to the scene (Tools > Fungus > Create > Lua) +4. In the LuaBindings component, add a binding to the Flowchart gameobject, and select the Flowchart component. +5. In the LuaScript component, use the runblock() function to execute the Block, passing the bound flowchart and name of the block as parameters. + +```lua +runblock(flowchart, "MyBlock") +``` + +You can also access any Flowchart variable from Lua via the getvar() function. + +```lua +-- Assume the 'flowchart' variable is bound to a Flowchart component in LuaBindings +-- MyVar is a string variable defined on the Flowchart + +local myvar = getvar(flowchart, "MyVar") + +print(myvar.value) + +myvar.value = "New value for string" +``` + +This is the list of available functions for controlling Flowcharts. + +```lua +-- Returns the specified Variable in a Flowchart. +-- To access the value of the variable, use its .value property. e.g. +-- v = getvar(flowchart, "FloatVar") +-- v.value = 10 -- Sets the value of the variable to 10 +-- f = v.value -- f now contains 10 +-- flowchart: The Fungus Flowchart containing the Block to run. +-- varname: The name of the Variable to get. +getvar(flowchart, varname) + +-- Runs the specified Block in a Flowchart +-- flowchart: The Fungus Flowchart containing the Block to run. +-- blockname: The name of the Block to run. +-- commandindex: Index of the command to start execution at +-- nowait: If false, will yield until the Block finishes execution. If true will continue immediately. +runblock(flowchart, blockname, commandindex, nowait) +``` diff --git a/Docs/fungus_lua/create_menu.md b/Docs/fungus_lua/create_menu.md new file mode 100644 index 00000000..264f7175 --- /dev/null +++ b/Docs/fungus_lua/create_menu.md @@ -0,0 +1,41 @@ +# The Create Menu + +The easiest way to add Lua scripting to your scene is via the Tools > Fungus > Create menu. This allows you to quickly instantiate one of the Lua prefabs that comes with FungusLua. The FungusLua prefabs all begin with 'Lua'. + +You can also access these prefabs from Fungus/Thirdparty/FungusLua/Resources/Prefabs. + +![Fungus Create Menu](images/create_menu.png) + +# Lua Prefab + +This prefab provides a complete Lua setup, including the [LuaEnvironment](lua_environment.md), [LuaUtils](lua_utils.md), [LuaBindings](lua_bindings.md) and [LuaScript](lua_script.md) components in a single game object. + +This is perfect when you want to quickly set up a single script with a few bindings. If you're learning FungusLua, use the Lua object until you're comfortable with how all these components work. + +For more sophisticated scenarios it can be better to place these components in different game objects, e.g. one LuaEnvironment object, one LuaBindings object and multiple LuaScript objects that share the environment and bindings. The other prefab types listed below make it easy to set up this kind of configuration. + +# Lua File + +This option creates a Lua file in the folder you select. In Unity, Lua files use the .txt extension so they work properly with TextAsset properties and can be opened in the code editor. + +When you create a Lua file, add your Lua script to it in a text editor, and then select the file in the Lua File property of a LuaScript component or Execute Lua command to execute it. You can also use Lua's [module system](lua_script.md#lua-modules-and-require) and the require() function to include Lua code from other files. + +# Lua Environment Prefab + +This prefab provides a [LuaEnvironment]((lua_environment.md)) component for executing Lua script, and the [LuaUtils](lua_utils.md) component which provides useful utilities for working with Lua, Unity and Fungus. + +FungusLua will automatically create a default LuaEnvironment if none exists when the scene starts, so you really only need to create a Lua Environment in your scene when you want to customize the default environment setup (e.g. Adding a string table file or registering additional c# types). + +# Lua Bindings Prefab + +This prefab provides a [LuaBindings](lua_bindings.md) component which you can use to bind objects in your scene / project to Lua variables so they can be accessed from Lua script. You can have multiple Lua Bindings in a scene, or additively load in a scene which contains a Lua Bindings for objects in that scene. At startup, all loaded Lua Bindings register their bindings with every Lua Environment in the scene (unless the All Environments option is switched off). + +If you want to make a prefab using Lua Bindings, all the bound objects must be children of the Lua Bindings prefab in the hierarchy so that Unity can maintain the object references correctly. This is a limitation of how Unity works. + +# Lua Script Prefab + +This prefab contains a [Lua Script](lua_script.md) component which you can use to execute Lua script, either typed in the inspector window or loaded via a text file. It also contains an Execute Handler component which supports executing the Lua Script when a Unity event occurs (e.g. start, update, on enter trigger, etc.) + +# Lua Store Prefab + +This prefab contains a [Lua Store](lua_store.md) component which you can use to persist Lua variables between scene loads. diff --git a/Docs/fungus_lua/execute_lua.md b/Docs/fungus_lua/execute_lua.md new file mode 100644 index 00000000..2f045144 --- /dev/null +++ b/Docs/fungus_lua/execute_lua.md @@ -0,0 +1,36 @@ +# The ExecuteLua Command + +This command allows you to embed a Lua script to be executed as part of a command sequence in a Block. The Lua script to be executed can be specified in the inspector or in a text file, in the same way as in the [Lua Script component](lua_script.md#lua-script-and-files). + +You can provide an optional LuaEnvironment to use for the execution. If none is provided then a LuaEnvironment will be selected / created automatically. If a LuaEnvironment has been set on the parent Flowchart then that environment will be used by default. + +The parent Flowchart will be bound to a global Lua variable prior to executing the Lua script. By default the binding name is 'flowchart', but you can change it to anything you want via the Lua Binding Name property of the parent Flowchart. + +You can also store the return value from the Lua script in a Flowchart variable. + +# Evaluating expressions + +The Fungus If command can only compare 2 variables at a time. For more complex expressions involving multiple variables or [math functions](http://lua-users.org/wiki/MathLibraryTutorial), you can use Lua to evaluate the expression and store the result in a Flowchart variable. + +1. Add a Flowchart object (Tools > Fungus > Create > Flowchart). Add some variables to the Flowchart. +2. Add a LuaBindings object (Tools > Fungus > Create > LuaBindings) +3. Add a binding to the Flowchart gameobject, and select the Flowchart component. +4. In the Flowchart, add an ExecuteLua command in a block to evaluate the complex expression. Store the return value in a Boolean Flowchart variable. +5. Add an If command which checks the value of the Boolean variable. + +In the Execute Lua command, you can use the getvar() function to get any Flowchart variables to be used in the expression. +Note: getvar() returns a reference to the Fungus variable object. To access the value of this variable use the .value property. + +# Example + +Here's an example Lua script which evaluates a complex expression involving 3 integer variables defined on a bound Flowchart. + +```lua +local v1 = getvar(flowchart, "Var1") +local v2 = getvar(flowchart, "Var2") +local v3 = getvar(flowchart, "Var3") + +return (v1.value == v2.value or v3.value == 5) +``` + +Don't forget to use .value to access the value stored in the variable object, rather than the variable object itself! diff --git a/Docs/fungus_lua/fungus_module.md b/Docs/fungus_lua/fungus_module.md new file mode 100644 index 00000000..410b7c42 --- /dev/null +++ b/Docs/fungus_lua/fungus_module.md @@ -0,0 +1,61 @@ +# Fungus Module + +This Lua module provides handy functions for working with Lua, Unity and Fungus. + +In this page we cover some of the more generic functionality in the module, other major features are described elsewhere in the documentation. + +# Inspecting Lua objects + +You can use Lua's built in print() function to get a basic description of any object printed to the console. When you want to get a more detailed description of an object, use inspect(). + +```lua +-- Prints a short description of object v +print(v) + +-- Prints a summary of object v in a human readable format. +inspect(v) +``` + +# Running Unity coroutines + +When you bind to a C# component using Lua Bindings, you can access any public method in the class. If a method returns IEnumerator then that method can be executed [as a coroutine](http://docs.unity3d.com/Manual/Coroutines.html), which is a powerful way to run asynchronous code. + +The runwait() function allows you to call a C# coroutine method from Lua which may take multiple frames to finish its work, and then carry on with the rest of the Lua code once that C# method has finished executing. This is how the say() function works for example. + +This is the list of available functions for waiting and working with coroutines. + + +```lua +-- Waits for a number of seconds, then continue execution of Lua script +wait(duration) + +-- Waits until the Lua function provided returns true, or the timeout expires. +-- Returns true if the function succeeded, or false if the timeout expired +waitfor(fn, timeoutduration) + +-- Run a C# coroutine and continue execution of Lua script +run(co) + +-- Run a C# coroutine, wait until it completes, then continue execution of Lua script +runwait(co) +``` + +# Globals vs Table mode + +The Fungus module can be used in three modes, controlled by the Fungus Module option in the LuaUtils component. + +1. Use Global Variables: all module functions are mapped to global functions. This allows for convenient access, but it runs the risk that you might accidentally declare a variable with the same name as a Fungus module function. +2. Use Fungus Variable: all module functions are accessed through a global table called 'fungus'. This gives a degree of namespace safety at the cost of more typing. +3. No Fungus Module: the Fungus module will not be registered. Used if you don't want to use the Fungus module. + +Options 1 and 2 are functionaly equivalent, it's just a matter of personal preference which you want to use. + +```lua +-- sub is a function in the Fungus module, mapped to a global variable + +-- Use Global Variables +sub('a string') + +-- Use Fungus Variable +fungus.sub('a string') +``` \ No newline at end of file diff --git a/Docs/fungus_lua/images/create_menu.png b/Docs/fungus_lua/images/create_menu.png new file mode 100644 index 00000000..c0f4f9c5 Binary files /dev/null and b/Docs/fungus_lua/images/create_menu.png differ diff --git a/Docs/fungus_lua/images/lua.png b/Docs/fungus_lua/images/lua.png new file mode 100644 index 00000000..4bdf7a91 Binary files /dev/null and b/Docs/fungus_lua/images/lua.png differ diff --git a/Docs/fungus_lua/images/lua_bindings.png b/Docs/fungus_lua/images/lua_bindings.png new file mode 100644 index 00000000..95edec43 Binary files /dev/null and b/Docs/fungus_lua/images/lua_bindings.png differ diff --git a/Docs/fungus_lua/images/lua_environment.png b/Docs/fungus_lua/images/lua_environment.png new file mode 100644 index 00000000..97b131b8 Binary files /dev/null and b/Docs/fungus_lua/images/lua_environment.png differ diff --git a/Docs/fungus_lua/images/lua_script.png b/Docs/fungus_lua/images/lua_script.png new file mode 100644 index 00000000..a28e580d Binary files /dev/null and b/Docs/fungus_lua/images/lua_script.png differ diff --git a/Docs/fungus_lua/images/lua_stage_binding.png b/Docs/fungus_lua/images/lua_stage_binding.png new file mode 100644 index 00000000..ac24a9d9 Binary files /dev/null and b/Docs/fungus_lua/images/lua_stage_binding.png differ diff --git a/Docs/fungus_lua/images/moonsharp.png b/Docs/fungus_lua/images/moonsharp.png new file mode 100644 index 00000000..41574066 Binary files /dev/null and b/Docs/fungus_lua/images/moonsharp.png differ diff --git a/Docs/fungus_lua/index.md b/Docs/fungus_lua/index.md new file mode 100644 index 00000000..f85e4fa4 --- /dev/null +++ b/Docs/fungus_lua/index.md @@ -0,0 +1,40 @@ +# What is FungusLua? + +FungusLua is a simple way to embed Lua scripting into your Unity project. Lua is an easy to learn scripting language so it's a great way to empower artists, writers and designers to use more of the power of Unity. + +At its core, FungusLua allows you to control any Unity object from Lua script. It has useful utilities for using Fungus flowcharts and dialogs, persisting variables between scene loads, localization, and working with the Unity Test Tools. + +We made FungusLua in response to requests from the Fungus community for a way to script Fungus commands from a text file or spreadsheet. We figured that if people are going to be writing commands in text files, why not go all the way and add a powerful embedded scripting language? + +FungusLua comes as part of the [Fungus asset](http://u3d.as/f0T) available on the Unity Asset Store. + +# Tutorial Video + +This video shows how to use many of the features available in FungusLua. It's more of a demonstration than a step-by-step tutorial, but hopefully between this video, the docs and the forums you'll have enough to figure it all out :) + + + +# Using FungusLua On Its Own + +FungusLua can easily be used on its own if you don't need the rest of the functionality in Fungus. + +1. In the project window, move the Fungus/Thirdparty/FungusLua folder up to the root of the project. +2. Delete the Fungus and FungusExamples folders. + +The Tools > Fungus menu will now only show options for creating FungusLua objects. Obviously you won't be able to use Fungus functions like say(), menu(), etc. anymore, but you can still use LuaEnvironment, LuaBindings, LuaScript to add Lua scripting to your game. + +# About Lua + +![Lua logo](images/lua.png) + +[Lua](http://www.lua.org/about.html) is a powerful, fast, lightweight, embeddable scripting language. It is a popular language for game development and supporting user modding. The standard resource for learning Lua is [Programming in Lua](http://www.lua.org/pil/1.html). + +# About MoonSharp + +![MoonSharp Logo](images/moonsharp.png) + +[MoonSharp](http://www.moonsharp.org) is an open source implementation of the Lua scripting language written entirely in C#. + +FungusLua is essentially a set of wrapper components built on top of MoonSharp which make it easier to use Lua scripting directly in the Unity editor. MoonSharp does all the hard work really and is a completely awesome project :) + +The [MoonSharp tutorials](http://www.moonsharp.org/getting_started.html) and [MoonSharp forum](https://groups.google.com/forum/#!forum/moonsharp) are great resources to learn how MoonSharp works, especially for more advanced usage. \ No newline at end of file diff --git a/Docs/fungus_lua/lua_bindings.md b/Docs/fungus_lua/lua_bindings.md new file mode 100644 index 00000000..1a06c9b9 --- /dev/null +++ b/Docs/fungus_lua/lua_bindings.md @@ -0,0 +1,39 @@ +# LuaBindings component + +The LuaBindings component allows you map gameobjects and components in your scenes to Lua variables which you can then access in your Lua scripts. You can bind to any component, including standard Unity components, components from the Unity Asset Store and your own custom scripts. + +As well as scene GameObjects and components, you can bind to any Unity object in your project. This includes things like Prefabs, Materials, TextAssets, Textures, ScriptableObjects, etc. + +![LuaBinding](images/lua_bindings.png) + +# Adding LuaBindings + +To setup LuaBindings in your scene: + +1. Create a LuaBindings object (Tools > Fungus > Create > LuaBindings) +2. Drag the Unity object you want to access to the Object field in the Object Bindings list. +3. The Key field is automatically populated based on the object name. This will be the variable name you use to access the bound object from Lua script. You can change this key to whatever string you prefer. +4. If the bound object is a GameObject, you can optionally select a component within it to bind to. + +# Using a global table + +The bindings specified in a LuaBindings component are automatically registered as global variables in all LuaEnvironments in the scene at startup. + +Registering as global variables is convenient when writing short scripts, but for more complex scripts it could cause problems if you accidentally define another variable with the same name as a binding. To avoid this problem, you can use the Table Name property to register bindings in a global table to add a degree of namespace safety. + +For example, if your binding is called 'camera' and you've set Table Name to "myobjects", you would access the camera object like this: +```lua +myobjects.camera +``` + +Note that by default the LuaBindings component will register its bindings with all LuaEnvironments in the scene. If you don't want this behaviour, deselect the 'All Environments' option and select the specific LuaEnvironment you want to use instead. + +# Finding member info + +The Member Info dropdown box lets you to quickly lookup properties and methods for any bound object. When you select a member, a description of the member is displayed together with the Lua script needed to access it. When binding to standard Unity objects, you can also check the API docs to find out more about the supported methods and properties. + +# Register Types option + +In order to access a C# type from Lua, that type has to be registered with MoonSharp. When the Register Types option is selected, LuaBindings will automatically register the types of bound objects and all public properties & methods that the type uses. + + diff --git a/Docs/fungus_lua/lua_environment.md b/Docs/fungus_lua/lua_environment.md new file mode 100644 index 00000000..92c0903a --- /dev/null +++ b/Docs/fungus_lua/lua_environment.md @@ -0,0 +1,20 @@ +# LuaEnvironment + +The LuaEnvironment component manages all the variables, functions, executing code, etc. for a single Lua context, and provides handy functions for loading and running Lua scripts. In order to run Lua code there must be at least one LuaEnvironment component present in the scene. + +You can create one via (Tools > Fungus > Create > LuaEnvironment). You usually don't need to explicitly create a LuaEnvironment though because FungusLua will create one automatically when there isn't one in the scene at startup. + +![LuaEnvironment](images/lua_environment.png) + +# Multiple Environments + +You can use multiple LuaEnvironments in your scene to ’sandbox’ the variables, functions and executing code of independent sets of Lua scripts. If you do this, make sure to specify the appropriate LuaEnvironment when using LuaScript components, ExecuteLua commands, etc. or else they'll just use the first one they find in the scene. + +# Remote Debugger + +The 'Remote Debugger' option activates the built-in MoonSharp remote debugger tool. The application will halt execution on the first executed line of Lua code and open a MoonSharp debugger window in your browser. See the [MoonSharp documentation](http://www.moonsharp.org/debugger.html) for more information on using this debugger. + +# LuaUtils + +When you create a LuaEnvironment object via (Tools > Fungus > Create > LuaEnvironment), the created gameobject has another component called LuaUtils which adds many useful features to the basic LuaEnvironment setup. See the [Lua Utils](lua_utils.md) section for more info. + diff --git a/Docs/fungus_lua/lua_script.md b/Docs/fungus_lua/lua_script.md new file mode 100644 index 00000000..b7ae5502 --- /dev/null +++ b/Docs/fungus_lua/lua_script.md @@ -0,0 +1,79 @@ +# LuaScript + +The LuaScript component provides an easy way to run Lua scripts in your scene. You can create a LuaScript object via (Tools > Fungus > Create > LuaScript). + +![LuaScript](images/lua_script.png) + +# ExecuteHandler component + +When you create a LuaScript object, you'll see that it contains a component called 'ExecuteHandler'. This component allows you to specify options for when the Lua script should execute. By default it executes the Lua script when the scene starts, but you can change this to execute after a delay, on every update, on trigger events, etc. + +If you want to execute a LuaScript from a custom C# script, set On Event to 'Nothing' and instead call the LuaScript.OnExecute() method directly. You can also call the OnExecute() method from a UI event, e.g. a UI Button 'On Click' event. + +# Lua script and files + +You can enter the Lua code you wish to execute directly into the 'Lua Script' text box. You can also put Lua code into a text file in your project and use the Lua File property to execute it. + +You can also use both options at the same time. In this case, the Lua File contents are loaded first and the Lua Script text is appended to that. This is a handy feature for code reuse and configuration, e.g. create a Lua text file with Lua functions to control your game, and then call those functions from the Lua Script text box. + +# Lua modules and require() + +The Lua module system allows you to create reusable packages of Lua code and include these in your Lua scripts. [This tutorial](http://www.tutorialspoint.com/lua/lua_modules.htm) explains how to write Lua modules. Module files in FungusLua need to be put into a special folder structure so that the Lua require() function is able to locate them. + +To use a Lua module: + +1. Create a Resources/Lua folder in your project. The capitalization here is important. The folder can be created inside an existing folder in your project. +2. Create a mymodule.txt file inside the Resources/Lua folder and add your Lua script to it. (Rename mymodule.txt to whatever you want). +3. You can now use the Lua require function to load the module for use in any Lua script, for example + +```lua +local mymodule = require("mymodule") + +-- Call a function in the module +mymodule.myfunction() +``` + +# Error messages + +When a script contains errors there are a few techniques you can use to track down the source. + +FungusLua compiles Lua code at scene startup so that it can be quickly executed when needed later on. This means you will usually see Lua syntax error messages in the console at startup (during compilation), and runtime errors when the script executes later on. + +All Lua script errors generate an error message in the Unity log, displayed in red. + +For example, if you try to run this invalid code in a LuaScript object: +```lua +not valid lua +``` + +It will generate an error message in the log like this +```lua +LuaScript.LuaScript:(1,0-3): unexpected symbol near 'not' +1: not valid lua +``` + +- The first 'LuaScript.LuaScript' part gives you information about where the Lua script is running from. +- The next part in brackets '(1,0-3)' tells you the line number and character range where the error is located. +- The last part gives you a description of the type of error. +- The next line on gives a listing of the Lua source code. Use the linenumber info above to locate the line causing the problem. + +One of the most common errors is attempting to access a variable that doesn't exist. In this example error message, we've tried to access the field 'name' on a variable v that hasn't been defined yet. + +```lua +LuaScript.LuaScript:(1,7-9): attempt to index a nil value +1: print(v.name) +``` + +To resolve this type of error, carefully check that the variable you want to access has been defined, is spelled correctly and is what you think it is. You can use the print() and inspect() functions to display information about the object in the console. For instance, you may have added a binding to a gameobject, but forgot to select the correct component in the binding. + +For runtime errors, a useful technique is to add print() calls in your code just before where the error occurs, and run it again. This way you can print out information to the console to help track down the cause of the error. + +MoonSharp includes a remote debugger tool which you can use to step through Lua code and inspect variables. See the [LuaEnvironment documentation](lua_environment.md) for more information. + +# Setting the LuaEnvironment + +By default the LuaScript component will use the first LuaEnvironment it finds in the scene to execute, or create one if none exists. If you want to use a specific LuaEnvironment, set it in the Lua Environment property. This is a good way to keep unrelated sets of Lua scripts sandboxed from each other. + +# RunAsCoroutine option + +This option will run the Lua script as a Lua coroutine which is useful for writing asynchronous code via the coroutine.yield() function in Lua. If you don't need to execute your Lua script asynchronously, deselecting this option will avoid the overhead of running as a coroutine. Recommended for advanced users only! diff --git a/Docs/fungus_lua/lua_store.md b/Docs/fungus_lua/lua_store.md new file mode 100644 index 00000000..145e345b --- /dev/null +++ b/Docs/fungus_lua/lua_store.md @@ -0,0 +1,21 @@ +# LuaStore + +A common issue when working with multiple scenes in Unity is how to persist variable values from one scene to the next. By default, all scene objects and their properties are destroyed when you load another scene. + +The Lua Store component provides an easy way around this when using Lua scripting. A shared global table called ‘store’ is bound in every Lua Environment when the scene starts. This global table persists between scene loads, which means you can set a store variable in one scene, load another scene, then access the same store variable and it will still retain the value you set earlier. + +# Example + +- Add a LuaStore to the first scene in your game (Tools >Fungus > Create > LuaStore). +- Set variables in the store in Lua, e.g. + +```lua +store.name = "John" +``` + +- Load another scene, e.g. using the Load Scene command in Fungus +- Get the same variable from the store, e.g. + +```lua +print(store.name) -- prints "John" +``` \ No newline at end of file diff --git a/Docs/fungus_lua/lua_utils.md b/Docs/fungus_lua/lua_utils.md new file mode 100644 index 00000000..36b19ac3 --- /dev/null +++ b/Docs/fungus_lua/lua_utils.md @@ -0,0 +1,107 @@ +# LuaUtils + +LuaUtils is a component that extends the Lua environment with some commonly used functionality. + +It can be accessed from Lua scripts via the 'luautils' global variable. This component mostly does a lot of setup work in the background, but it also provides some handy functions for instantiating, finding and destroying gameobjects in the scene. + +# Example + +Here's an example of the kind of thing you can do: + +```lua +local go = luautils.Find("MyObject") -- Find a game object by name +luautils.Destroy(go) -- Destroy it +``` + +# GameObject Functions + +This is the list of GameObject functions provided in luautils. + +```lua +-- Find a game object by name and returns it. +GameObject Find(string name) + +-- Returns one active GameObject tagged tag. Returns null if no GameObject was found. +GameObject FindWithTag(string tag) + +-- Returns a list of active GameObjects tagged tag. Returns empty array if no GameObject was found. +GameObject[] FindGameObjectsWithTag(string tag) + +-- Create a copy of a GameObject. +-- Can be used to instantiate prefabs. +GameObject Instantiate(GameObject go) + +-- Destroys an instance of a GameObject. +Destroy(GameObject go) + +-- Spawns an instance of a named prefab resource. +-- The prefab must exist in a Resources folder in the project. +GameObject Spawn(string resourceName) +``` + +# Registering C# Types + +The most important function of the LuaUtils component is registering C# types so that instances of those types can be accessed from Lua scripts. + +In order to access the members of a C# type from Lua, the type first has to be registered with MoonSharp. Note that for objects added using the LuaBindings component, the relevant types are registered automatically. + +In some cases however, you will need to register a type explicitly. The easiest way to do this is by adding the type's name to the FungusTypes.txt or UnityTypes.txt JSON files referenced by the LuaUtils component. You can also create your own JSON files to register additional types. Note that types that are not contained in the main application DLL will need to use the [namespace qualified type name](https://msdn.microsoft.com/en-us/library/system.type.assemblyqualifiedname(v=vs.110).aspx) in the JSON file. + +# Example JSON Type File + +Example of a types JSON file: +```json +{ + "registerTypes" : [ + "Fungus.Block" + ], + "extensionTypes" : [ + "Fungus.LuaExtensions" + ] +} +``` + +# Registering Types Directly + +If you need to register types directly from C#, or do a more complex type of registration, you can use the MoonSharp UserData class to do this. See the MoonSharp documentation for a list of supported registration methods. A good place to register C# types is in the Awake method of a custom component. + +# Other Utilities + +LuaUtils creates bindings for several useful C# classes and components so that you can access them from Lua script. + +| Binding name | Description | +| ----------------- | ----------- | +| time | The [Unity Time class](http://docs.unity3d.com/ScriptReference/Time.html). e.g. 'time.deltaTime' returns the delta time for this frame | +| playerprefs | The [Unity PlayerPrefs](preferences.md#playerprefs) class. Used for saving data to disk. | +| prefs | The [FungusPrefs class](preferences.md#fungusprefs), our own wrapper around PlayerPrefs that adds a slots systems. | +| factory | The [PODTypeFactory](lua_utils.md#podfactory) class for creating common plain-old-data types | +| luaenvironment | The LuaEnvironment component used to execute Lua scripts | +| luautils | A reference to the LuaUtils component itself | +| test | Support for [Unity Test Tools](unity_test_tools.md) (if installed) | +| stringtable | The FungusLua localisation [string table](string_table.md) | + +# PODFactory + +Due to limitations in C# / Mono, MoonSharp has limited support for working with Plain-Old-Data (struct) types like [Vector3](http://docs.unity3d.com/ScriptReference/Vector3.html), [Color](http://docs.unity3d.com/ScriptReference/Color.html), etc. + +The best approach here is to treat POD properties as immutable objects, and never try to modify a POD variable that has been acquired from a C# object. Instead, you should construct a new POD object, populate it with the required values and then pass that object in calls to C# code. The LuaUtils PODFactory class helps do this for common Unity types. + +```lua +-- Returns a new Color object +local c = luautils.factory.color(1,1,1,1) + +-- Returns a new Vector2 object +local v2 = luautils.factory.vector2(1, 2) + +-- Returns a new Vector3 object +local v3 = luautils.factory.vector3(1, 2, 3) + +-- Returns a new Vector4 object +local v4 = luautils.factory.vector4(1, 2, 3, 4) + +-- Returns a new Quaternion object +local q = luautils.factory.quaternion(float x, float y, float z) -- Rotation in euler angles + +-- Returns a new Rect object +local r = luautils.factory.rect(float x, float y, float width, float height) +``` \ No newline at end of file diff --git a/Docs/fungus_lua/preferences.md b/Docs/fungus_lua/preferences.md new file mode 100644 index 00000000..a5c8d02f --- /dev/null +++ b/Docs/fungus_lua/preferences.md @@ -0,0 +1,56 @@ +# PlayerPrefs + +The [Unity PlayerPrefs](http://docs.unity3d.com/ScriptReference/PlayerPrefs.html) system stores and accesses player preferences between game sessions. + +Here's an example of using PlayerPrefs from Lua. + +```lua +-- Saving a value to preferences +playerprefs.SetInt("SaveName", 1) +playerprefs.Save() + +-- Using a value from preferences +local v = playerprefs.GetInt("SaveName") +print(v) -- Will print out 1 +``` + +# FungusPrefs + +The FungusPrefs class is a wrapper around PlayerPrefs that adds support for save slots. + +Basically, if you want to store simple values use PlayerPrefs. If you want to store values using multiple player profiles, you should use FungusPrefs. The slot variable is an integer [0..] and key is a string. + +```lua +-- Deletes all saved values for all slots. +prefs.DeleteAll() + +-- Removes key and its value from this save slot. +prefs.DeleteKey(slot, key) + +-- Returns the float value associated with this key in this save slot, it it exists. +prefs.GetFloat(slot, key, defaultValue) + +-- Returns the int value associated with this key in this save slot, it it exists. +prefs.GetInt(slot, key, defaultValue) + +-- Returns the string value associated with this key in this save slot, it it exists. +prefs.GetString(slot, key, defaultValue) + +-- Returns true if the key exists in this save slot. +prefs.HasKey(slot, key) + +-- Writes all modified prefences to disk. +prefs.Save() + +-- Sets the value of the preference identified by key for this save slot. +prefs.SetFloat(slot, key, value) + +-- Sets the value of the preference identified by key for this save slot. +prefs.SetInt(slot, key, value) + +-- Sets the value of the preference identified by key for this save slot. +prefs.SetString(slot, key, value) + +-- Returns the combined key used to identify a key within a save slot. +prefs.GetSlotKey(slot, key) +``` \ No newline at end of file diff --git a/Docs/fungus_lua/string_table.md b/Docs/fungus_lua/string_table.md new file mode 100644 index 00000000..152d414a --- /dev/null +++ b/Docs/fungus_lua/string_table.md @@ -0,0 +1,63 @@ +# String Table + +The LuaUtils component provides support for simple text localisation. + +1. Define your language strings in a JSON file and save it in the project assets folder. +2. Add a LuaEnvironment component to your scene - e.g. Tools > Fungus > Create > LuaEnvironment +3. In the LuaUtils component, set the String Table property to reference your JSON file asset. +4. Use the {$VarName} syntax to subsitute a localised string anywhere that string substitution is supported. e.g. in a Lua script: + +```lua +say("{$hello_world}") +``` + +You can use the {$VarName} syntax anywhere that variable subsitution is supported. This includes: + +- Say command +- Menu command +- Set Text command +- Write command +- Conversation command +- Character object - character name +- Debug Log command +- Load Variable command - save key +- Save Variable command - save key +- Delete Save Key command + +You can also extend the Fungus string substitution system with your own components. Implement the StringSubstituter.ISubstitutionHandler interface in a Monobehavior subclass and then return the modified string from SubstituteStrings(). + +# JSON Format + +This is an example of the JSON format for the string table. To use this localised string, you would use the {$hello_world} tag. + +```json +{ + "hello_world" : { + "en" : "Hello world!", + "fr" : "Bonjour le monde!", + "de" : "Hallo Welt!" + }, + "goodbye_world" : { + "en" : "Goodbye world!", + "fr" : "Au revoir monde!", + "de" : "Auf Wiedersehen Welt!" + } +} +``` + +# Lua Functions + +These Lua functions are available for working with the string table. + +```lua +-- Set active language for string table +setlanguage(languagecode) + +-- Get a named string from the string table +getstring(key) + +-- Substitutes variables and localisation strings into a piece of text +-- e.g. v = 10, "Subbed value is [$v]" => "Subbed value is 10" +sub(text) +``` + diff --git a/Docs/fungus_lua/unity_test_tools.md b/Docs/fungus_lua/unity_test_tools.md new file mode 100644 index 00000000..8c7bccd0 --- /dev/null +++ b/Docs/fungus_lua/unity_test_tools.md @@ -0,0 +1,40 @@ +# Unity Test Tools + +If you are using the [Unity Test Tools](http://u3d.as/65h), FungusLua is a powerful and fast way to create integration tests using Lua scripting. + +# Example + +1. Create a new test in the scene. +2. Add a Lua object (Tools > Fungus > Create > Lua) as a child of the test object. +4. In the LuaScript component, use the check() function to assert whatever conditions you need for the test. At the end, call pass(). + +Example test script: +```lua +-- Check a condition, and output a reason if it fails +check( myvar < 40, "My var is too big") + +-- Just check a condition +check( myvar > 20 ) + +-- Test will exit successfully +pass() +``` + +If any of the checks fail, then the test fails immediately. + +# Lua Functions + +```lua +-- Checks if a condition is true +-- Lua has a built in assert function, so we called this check to avoid conflicting. +check(c, reason) + +-- Pass an integration test +pass() + +-- Fail an integration test +-- reason: Optional string explaining why the test failed. +fail(reason) +``` + + diff --git a/Docs/getting_started/images/002_docking/1_menu.png b/Docs/getting_started/images/002_docking/1_menu.png new file mode 100644 index 00000000..00462ddb Binary files /dev/null and b/Docs/getting_started/images/002_docking/1_menu.png differ diff --git a/Docs/getting_started/images/002_docking/2_window copy.png b/Docs/getting_started/images/002_docking/2_window copy.png new file mode 100644 index 00000000..c9793eb5 Binary files /dev/null and b/Docs/getting_started/images/002_docking/2_window copy.png differ diff --git a/Docs/getting_started/images/002_docking/2_window.png b/Docs/getting_started/images/002_docking/2_window.png new file mode 100644 index 00000000..61d7918e Binary files /dev/null and b/Docs/getting_started/images/002_docking/2_window.png differ diff --git a/Docs/getting_started/images/002_docking/3_docked.png b/Docs/getting_started/images/002_docking/3_docked.png new file mode 100644 index 00000000..2b84fa20 Binary files /dev/null and b/Docs/getting_started/images/002_docking/3_docked.png differ diff --git a/Docs/getting_started/images/003_flowchart/1_menu.png b/Docs/getting_started/images/003_flowchart/1_menu.png new file mode 100644 index 00000000..bbde4693 Binary files /dev/null and b/Docs/getting_started/images/003_flowchart/1_menu.png differ diff --git a/Docs/getting_started/images/003_flowchart/2_gameobject.png b/Docs/getting_started/images/003_flowchart/2_gameobject.png new file mode 100644 index 00000000..c5cbaf9c Binary files /dev/null and b/Docs/getting_started/images/003_flowchart/2_gameobject.png differ diff --git a/Docs/getting_started/images/004_examples/1_examples.png b/Docs/getting_started/images/004_examples/1_examples.png new file mode 100644 index 00000000..3b0a8795 Binary files /dev/null and b/Docs/getting_started/images/004_examples/1_examples.png differ diff --git a/Docs/getting_started/images/004_examples/2_filter_scenes copy.png b/Docs/getting_started/images/004_examples/2_filter_scenes copy.png new file mode 100644 index 00000000..6912ad7a Binary files /dev/null and b/Docs/getting_started/images/004_examples/2_filter_scenes copy.png differ diff --git a/Docs/getting_started/images/004_examples/2_filter_scenes.png b/Docs/getting_started/images/004_examples/2_filter_scenes.png new file mode 100644 index 00000000..e4c40066 Binary files /dev/null and b/Docs/getting_started/images/004_examples/2_filter_scenes.png differ diff --git a/Docs/getting_started/images/004_examples/3_project_window.png b/Docs/getting_started/images/004_examples/3_project_window.png new file mode 100644 index 00000000..fa5d7a13 Binary files /dev/null and b/Docs/getting_started/images/004_examples/3_project_window.png differ diff --git a/Docs/getting_started/images/004_examples/4_filter_scenes_cancel.png b/Docs/getting_started/images/004_examples/4_filter_scenes_cancel.png new file mode 100644 index 00000000..ddb5b839 Binary files /dev/null and b/Docs/getting_started/images/004_examples/4_filter_scenes_cancel.png differ diff --git a/Docs/getting_started/images/004_examples/5_drag_drop.png b/Docs/getting_started/images/004_examples/5_drag_drop.png new file mode 100644 index 00000000..31b7cbaa Binary files /dev/null and b/Docs/getting_started/images/004_examples/5_drag_drop.png differ diff --git a/Docs/getting_started/images/004_examples/6_drag_running.png b/Docs/getting_started/images/004_examples/6_drag_running.png new file mode 100644 index 00000000..7f877d46 Binary files /dev/null and b/Docs/getting_started/images/004_examples/6_drag_running.png differ diff --git a/Docs/getting_started/images/005_highlight_play_mode/1_prefs_tint copy.png b/Docs/getting_started/images/005_highlight_play_mode/1_prefs_tint copy.png new file mode 100644 index 00000000..48e35e2a Binary files /dev/null and b/Docs/getting_started/images/005_highlight_play_mode/1_prefs_tint copy.png differ diff --git a/Docs/getting_started/images/005_highlight_play_mode/1_prefs_tint.png b/Docs/getting_started/images/005_highlight_play_mode/1_prefs_tint.png new file mode 100644 index 00000000..d268b246 Binary files /dev/null and b/Docs/getting_started/images/005_highlight_play_mode/1_prefs_tint.png differ diff --git a/Docs/getting_started/images/005_highlight_play_mode/2_green_play_mode.png b/Docs/getting_started/images/005_highlight_play_mode/2_green_play_mode.png new file mode 100644 index 00000000..267a26fb Binary files /dev/null and b/Docs/getting_started/images/005_highlight_play_mode/2_green_play_mode.png differ diff --git a/Docs/getting_started/images/005_highlight_play_mode/3_menu_prefs.png b/Docs/getting_started/images/005_highlight_play_mode/3_menu_prefs.png new file mode 100644 index 00000000..480699f2 Binary files /dev/null and b/Docs/getting_started/images/005_highlight_play_mode/3_menu_prefs.png differ diff --git a/Docs/getting_started/images/006_new_scene/1_default copy.png b/Docs/getting_started/images/006_new_scene/1_default copy.png new file mode 100644 index 00000000..86e5f1ea Binary files /dev/null and b/Docs/getting_started/images/006_new_scene/1_default copy.png differ diff --git a/Docs/getting_started/images/006_new_scene/1_default.png b/Docs/getting_started/images/006_new_scene/1_default.png new file mode 100644 index 00000000..35800b8e Binary files /dev/null and b/Docs/getting_started/images/006_new_scene/1_default.png differ diff --git a/Docs/getting_started/images/006_new_scene/2_save_as.png b/Docs/getting_started/images/006_new_scene/2_save_as.png new file mode 100644 index 00000000..b8980ef8 Binary files /dev/null and b/Docs/getting_started/images/006_new_scene/2_save_as.png differ diff --git a/Docs/getting_started/images/006_new_scene/3_saved_scene.png b/Docs/getting_started/images/006_new_scene/3_saved_scene.png new file mode 100644 index 00000000..88103063 Binary files /dev/null and b/Docs/getting_started/images/006_new_scene/3_saved_scene.png differ diff --git a/Docs/getting_started/images/007_tools_menu/0_tools.png b/Docs/getting_started/images/007_tools_menu/0_tools.png new file mode 100644 index 00000000..0e061861 Binary files /dev/null and b/Docs/getting_started/images/007_tools_menu/0_tools.png differ diff --git a/Docs/getting_started/images/007_tools_menu/1_tools_create.png b/Docs/getting_started/images/007_tools_menu/1_tools_create.png new file mode 100644 index 00000000..9cf59668 Binary files /dev/null and b/Docs/getting_started/images/007_tools_menu/1_tools_create.png differ diff --git a/Docs/getting_started/images/007_tools_menu/2_tools_utilities.png b/Docs/getting_started/images/007_tools_menu/2_tools_utilities.png new file mode 100644 index 00000000..84b04eec Binary files /dev/null and b/Docs/getting_started/images/007_tools_menu/2_tools_utilities.png differ diff --git a/Docs/getting_started/images/007_tools_menu/3_fungus_tools.png b/Docs/getting_started/images/007_tools_menu/3_fungus_tools.png new file mode 100644 index 00000000..4b2cb2ed Binary files /dev/null and b/Docs/getting_started/images/007_tools_menu/3_fungus_tools.png differ diff --git a/Docs/getting_started/images/008_create_flowchart/1_tools_create.png b/Docs/getting_started/images/008_create_flowchart/1_tools_create.png new file mode 100644 index 00000000..8b39aa1e Binary files /dev/null and b/Docs/getting_started/images/008_create_flowchart/1_tools_create.png differ diff --git a/Docs/getting_started/images/008_create_flowchart/2_flowchart_gameobject.png b/Docs/getting_started/images/008_create_flowchart/2_flowchart_gameobject.png new file mode 100644 index 00000000..12ce2cf3 Binary files /dev/null and b/Docs/getting_started/images/008_create_flowchart/2_flowchart_gameobject.png differ diff --git a/Docs/getting_started/images/008_create_flowchart/3_flowchart_properties copy.png b/Docs/getting_started/images/008_create_flowchart/3_flowchart_properties copy.png new file mode 100644 index 00000000..2031827e Binary files /dev/null and b/Docs/getting_started/images/008_create_flowchart/3_flowchart_properties copy.png differ diff --git a/Docs/getting_started/images/008_create_flowchart/3_flowchart_properties.png b/Docs/getting_started/images/008_create_flowchart/3_flowchart_properties.png new file mode 100644 index 00000000..0a03f271 Binary files /dev/null and b/Docs/getting_started/images/008_create_flowchart/3_flowchart_properties.png differ diff --git a/Docs/getting_started/images/009_rename_block/1_rename copy.png b/Docs/getting_started/images/009_rename_block/1_rename copy.png new file mode 100644 index 00000000..68ec56f6 Binary files /dev/null and b/Docs/getting_started/images/009_rename_block/1_rename copy.png differ diff --git a/Docs/getting_started/images/009_rename_block/1_rename.png b/Docs/getting_started/images/009_rename_block/1_rename.png new file mode 100644 index 00000000..21300929 Binary files /dev/null and b/Docs/getting_started/images/009_rename_block/1_rename.png differ diff --git a/Docs/getting_started/images/010_say_command/1_plus.png b/Docs/getting_started/images/010_say_command/1_plus.png new file mode 100644 index 00000000..3092fd15 Binary files /dev/null and b/Docs/getting_started/images/010_say_command/1_plus.png differ diff --git a/Docs/getting_started/images/010_say_command/2_narrative_say.png b/Docs/getting_started/images/010_say_command/2_narrative_say.png new file mode 100644 index 00000000..5767fbc9 Binary files /dev/null and b/Docs/getting_started/images/010_say_command/2_narrative_say.png differ diff --git a/Docs/getting_started/images/010_say_command/3_hello_fungus_world copy.png b/Docs/getting_started/images/010_say_command/3_hello_fungus_world copy.png new file mode 100644 index 00000000..41ed51f2 Binary files /dev/null and b/Docs/getting_started/images/010_say_command/3_hello_fungus_world copy.png differ diff --git a/Docs/getting_started/images/010_say_command/3_hello_fungus_world.png b/Docs/getting_started/images/010_say_command/3_hello_fungus_world.png new file mode 100644 index 00000000..2aeceefb Binary files /dev/null and b/Docs/getting_started/images/010_say_command/3_hello_fungus_world.png differ diff --git a/Docs/getting_started/images/010_say_command/4_scene_running.png b/Docs/getting_started/images/010_say_command/4_scene_running.png new file mode 100644 index 00000000..82ba18f6 Binary files /dev/null and b/Docs/getting_started/images/010_say_command/4_scene_running.png differ diff --git a/Docs/getting_started/index.md b/Docs/getting_started/index.md new file mode 100644 index 00000000..ddd89495 --- /dev/null +++ b/Docs/getting_started/index.md @@ -0,0 +1,218 @@ +# Getting Started {#getting_started} + +Follow these steps to get up and running with Fungus quickly, then learn more about what Fungus can do and how to do it from the other documentation pages and videos. + + +## Opening and docking the Flowchart window +You'll need the Fungus Flowchart window when working with Fungus. Open and dock this window somewhere handy by following these steps: + +1. Choose menu: ``Tools | Fungus | Flowchart Window`` +
+![Menu open Fungus window](./images/002_docking/1_menu.png "Menu open Fungus window") +
+
+ +2. Drag-and-drop the Flowchart window to the location you wish to dock it: +
+![Drag Fungus window](./images/002_docking/2_window.png "Drag Fungus window") +
+
+ +3. The Flowchart window is now docked and part of your Unity window layout: +
+![Docked Fungus window](./images/002_docking/3_docked.png "Docked Fungus window") + + +## Finding the example folders and scene files +Two folders are created when you install Fungus, the Fungus features themslves (in folder 'Fungus') and a set of examples (in folder 'FungusExamples'). + +Examples include Drag and Drop, Sherlock and Fungus Town: +
+![Fungus Examples](./images/004_examples/1_examples.png "Fungus Examples") +
+ +You can use the left-hand side of the Unity Project window to explore each example folder: +
+![Fungus Examples Project window](./images/004_examples/3_project_window.png "Fungus Examples Project window") +
+ +Alternatively, you can 'filter' the Project view to show all scenes (and no other files) by clicking the scene filter icon to the right of the search bar: +
+![Fungus Examples Project window filter scenes](./images/004_examples/2_filter_scenes.png "Fungus Examples Project window filter scenes") +
+ +You can cancel the filter by clicking the 'x' in the search bar: +
+![Fungus Examples Project window filter scenes cancel](./images/004_examples/4_filter_scenes_cancel.png "Fungus Examples Project window filter scenes cancel") +
+ + +## Loading and playing the example scenes +To **load** an example scene, double click the desired example's scene object in the Project window, and the scene should load. For example, this screenshot shows the scene and Flowchart windows when the DragAndDrop example scene has been loaded: +
+![Fungus Examples Drag Drop](./images/004_examples/5_drag_drop.png "Fungus Examples Drag Drop") +
+ +To **run** the currently loaded scene (i.e. to enter **Play-mode**), click the Unity 'play' triangle button at the center top of the Unity application window, and then do whatever makes sense in that scene (e..g click/type text/drag-and-drop objects etc.!): +
+![Unity play scene](./images/004_examples/6_drag_running.png "Unity play scene") +
+ +Note: you click the 'play' button a second time to end **Play-mode**. + + +## Changes made during playmode don't persist +As with all Unity projects, you can **change** the properties of gameObjects while a scene is running, but these changes are 'ephemeral' - they only last while the scene is running. As soon as you end play mode the properties of all objects in the Hierarchy will revert to those saved in the Scene file. + +This makes it easy to 'tweak' values of objects in **Play-mode**, and then when the desired behaviour is achieved, those values can be set for the saved scene properties. + +Values set when Unity is in **Edit-mode** will be saved when you saved your scene (``CTRL-S`` / ``Command-S``, or menu: ``File | Save Scene``). + + +## Change your preferences to highlight Play-mode +Sometimes we can forget we are in Unity **Play-mode**, and then make changes to Hierarchy gameObject values that are then 'fogotton' when we do stop playing the scene. A good way to avoid this problem is to to set a 'tint' to the Unity editor to make it visually very clear to us when we are in **Play-mode**. To add a tint to **Play-mode** do the following: + +1. Open the Unity preferences dialog by choosing menu: ```File | Preferences ...``` + +2. Select the ```Colors``` preferences, and choose a light colored tint (we chose a light green in this case): +
+![Unity preferences dialog](./images/005_highlight_play_mode/1_prefs_tint.png "Unity preferences dialog") +
+
+ +3. Close the dialog (changes are saved automatically). + +4. When you next enter **Play-mode** you'll see most of the Unity Editor windows turn green (apart from the Game and Flowchart windows): +
+![Unity Play Mode tinted](./images/005_highlight_play_mode/2_green_play_mode.png "Unity Play Mode tinted") +
+ + +## Creating, naming and saving a new scene from scratch +To create a new scene in Unity do the following: + +1. Choose menu: ```File | New Scene``` + +2. Note: if you have any unsaved changes for the current scene you need to either save or abandon them before a new scene can be created. + +3. You should now have a shiny new scene, with a Hierarchy containing just one gameObject, a Main Camera. The new scene will have been give the default name "Untitled", which you can see in the title of the Application window: +
+![New Scene](./images/006_new_scene/1_default.png "New Scene") +
+
+ +4. Good practice is to save your scene (in the right place, with the right name), before creating your work in the scene. Let's save this scene in the root of our project "Assets" folder, naming it "demo1". First choose menu: ```File | Save Scene As...``` + +5. Choose the location and name (we'll choose folders "Assets" and scene name "demo1"): +
+![Save Scene As dialog](./images/006_new_scene/2_save_as.png "Save Scene As dialog") +
+
+ +6. Once you have successfully saved the scene you should now see the new scene file "demo1" in your Assets folder in the Project window, and you should also see in the Application window title that you are currently editing the scene named "demo1": +
+![Editing newly saved scene](./images/006_new_scene/3_saved_scene.png "Editing newly saved scene") +
+ + +## Menu: Tools | Fungus +The core Fungus operations are available from the Unity ```Tools``` menu. + +Choose menu: ```Tools | Fungus``` to see the options available: +
+![Fungus Tools menu](./images/007_tools_menu/3_fungus_tools.png "Fungus Tools menu") +
+ +As can be seen, there are 2 submenus, ```Create``` and ```Utilities```, plus the ```Flowchart Window``` action (which reveals the window if already open, or opens a new window if the Flowchart window was not previously opened). + + +### Menu: Tools | Fungus | Create +The Fungus Tools ```Create``` submenu offers the following actions: +
+![Fungus Tools Create menu](./images/007_tools_menu/1_tools_create.png "Fungus Tools Create menu") +
+ + +### Menu: Tools | Fungus | Utilities +The Fungus Tools ```Utilties``` submenu offers the following actions: +
+![Fungus Tools Utilties menu](./images/007_tools_menu/2_tools_utilities.png "Fungus Tools Utilities menu") +
+ + +## Create a Flowchart +To create a Fungus Flowchart do the following: + +1. Choose menu: ```Tools | Fungus | Create Flowchart``` +
+![menu create Flowchart](./images/008_create_flowchart/1_tools_create.png "menu create Flowchart") +
+
+ +2. A new **Flowchart** gameObject should appear in the Hierarchy window. +
+![new Flowchart gameobject](./images/008_create_flowchart/2_flowchart_gameobject.png "new Flowchart gameobject") +
+
+ +3. Select the **Flowchart** gameObject in the Hierarchy window, and you'll see the **Flowchart's** properties in the Inspector Window: +
+![Flowchart properties](./images/008_create_flowchart/3_flowchart_properties.png "Flowchart properties") +
+
+ +4. If you have not already displayed the Flowchart Window, you can do so by clicking the Flowchart Window button in the Inspector. + +5. As you can see, when a new Flowchat is created a single command Block named "New Block" is automatically created, with the Event handler "Game Started" (so it will start executing Fungus commands as soon as the scene goes into **Play Mode**). + + +## Flowchart Block property viewing and editing +Let's change the name of the default command Block of a new Flowchart in the Flowchart window to "hello". Do the following: + +1. Create a new Fungus Flowchart (if you haven't already done so). + +2. Click to select the Block in the Flowchart window (when multiple blocks are present, the selected one gets a green highlight border). + +3. In the Inspector change the text for the Block Name property to "hello". You should see the Block name change in the Flowchart window: +
+![rename Block](./images/009_rename_block/1_rename.png "rename Block") +
+ + +## Add a Say command +To add a "Say" command to a Block do the following: + +1. (setup) Create a new scene, add a Fungus Flowchart to the scene. + +1. Ensure the Block is selected, and you can see its properties in the Inspector, and ensure the name of the Block is "hello". + +2. Click the Plus button in the bottom half of the Inspector window, to add a new Command to the Block's properties: +
+![new command button](./images/010_say_command/1_plus.png "new command button") +
+
+ +3. Choose menu: ```Narrative | Say```: +
+![add Say command](./images/010_say_command/2_narrative_say.png "add Say command") +
+
+ +4. Since this Block only has one Command, that command is automatically selected (shown with a green highlight). + +5. In the "Story Text" textbox in the bottom half of the Inspector window type in "hello Fugus world": +
+![story text](./images/010_say_command/3_hello_fungus_world.png "story text") +
+
+ +6. Run the scene, and see Fungus create a dialog window, and output the text contents of your Say command: +
+![story text output](./images/010_say_command/4_scene_running.png "story text output") +
+
+ + +[Unity3D.com]: http://www.unity3d.com +[Unity3D.com/get-unity]: http://unity3d.com/get-unity +[FungusGames.com]: http://www.fungusgames.com diff --git a/Docs/glossary/images/001_3_block_types/1_event_block.png b/Docs/glossary/images/001_3_block_types/1_event_block.png new file mode 100644 index 00000000..77bc1c6b Binary files /dev/null and b/Docs/glossary/images/001_3_block_types/1_event_block.png differ diff --git a/Docs/glossary/images/001_3_block_types/2_branching_block.png b/Docs/glossary/images/001_3_block_types/2_branching_block.png new file mode 100644 index 00000000..a55a40b7 Binary files /dev/null and b/Docs/glossary/images/001_3_block_types/2_branching_block.png differ diff --git a/Docs/glossary/images/001_3_block_types/3_standard_block.png b/Docs/glossary/images/001_3_block_types/3_standard_block.png new file mode 100644 index 00000000..24600331 Binary files /dev/null and b/Docs/glossary/images/001_3_block_types/3_standard_block.png differ diff --git a/Docs/glossary/images/001_variables/1_default_values.png b/Docs/glossary/images/001_variables/1_default_values.png new file mode 100644 index 00000000..c905767d Binary files /dev/null and b/Docs/glossary/images/001_variables/1_default_values.png differ diff --git a/Docs/glossary/images/010_say_command/4_scene_running.png b/Docs/glossary/images/010_say_command/4_scene_running.png new file mode 100644 index 00000000..82ba18f6 Binary files /dev/null and b/Docs/glossary/images/010_say_command/4_scene_running.png differ diff --git a/Docs/glossary/images/011_menu_maths/9_menu_running.png b/Docs/glossary/images/011_menu_maths/9_menu_running.png new file mode 100644 index 00000000..ea8fbe9f Binary files /dev/null and b/Docs/glossary/images/011_menu_maths/9_menu_running.png differ diff --git a/Docs/glossary/index.md b/Docs/glossary/index.md new file mode 100644 index 00000000..c40460e4 --- /dev/null +++ b/Docs/glossary/index.md @@ -0,0 +1,525 @@ +# Glossary of terms {#glossary} + + + + + +## A + +**Animator parameter**: +Special variables that can be used to change what happens in an animation chart, such as when to trigger a chance from one animation state to another. + + + +**Assets**: +The files on the computer/device, that are used in a game. Asset files include audio clips, video clips, 2D images, 3D models, and text files containing computer program code. + + + +**Audio tag**: +One of the tags specially allowing the control of Audio from within the Story Text of a Say Command. + +There are four audio related tags: + + {audio=AudioObjectName} Play Audio Once + {audioloop=AudioObjectName} Play Audio Loop + {audiopause=AudioObjectName} Pause Audio + {audiostop=AudioObjectName} Stop Audio + +For more information see: [Audio Tags recipe](../../audio/#audio-tags-in-say-commands/index.html) + + +**Audiosource**: +A special component of Unity objects that can refer to a particular audio clip file, and control its playing / pausing / 3d effects etc. + + + + + +## B + + +**Block**: +A Fungus Block is a sequence of Commands that have been created inside a Fungus Flowchart. + + +**Block connection**: +When Commands in one Block cause the execution of Commands in another Block. + + + +**Boolean variable**: +A true/false variable. + + +**Branching block**: +A Block that is **not** an Event Block, and causes execution of 2 or more other Blocks. + +Note: Branching Blocks are displayed as an orange polygon in the Flowchart window. + +![branching block](./images/001_3_block_types/2_branching_block.png "branching block") + + +**Branching narrative**: +When choices by the user (via the Menu Command for example) will change what Narrative Commands are executed and displayed to the user. + + + + +**Build platform**: +The target device for which a Unity game application will be built. + + +**Build settings**: +Build settings include the target platform, screen resolution, input devices, scenes to be included etc. + + + + + + + + + + + + + + + + +## C + + + +**Csharp (C♯)**: +A computer programming language developed by Microsoft, similar to Java. C♯ is one of the programming languages that can be used to write scripts for controlling Unity games. + + +**Character**: +A Fungus gameObject allowing the personalisation of narrative, allowing characters to have names, special colours for their text on screen, and a range of different named images so character images can be displayed corresponding to the content of their dialog. + + +**Clickable Sprite**: +A 2D image on screen that has been code to do something when clicked with the mouse or selected by the trackpad. + + +**Coding / Scripting**: +Writing lines of computer code to control execution of a computer program, such as a Unity game (as opposed to using a visual language such as Fungus Flowcharts). + + +**Command**: +An instruction for the Unity game engine to do something, examples are to play or stop a sound, or to display some text to the user in a dialog. + + +**Command category**: +THe Fungus commands are grouped according to what kind of action they will lead to. + + +**Command property panel**: +When a Block is selected in a Fungus Flowchart, the top-half of the Inspector window will show the properties and list of Commands for that Block. When one of the Commands is selected, that its properties are displayed in the bottom-half of the Inspector window. + + + +**Condition**: +Conditions are tests that are either "TRUE" or "FALSE" at a particular point in time. Different Commands can be defined to be executed depending on the value of a condition test in a Fungus Block. + + + +**CSV**: +Comma Separated Variable - a computer file format where the values of rows and columns are recorded, in a form that can be loaded into a spreadsheet.. + + + +**Custom strings**: +As well as the automatically generated rows for each Say, Menu, Command etc., you can also add your own rows to the localisation file using any string id you want. To use these custom strings, you use variable substitution. + +For example, say you have a custom string called "PlayerName", you can put {$PlayerName} in any Say text to substitute the correct localised value from the localisation file. + + + + + +## D + + +**Draggable Sprite**: +A 2D image on screen that has been code to do something when clicked-and-dragged with the mouse or trackpad. + + +**DragTarget Sprite**: +A 2D image that has been defined to execute some action(s) if a Draggable Sprite is dragged and released over it. + + + + + +## E + + +**Editor**: +An application allowing the editing of game resources. The Unity Editor has multiple windows for viewing / editing properties of files, scene contents, UI dialogs, camera settings etc. + + +**Event Handler**: +A Fungus Block or a Unity coded "method" that will be executed when a particular "Event" occurs. For example when the "SPACE" key is pressed the game should respond to the user having executed a spell or fired a gun or whatever. + + +**Event block**: +Any Block whose execution is triggered by an Event, such as Game Started or Key Preses. + +Note: Event Blocks are displayed as rounded blue rectangles in the Flowchart window. + +![event block](./images/001_3_block_types/1_event_block.png "event block") + + +**Excel**: +A computer spreadsheet application program from Microsoft, part of the MS Office suite. + +see the Microsoft website: [Microsoft Excel application] + + + +**Execution**: +The running of Commands or statements in a computer script / program. Making the computer do something. + + + + + +## F + + +**Float variable**: +A variable that stores decimal numbers, such as 5.5, -0.11 etc. + + + +**Flowchart**: +A Fungus Flowchart contains a set of Blocks, each containing Commands to be executed. + + +**Flow control**: +A general term referring to how a computer decides what to do next. So it is deciding which Fungus Command or Unity code statement to execute next. Typical Flow commands include decision choices such as loops or IF-conditions etc. + + +**Flowchart item id**: +The unique number that is created for each Block of a Flowchart. This ID is used fpr serialisation (save and load) purposes, and not usually seen by the developer. + + +**Flowchart Localization id**: +A special, unique name, used for associating language localization data for each Fungus game project. + + +**Flowchart Message**: +A Message is basically a piece of text, but one that plays the role of being able to act as a 'trigger event' to cause Blocks to start executing. + +Messages can be sent (via the ```Flow | Send Message``` Command), either to the current Flowchart, or to **ALL** Flowcharts. One of the Events that can be defined to start the execution of a Block is if a particular Message has been received by the Flowchart. + + +**Flowchart Window**: +A special window available in the Unity Editor for editing and working with Fungus Flowcharts and their Blocks. + + + + + +## I + + +**Integer variable**: +A variable that stores whole numbers, such as 100, 2, 0, -2 etc. + + + + + +## L + + +**Landscape orientation**: +An orientation of an image or computer screen, where the width is greater than the height. + + +**Language Column**: +When you first export the localization .csv (Comma-Separated-Variable) file it has 3 columns (Key, Description, Standard). +When you want to add a new language to the file you add a new column for that language. You can use whatever column name you like, though it's typical to use two letter language codes (FR, ES, DE, etc.). + +The Set Language command is provided with the name of the column for the language you wish to use in Fungus. + + +**Libre Office**: +A free and Open Source alternative to Microsoft Office. + +Lean more and download from: [LibreOffice.org] + + +**Localization**: +Localization and Internationalization refer to coding a game in such a way that it can be deployed in a manner supporting playing and interactions in multiple human languages. + + +**Logging**: +The ```Scripting | Debug Log``` Command allows the writing ('logging') of messages to the Console window while a scene is running. Logs provide a record of what has happened when the game is running, useful for checking what happened was what was intended, or for debugging (hunting down where errors are located). + + + + + +## M + + +**Mecanim Animation**: +A Unity file representing an animation clip or pose. Animators manage the changes or mixing between one Animation clip and another. + + +**Mecanim Animator**: +A Unity state-chart controller, which manages animated gameObjects - deciding when and how quickly objects should 'blend' into a different state or animation. + + +**Menu Dialog**: +The UI elements (background / lines / text) that define the visual style of how the Text of Menu Commands is presented to the user. + +![menu running](./images/011_menu_maths/9_menu_running.png "menu running") + +Fungus provides a default Menu Dialog, but custom variations can be defined, for different games / scenes / characters etc. + + + + + +## O + + +**Order in layer**: +If multiple objects have been assigned to the same Unity Sorting Layer, then the numeric value of the Order in Layer property determines their visual sorting order (what appears in front of what). + + + + + + + +##P + + +**Parallax Sprite**: +The use of 2D sprites, moving at different speeds, to give the impression of 3D movement (where sprites for objects meant to be further away from the user move more slowly than objects closer to the game object. + + +**Platform build**: +Refers to the device and type of application that the Unity editor will create. Examples are stand alone applications for Windows, Mac OS, iOS phone, Android phone, X-BOX etc. + + +**Portrait**: +The Fungus Portrait Command is used to make the game display one of the Character Portrait images on the Stage. A particular image can be selected, and it can be made to move on/off stage. + + +**Portrait orientation**: +An orientation of an image or computer screen, where the height is greater than the width. + + +**Procedural Sound**: +A method of creating sounds using computer algorithms. + + +**Private / Public variables**: +A Private variable as one that can only be accessed by Cmmands in Blocks in that Flowchart. A Public variable is one that can be accessed by Commands in Blocks in other Flowcharts as well as its own one. + + + + + +## S + + + + +**Save profile**: +The Save Profile is basically a string that gets prepended to the key used to save & load variables in PlayerPrefs. This allows you to create separate save profiles using different names. For example, player 1's save data might use the Save Profile 'Chris', while player 2's data would use the Save Profile 'Matt', and their data can be saved / loaded independently. + +The typical workflow would be: + +1. Choose a suitable value fo the Save Profile (e.g. "player1") + +2. Set Save Profile. + +3. Save Variable(s). + + + +**Say Dialog**: +The UI elements (background / lines / text) that define the visual style of how the Story Text of Say Commands is presented to the user. + +![story text output](./images/010_say_command/4_scene_running.png "story text output") + + +Fungus provides a default Say Dialog, but custom variations can be defined, for different games / scenes / characters etc. + + +**Scenes**: +Unity Scenes are like chapters in a book, or "screens" in a game, or "levels" in a game. They allow the logic of a computer game to be broken into components. The "gameObjects" in a scene determine what software components will be created when a Scene starts running (others may be created or deleted once the Scene has started). + + +**Screen aspect ratio**: +The relationship of the width of an image or screen to its height. Typical rations include 4:3 ad 16:10. + + +**Screen resolution**: +The number of pixels wide and high a window or device supports. + + +**Sorting layer**: +Unity 2D objects are assigned to a "Sorting Layer". This allows images/text to be assigned to layers such as Background, Foreground, Middleground, UI (on top of everything) etc. + + +**Spine**: +Spine is a third-party 2D animation system from [EsotericSoftware.com]. + + +**Spine Animation**: +Animation clip based on the Spine 2D system, that can be controlled from Fungus Commands (once the Unity Spine and Fungus Spine add-on packages have been installed). + + + +**Sprites**: +2D Images, that may be hidden / revealed. Sprite may be moved through Fungus Commands, or Unity code. Sprites can also be defined to be "draggable" by the users computer mouse pointer or mobile device touch gestures. + + + +**Stage**: +A Fungus gameObject in the scene, used to define the position and start-end movements of Character Portrait images controlled by Fungus Portrait Commands. + + +**Standard block**: +A Fungus Block whose execution is **not** triggered by an event (so it is not an Event Block), and which does **not** cause the execution of 2 or more other Blocks (so is **not** a Branching Block). + +Note: Standard Blocks are displayed as yellow rectangles in the Flowchart window. + +![standard block](./images/001_3_block_types/3_standard_block.png "standard block") + + + +**Standard Text**: +When you export the localization file, there is a Standard Text field. This is populated with the text that has been entered into the Say, Menu, etc. text fields in the Unity editor. In normal usage, this field is in the localisation file for reference so localizers know what text needs to be translated. For example, if the project is drafted using English, then the text in Say, Menu Commands etc. would be in English, and in the exported localization file this text would appear in the Standard Text fields. + +Note, if you use the Set Language command with an empty language string then the values in the Standard Text field will be used when Fungus runs. + + + +**Story Text Tags**: +Special instructions that can be embedded inside the Story Text of Say commands. Examples are tags that start/stop playing a sound, or send a message. + + + + +**String ID**: +This is an automatically generated ID code, that is stored in the first column of the localisation file. These IDs are generated automatically when you export the strings using the Localization object. + +The ID is needed since every localised text string needs a unique identifying name so that it can be mapped it back to the Say, Menu, etc. command that references it. + + +**String variable**: +A variable that stores text characters, such as the player's name, or colour of the potion they are carrying. + + + + + + + + +## T + + +**Tag**: +Special characters that can be inserted into Fungus Say Commands, to control other aspects of the scene, such as the playing of a sound, or the shaking of the camera, or the sending of a message to cause other Blocks to start executing. + + + + + + +## U + + +**Unity**: +A game engine and IDE (Interactive Development Environment) - with program code editor, and audio/graphics editing facilities. Able to build applications for deployment to Windows, Mac, Linus, iOS, Android, XBox etc. + + +**Unity UI**: +The building of visual interfaces for computer programs deployed by Unity. + + + +**Usfxr**: +A system for generating sound effects from mathematical parameters. + +Built into Fungus and based on the open source project at: [Usfxr at GitHub] + + + + + +## V + + +**Variable**: +A named memory location, from which values can be retrieved at a later date. + + +**Variable default value**: +A "default" value refers to the value given to a variable automatically, if no particular value is specified. In the Variables section at the bottom of the Flowchart window, as well as defining the names and data types of variables, you can also set default values here. + +![default variable value](./images/001_variables/1_default_values.png "default variable value") + + +**Variables Panel**: +The very bottom section of the Flowchart window is where variables (such as score, playerName, carryingGreenKey etc.) can be defined for use in Fungus Commands. + + +**Variable saving**: +The saving of the value of a variable to the devices 'disk'. So when another Unity Scene is loaded, the saved value can be loaded from saved memory. The saved value can also be loaded the next time the game application is executed on a device. + + +**Variable substitution**: + +This relates to the use of a tag in the Story Text of a Say Command, whereby the contents of a Variable will be inserted into that part of the text for the Say Command + +```{$VarName} Substitute variable``` + + +**View, Move, Rotate, Scale & Rectangle tools**: +The core tools offered in the Unity editor for changing basic properties of 2D and 3D objects + + +**View**: +A Fungus gameObject that helps ensure good visual experience regardless of device aspect ration, and used for camera movements and control by Fungus Commands. + + +**Voice over**: +A sound clip file containing recorded audio that corresponds to text being displayed on screen. + + + + + +## W + + +**Webplayer**: +A Build option in Unity that creates an application that can play inside web pages that have the Unity Web Player plug-in installed. The need fo the plug-in and web-player option are being replaced by the WebGL Unity build facility. + + +**WebGL**: +[WebGL] is a technology available in modern browsers that allows for interactive, high quality computer graphics within web pages, without the need for any special plug-ins (such as Flash or the Unity Player). It promised to be the future for multimedia web page content and interaction. + + + + +[WebGL]: https://en.wikipedia.org/wiki/WebGL +[LibreOffice.org]: http://www.libreoffice.org/ +[EsotericSoftware.com]: http://esotericsoftware.com/ +[Usfxr at GitHub]: https://github.com/zeh/usfxr +[Microsoft Excel application]: http://products.office.com/excel diff --git a/Docs/guide_commands/index.md b/Docs/guide_commands/index.md new file mode 100644 index 00000000..66947ff1 --- /dev/null +++ b/Docs/guide_commands/index.md @@ -0,0 +1,65 @@ +# Fungus Fundamentals - Commands +A fundamental concept of Fungus is the **Command**. + + +## What is a command? + + +## Command properties panel + + +## Adding commands + + +## Command categories + + +## Pause After Command property + + +## Reordering commands with drag and drop + + +## Command and shift select commands + + +## Move command selection up/down buttons + + +## Duplicate button + + +## Delete button + + +## Copy, Paste, Delete, Select All, Select None context menu and keyboard shortcuts + + +## Keyboard shortcuts + + +## Resizing the command property panel + + +## Disabling a command + + +## Flowchart item id (number beside enabled check) + + +## Command indenting + + +## Command help info + + +## Table of all commands provided with Fungus + + +## Exporting Event Handler class info + + +## Link to creating custom commands in Extending Fungus + + +## Cut, copy, paste, etc. context menu & keyboard shortcuts diff --git a/Docs/images/favicon.ico b/Docs/images/favicon.ico new file mode 100644 index 00000000..3f6e96e0 Binary files /dev/null and b/Docs/images/favicon.ico differ diff --git a/Docs/images/itb_logo.gif b/Docs/images/itb_logo.gif new file mode 100644 index 00000000..6d0624fd Binary files /dev/null and b/Docs/images/itb_logo.gif differ diff --git a/Docs/images/logo.png b/Docs/images/logo.png new file mode 100644 index 00000000..1eae3550 Binary files /dev/null and b/Docs/images/logo.png differ diff --git a/Docs/images/logo_100.png b/Docs/images/logo_100.png new file mode 100644 index 00000000..0e37e72b Binary files /dev/null and b/Docs/images/logo_100.png differ diff --git a/Docs/images/logo_mid.png b/Docs/images/logo_mid.png new file mode 100644 index 00000000..87059bf7 Binary files /dev/null and b/Docs/images/logo_mid.png differ diff --git a/Docs/mainpage.md b/Docs/mainpage.md new file mode 100644 index 00000000..372d994d --- /dev/null +++ b/Docs/mainpage.md @@ -0,0 +1,29 @@ +# Fungus Docs + +Welcome to the documentation website for Fungus, the open source visual storytelling tool for [Unity](http://unity3d.com). + +The main website for Fungus and [community forum](http://fungusgames.com/forum) are available at [FungusGames.com](http://fungusgames.com). + +* @subpage about +* @subpage download +* @subpage getting_started +* @subpage flowcharts +* @subpage blocks +* @subpage telling_a_story +* @subpage playing_audio +* @subpage conversation +* @subpage articles +* @subpage glossary +* @subpage faq + +# Overview + +There's a wide range of training material available here, suitable for both beginner and experienced game developers. + +- [What is Fungus?](about/index.md) +- [Download and install instructions](download/index.md) +- [Tutorial videos](tutorial_videos/index.md) +- [Fungus Training Course](training_course/index.md) +- [FungusLua scripting system](fungus_lua/index.md) +- [Articles by the Fungus community](articles/index.md) +- [Frequently Asked Questions](faq/index.md) diff --git a/Docs/playing_audio/images/000_big_picture/1_big_picture.png b/Docs/playing_audio/images/000_big_picture/1_big_picture.png new file mode 100644 index 00000000..a3b51c66 Binary files /dev/null and b/Docs/playing_audio/images/000_big_picture/1_big_picture.png differ diff --git a/Docs/playing_audio/images/001_clips/0_audio_in_examples copy.png b/Docs/playing_audio/images/001_clips/0_audio_in_examples copy.png new file mode 100644 index 00000000..b81865d3 Binary files /dev/null and b/Docs/playing_audio/images/001_clips/0_audio_in_examples copy.png differ diff --git a/Docs/playing_audio/images/001_clips/0_audio_in_examples.png b/Docs/playing_audio/images/001_clips/0_audio_in_examples.png new file mode 100644 index 00000000..a7ce1c9a Binary files /dev/null and b/Docs/playing_audio/images/001_clips/0_audio_in_examples.png differ diff --git a/Docs/playing_audio/images/002_audio_into_unity/1_drag_folder copy.png b/Docs/playing_audio/images/002_audio_into_unity/1_drag_folder copy.png new file mode 100644 index 00000000..944c815d Binary files /dev/null and b/Docs/playing_audio/images/002_audio_into_unity/1_drag_folder copy.png differ diff --git a/Docs/playing_audio/images/002_audio_into_unity/1_drag_folder.png b/Docs/playing_audio/images/002_audio_into_unity/1_drag_folder.png new file mode 100644 index 00000000..27528b80 Binary files /dev/null and b/Docs/playing_audio/images/002_audio_into_unity/1_drag_folder.png differ diff --git a/Docs/playing_audio/images/003_fungus_audio_commands/1_audio_commands.png b/Docs/playing_audio/images/003_fungus_audio_commands/1_audio_commands.png new file mode 100644 index 00000000..74b44062 Binary files /dev/null and b/Docs/playing_audio/images/003_fungus_audio_commands/1_audio_commands.png differ diff --git a/Docs/playing_audio/images/003_fungus_audio_commands/2_say_voiceover_clip copy.png b/Docs/playing_audio/images/003_fungus_audio_commands/2_say_voiceover_clip copy.png new file mode 100644 index 00000000..a079f8b2 Binary files /dev/null and b/Docs/playing_audio/images/003_fungus_audio_commands/2_say_voiceover_clip copy.png differ diff --git a/Docs/playing_audio/images/003_fungus_audio_commands/2_say_voiceover_clip.png b/Docs/playing_audio/images/003_fungus_audio_commands/2_say_voiceover_clip.png new file mode 100644 index 00000000..c89393d3 Binary files /dev/null and b/Docs/playing_audio/images/003_fungus_audio_commands/2_say_voiceover_clip.png differ diff --git a/Docs/playing_audio/images/004_play_music/1_add_playmusic_command.png b/Docs/playing_audio/images/004_play_music/1_add_playmusic_command.png new file mode 100644 index 00000000..9359b160 Binary files /dev/null and b/Docs/playing_audio/images/004_play_music/1_add_playmusic_command.png differ diff --git a/Docs/playing_audio/images/005_play_sound/1_play_sound.png b/Docs/playing_audio/images/005_play_sound/1_play_sound.png new file mode 100644 index 00000000..8cc7428d Binary files /dev/null and b/Docs/playing_audio/images/005_play_sound/1_play_sound.png differ diff --git a/Docs/playing_audio/images/005_play_sound/2_wait_until_finished copy.png b/Docs/playing_audio/images/005_play_sound/2_wait_until_finished copy.png new file mode 100644 index 00000000..bb5e7d05 Binary files /dev/null and b/Docs/playing_audio/images/005_play_sound/2_wait_until_finished copy.png differ diff --git a/Docs/playing_audio/images/005_play_sound/2_wait_until_finished.png b/Docs/playing_audio/images/005_play_sound/2_wait_until_finished.png new file mode 100644 index 00000000..1eb54dcd Binary files /dev/null and b/Docs/playing_audio/images/005_play_sound/2_wait_until_finished.png differ diff --git a/Docs/playing_audio/images/006_set_audio_volume/1_drag_music_clip.png b/Docs/playing_audio/images/006_set_audio_volume/1_drag_music_clip.png new file mode 100644 index 00000000..98668e14 Binary files /dev/null and b/Docs/playing_audio/images/006_set_audio_volume/1_drag_music_clip.png differ diff --git a/Docs/playing_audio/images/006_set_audio_volume/2_second_block.png b/Docs/playing_audio/images/006_set_audio_volume/2_second_block.png new file mode 100644 index 00000000..8221dc90 Binary files /dev/null and b/Docs/playing_audio/images/006_set_audio_volume/2_second_block.png differ diff --git a/Docs/playing_audio/images/006_set_audio_volume/3_quieter.png b/Docs/playing_audio/images/006_set_audio_volume/3_quieter.png new file mode 100644 index 00000000..31270ff1 Binary files /dev/null and b/Docs/playing_audio/images/006_set_audio_volume/3_quieter.png differ diff --git a/Docs/playing_audio/images/006_set_audio_volume/4_audio_volume_command.png b/Docs/playing_audio/images/006_set_audio_volume/4_audio_volume_command.png new file mode 100644 index 00000000..c619aaf3 Binary files /dev/null and b/Docs/playing_audio/images/006_set_audio_volume/4_audio_volume_command.png differ diff --git a/Docs/playing_audio/images/006_set_audio_volume/5_add_menu.png b/Docs/playing_audio/images/006_set_audio_volume/5_add_menu.png new file mode 100644 index 00000000..e6abc78e Binary files /dev/null and b/Docs/playing_audio/images/006_set_audio_volume/5_add_menu.png differ diff --git a/Docs/playing_audio/images/006_set_audio_volume/6_link_to_quieter.png b/Docs/playing_audio/images/006_set_audio_volume/6_link_to_quieter.png new file mode 100644 index 00000000..ce8ff5a5 Binary files /dev/null and b/Docs/playing_audio/images/006_set_audio_volume/6_link_to_quieter.png differ diff --git a/Docs/playing_audio/images/006_set_audio_volume/7_green_arrow.png b/Docs/playing_audio/images/006_set_audio_volume/7_green_arrow.png new file mode 100644 index 00000000..4e7e434d Binary files /dev/null and b/Docs/playing_audio/images/006_set_audio_volume/7_green_arrow.png differ diff --git a/Docs/playing_audio/images/006_set_audio_volume/8_output.png b/Docs/playing_audio/images/006_set_audio_volume/8_output.png new file mode 100644 index 00000000..ca1ef1b8 Binary files /dev/null and b/Docs/playing_audio/images/006_set_audio_volume/8_output.png differ diff --git a/Docs/playing_audio/images/007_control_audio/1_create_empty.png b/Docs/playing_audio/images/007_control_audio/1_create_empty.png new file mode 100644 index 00000000..a826f0f8 Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/1_create_empty.png differ diff --git a/Docs/playing_audio/images/007_control_audio/2_rename.png b/Docs/playing_audio/images/007_control_audio/2_rename.png new file mode 100644 index 00000000..1bcbc94f Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/2_rename.png differ diff --git a/Docs/playing_audio/images/007_control_audio/3_drag_clip.png b/Docs/playing_audio/images/007_control_audio/3_drag_clip.png new file mode 100644 index 00000000..ae488ef8 Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/3_drag_clip.png differ diff --git a/Docs/playing_audio/images/007_control_audio/4_add_command.png b/Docs/playing_audio/images/007_control_audio/4_add_command.png new file mode 100644 index 00000000..4e4ea2c7 Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/4_add_command.png differ diff --git a/Docs/playing_audio/images/007_control_audio/5_drag_gameobject.png b/Docs/playing_audio/images/007_control_audio/5_drag_gameobject.png new file mode 100644 index 00000000..6690161a Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/5_drag_gameobject.png differ diff --git a/Docs/playing_audio/images/007_control_audio/6_control_audio_actions.png b/Docs/playing_audio/images/007_control_audio/6_control_audio_actions.png new file mode 100644 index 00000000..caf38d51 Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/6_control_audio_actions.png differ diff --git a/Docs/playing_audio/images/007_control_audio/7_duplicate.png b/Docs/playing_audio/images/007_control_audio/7_duplicate.png new file mode 100644 index 00000000..bebcd9c5 Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/7_duplicate.png differ diff --git a/Docs/playing_audio/images/007_control_audio/8_set_volume.png b/Docs/playing_audio/images/007_control_audio/8_set_volume.png new file mode 100644 index 00000000..21686fcf Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/8_set_volume.png differ diff --git a/Docs/playing_audio/images/007_control_audio/9_final_commands.png b/Docs/playing_audio/images/007_control_audio/9_final_commands.png new file mode 100644 index 00000000..86dec740 Binary files /dev/null and b/Docs/playing_audio/images/007_control_audio/9_final_commands.png differ diff --git a/Docs/playing_audio/images/008_say_audio_tags/1_say_tags.png b/Docs/playing_audio/images/008_say_audio_tags/1_say_tags.png new file mode 100644 index 00000000..02b955cf Binary files /dev/null and b/Docs/playing_audio/images/008_say_audio_tags/1_say_tags.png differ diff --git a/Docs/playing_audio/images/008_say_audio_tags/2_output.png b/Docs/playing_audio/images/008_say_audio_tags/2_output.png new file mode 100644 index 00000000..af601f98 Binary files /dev/null and b/Docs/playing_audio/images/008_say_audio_tags/2_output.png differ diff --git a/Docs/playing_audio/index.md b/Docs/playing_audio/index.md new file mode 100644 index 00000000..d80352ff --- /dev/null +++ b/Docs/playing_audio/index.md @@ -0,0 +1,302 @@ +# Playing Audio {#playing_audio} + +Almost every game benefits from some sound! Often we categorise audio clips into three kinds: + +1. Music +1. Sound effects +1. Speech + +Fungus provides straightforward ways to include all 3 kinds of audio clip in your game, using the techniques presented here. + + +# Sources of free to use audio clips and music +Before you can **add** audio clips to a game you need to get some audio clips. Here are some sources of audio clips to use when learning about audio in Fungus, in case you don't have some of your own to hand. + +The following are some good places online to fine music and sound effects for games. Some are free for any use (including commerical), some are just free for personal use. As always, check the licence of media assets before using them for any commerical products ... + +- [Freesound.org] +- lots of creative commons and royalty free sounds at [SoundBible.com] +- a great list of audio sources in peoples answers to questions at [Answers.unity3d] and [StackOverflow.com] +- mixture of free and paid music sources at [PixelProspector.com] + +You'll find a range of audio clips included inside the Fungus Examples folders: +
+![Fungus Examples audio](./images/001_clips/0_audio_in_examples.png "Fungus Examples audio") +
+ +# Adding audio assets to your project +Once you have some audio clips on your computer, you need to import them into your Unity project. + +##Method 1 (menu) +You can do this one clip at a time, by choosing menu: ```Assets | Import New Asset...``` and navigating to and selecting each clip. + +##Method 2 (drag-drop) +Alternatively you can **drag** files or entire folders into your Unity Project window, and Unity will make a copy of, and then import the dragged files: + +
+![drag audio folder into Unity](./images/002_audio_into_unity/1_drag_folder.png "drag audio folder into Unity") +
+ + + +# Three ways to work with audio in Fungus games +There are 3 main ways to work with audio in Fungus games. These are the Audio commands, the Say command, and gameObjects containing Unity Audio Source components. All three are discussed below: +
+![audio big picture](./images/000_big_picture/1_big_picture.png "audio big picture") +
+ + + + +## List of Fungus audio commands +The range of audio **Commands** you can add to a Block are as follows: +
+![Fungus audio commands](./images/003_fungus_audio_commands/1_audio_commands.png "Fungus audio commands") +
+ +Also you can declare an audio clip that contains the speech voiceover to correspond to text displayed with a **Say** command: +
+![Fungus audio commands](./images/003_fungus_audio_commands/2_say_voiceover_clip.png "Fungus audio commands") +
+ + +## Play Music command +Music sound clips loop, so they are restarted once they have finished playing. Often the first Command in a Block is a **Play Music** Command. Add music to a Block as follows: + +1. (if you have not already done so: Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart). + +1. Add a Play Music Command to the current Block by clicking the Add Command (plus-sign "+" button) in the Inspector, and then choosing menu: ```Audio | Play Music```. + +1. Ensure the Play Music command is selected (green highlight) in the top of the Inspector, and then drag the desired music clip file into the "Music Clip" property in the bottom half of the Inspector: +
+![Add Play Music command](./images/004_play_music/1_add_playmusic_command.png "Add Play Music command") +
+
+ +1. Change the volume as desired +
(the default is 1, values are between 0.0 and 1.0, representing percentages of volume from 0% - 100%). + +1. Play your scene - the music clip should play, and keep looping. + +NOTE: If you wish to start playing the music clip from a known time-point (rather than from the beginning), then enter the desired timepoint in the Inspector property "At Time" for your Play Music command. + + +## Play Sound command +The Fungus Play Sound Command will play a stated audio clip once. With your Flowchart Block selected, click the Add Command button in the Inspector and choose menu: ```Audio | Play Sound```. Drag in a sound effect (we chose the BearRoad sound from the Hunter example): +
+![Play Sound command](./images/005_play_sound/1_play_sound.png "Play Sound command") +
+ +Play the scene, you should hear your sound effect play once. + +Note. The default Fungus setting is for the sound effect to start playing, and while it is playing the next Command in the Block will start executing. However, you if you check the "Wait Until Finished" checkbox, then Fungus will wait until the sound effect has finished playing, before moving on to execute the next Command in the block: +
+![wait until finished](./images/005_play_sound/2_wait_until_finished.png "wait until finished") +
+ + +## Set Audio Volume command + +The default volume for music being played is 1 (100%). However, we can change this easily with the Set Audio Volume command. Do the following: + +1. (if you have not already done so: Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart). + +1. Rename this Block "Play Music". + +1. Add a Play Music Command to the current Block, then drag the desired music clip file into the "Music Clip" property in the bottom half of the Inspector: +
+![sherlock music](./images/006_set_audio_volume/1_drag_music_clip.png "sherlock music") +
+
+ +1. If you play the scene now, the music will play at full volume (1 = 100%). + +1. Now create a second Block in the Flowchart window named "quieter". +
+![new block quieter](./images/006_set_audio_volume/2_second_block.png "new block quieter") +
+
+ +1. Add to this new Block a Set Audio Volume Command. +
+![Add audio volume command](./images/006_set_audio_volume/4_audio_volume_command.png "Add audio volume command") +
+
+ +1. In the properties of the Set Audio Volume Command set the volume to 0.25 (25%). +
+![set audio volume quieter](./images/006_set_audio_volume/3_quieter.png "set audio volume quieter") +
+
+ +1. Select the "Play Music" block, and add a Menu command by clicking the plus-sign add Command button in the Inspector and then choosing menu: ```Narrative | Menu```. +
+![add menu command](./images/006_set_audio_volume/5_add_menu.png "add menu command") +
+
+ +1. Set the Text Property to "Make Quieter" and the Target Block to Block "Quieter": +
+![ menu properties](./images/006_set_audio_volume/6_link_to_quieter.png " menu properties") +
+
+ +1. In the Flowchart window you should now see a green arrow, showing that a Command in Block "Play Music" passes control to Block "quieter": +
+![green arrow](./images/006_set_audio_volume/7_green_arrow.png "green arrow") +
+
+ +1. When you run the scene, the music will start playing at full volume, then when y ou click the "Make Quieter" button, control will pass to the "quieter" block, and you'll hear the music become much quieter after the Set Audio Volume Command has been executed with a value of 25% (0.25): +
+![set audio running](./images/006_set_audio_volume/8_output.png "set audio running") +
+
+ + +## The 3 Unity audio concepts +Unity has 3 different kinds of Audio 'object', that it is worth understanding when working with audio in Fungus (or any other) Unity project: + +1. Audio Clip +1. Audio Listener +1. Audio Source + +### Unity Audio Clip +Unity uses the term Audio "Clip" to refer to the physical sound files (.mp3, .wav, .ogg etc.) that are stored in your Project folder. It is these Audio Clip files that you drag and drop into the "Music Clip" and "Sound Clip" properties in the Inspector Window, when creating Play Music and Play Sound Commands in a Fungus Block. + +### Unity Audio "Listener" +Basically, if you want sound to be played there must be an Audio Listener component inside one of the gameObjects in your scene. The Main Camera of a scene has one by default, so in most cases you just leave this alone and can rest assured that you have an Audio Listener. + +If a scene has no Audio Listener in any gameObject, then no audio will be heard by the user of the game, regardless of how many music and sound clips might be playing. + +Sometimes you may add gameObjects to your scene that contain another Audio Listener component. In this case, Unity will present a warning message stating that more than 1 Audio Listener is present in the scene. If you see such a message, then its best to resolve this problem by disabling all but one Audio Listener... + +If you are working with a 3D game, and/or you wish to present a sophisticated stereo sound experience for your user, then you may need to learn about 3D audio. In such games the 3D "position" of the gameObject containing the Audio Listener becomes important - but don't worry about this if you are just getting started with audio in Fungus. For 3D effects the Audio Listener is like an "electronic ear", so its location determines things like how loud a sound is played (distance from "ear") and left-right stereo balance (which "side" audio is to the "ear") etc. + +### Unity Audio Source +In Unity the link between an Audio Clip (music/sound) file that we wish to be played, and the Audio Listener in the scene is a Unity Audio Source component of a gameObject. However, in most cases Fungus creates one of these if needed, so we don't need to worry about them! + +However, for sophisticated control of music and sound and speech in your game there is the facility to make Fungus have detailed control of Unity Audio Sources. It is an Audio Source component that controls how and when and which part of an audio clip is playing (and whether it should loop or not), and whether it is playing or paused, and when resuming should continue from where paused or restart. The volume of a playing clip can also be controlled by properties of an Audio Source. + +Learn more about audio in Unity at the [Unity Manual Audio Page]. + +## Control Audio command + +The Fungus Audio Commands cover all common music and sound effect actions, for specialist audio work you may need to access the raw (and complicated) power of Unity audio. The Fungus Command "Control Audio" lets Fungus Blocks communicate directly with Unity Audio Source components in any gameObject in the current scene, so your wizard audio team member can do what they need to do with the Unity toolkit, and you can still control playing / looping / volume etc. of the audio in those complex gameObjects. + +The Control Audio Command offers five actions that can be communicated to Unity Audio Source components: +
+![control audio options](./images/007_control_audio/6_control_audio_actions.png "control audio options") +
+
+ +We'll learn about this with a simple Unity gameObject that plays a bear sound two times, first at full volume and then reduces the volume before playing a second time, using three "Control Audio" Fungus Commands. Do the following: + +1. (setup) If you have not already done so: Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename this Block "Control Audio". + +1. In the Hierarchy Window create a new Empty gameObject, choose menu: ```Create | Create Empty```: +
+![create empty](./images/007_control_audio/1_create_empty.png "create empty") +
+
+ +1. Rename this new empty gameObject "GameObject - bear sound" (or whatever sound name makes sense in your project). + +1. Locate your desired audio clip file in the Project window, and (with "GameObject - bear sound" selected), drag a reference to the audio clip from the Project window into the Inspector: +
+![rename empty](./images/007_control_audio/2_rename.png "rename empty") +
+
+ +1. An Audio Source component should now be added in the Inspector to "GameObject - bear sound". Un-check the Play On Awake property in the Inspector (to stop this sound from playing as soon as the scene begins - **we** want to be in control of this Audio Source object...): +
+![audio source added](./images/007_control_audio/3_drag_clip.png "audio source added") +
+
+ +1. With your Flowchart Block selected, click the Add Command button in the Inspector and choose menu: ```Audio | Control Audio```. +
+![Control Audio command](./images/007_control_audio/4_add_command.png "Control Audio command") +
+
+ +1. Drag the "GameObject - bear sound" gameObject from the Hierarchy into the Audio Source property in the Inspector, and select the Wait Until Finished checkbox (so Fungus will wait for the sound to finish playing before moving on): +
+![drag gameobject](./images/007_control_audio/5_drag_gameobject.png "drag gameobject") +
+
+ +1. Note that the default Control action for a Control Audio Command is "Play Once" - we'll leave this property unchanged, since we want our bear sound inside our gameObject to be played once. + +1. If you run the scene now, you'll hear the bear sound play once at full volume. + +1. Since all three of the Control Audio commands we need use a link to "GameObject - bear sound" the fastest workflow is to **duplicate** each Command, and just change the bits we need. So duplicate your Control Audio command by clicking the Duplicate Command button: +
+![duplciate command](./images/007_control_audio/7_duplicate.png "duplicate command") +
+
+ +1. In the newly copied command, change the Command action to Change Volume, and choose a volume of 0.25 (25%): +
+![set volume](./images/007_control_audio/8_set_volume.png "set volume") +
+
+ +1. Once again, make a duplicate of the first Control Audio Command (that Plays the sound). Drag this new Command to be last in the sequence of commands. +
+![another play again command](./images/007_control_audio/9_final_commands.png "another play again command") +
+
+ +1. Now when you play the scene, first the bear sound linked to in the Audio Source component of gameObject "GameObject - bear sound" should play at full volume, then (after having its volume reduced to 25%) it should play a second time at a much reduced volume. + + +## Audio Tags (in Say Commands) + +Since often dialog authors will know just what sound effects or music they wish to associate with their characters utterances, Fungus allows audio-related 'tags' to be embedded in the text of Say Commands. There are four audio related tags: + + {audio=AudioObjectName} Play Audio Once + {audioloop=AudioObjectName} Play Audio Loop + {audiopause=AudioObjectName} Pause Audio + {audiostop=AudioObjectName} Stop Audio + +Using tags like this make it important to carefully **name** the gameObjects in the Hierarchy window. To explore how to control sounds in gameObjects do the following: + +1. (setup) If you have not already done so: Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename this Block "Say audio tags". + +1. In the Hierarchy Window create a new Empty gameObject, choose menu: ```Create | Create Empty```: +
+![create empty](./images/007_control_audio/1_create_empty.png "create empty") +
+
+ +1. Rename this new empty gameObject "audioBearRoar", or whatever sound name makes sense in your project, but avoid spaces in the name of this game object. + +1. Locate your desired audio clip file in the Project window, and (with "audioBearRoar" selected), drag a reference to the audio clip from the Project window into the Inspector. + +1. Un-check the Play On Awake property in the Inspector for the Audio Source component (to stop this sound from playing as soon as the scene begins - **we** want to be in control of this Audio Source object...): + +1. With your Flowchart Block selected, click the Add Command button in the Inspector and choose menu: ```Narrative | Say```. Enter the following for the Story Text property of this Say Command "... and then the bear roared loudly {audio=audioBearRoar}": +
+![Say audio tag](./images/008_say_audio_tags/1_say_tags.png "Say audio tag") +
+
+ +1. Run your scene - the bear sound will play after the text has been displayed: +
+![Say audio tag - output](./images/008_say_audio_tags/2_output.png "Say audio tag - output") +
+
+ + + +[Freesound.org]: http://www.freesound.org/ +[Answers.unity3d]: http://answers.unity3d.com/questions/7743/where-can-i-find-music-or-sound-effects-for-my-gam.html +[SoundBible.com]: http://soundbible.com/royalty-free-sounds-1.html +[StackOverflow.com]: http://stackoverflow.com/questions/1210286/where-can-i-find-free-sound-effects-for-a-game +[PixelProspector.com]: http://www.pixelprospector.com/the-big-list-of-royalty-free-music-and-sounds-free-edition/ +[Unity Manual Audio Page]: http://docs.unity3d.com/Manual/AudioOverview.html diff --git a/Docs/telling_a_story/images/001_characters/1_menu_character.png b/Docs/telling_a_story/images/001_characters/1_menu_character.png new file mode 100644 index 00000000..5badd2a6 Binary files /dev/null and b/Docs/telling_a_story/images/001_characters/1_menu_character.png differ diff --git a/Docs/telling_a_story/images/001_characters/2_new_character.png b/Docs/telling_a_story/images/001_characters/2_new_character.png new file mode 100644 index 00000000..346efa83 Binary files /dev/null and b/Docs/telling_a_story/images/001_characters/2_new_character.png differ diff --git a/Docs/telling_a_story/images/001_characters/3_tom.png b/Docs/telling_a_story/images/001_characters/3_tom.png new file mode 100644 index 00000000..a420cf5c Binary files /dev/null and b/Docs/telling_a_story/images/001_characters/3_tom.png differ diff --git a/Docs/telling_a_story/images/001_characters/4_jerry.png b/Docs/telling_a_story/images/001_characters/4_jerry.png new file mode 100644 index 00000000..74fadd8f Binary files /dev/null and b/Docs/telling_a_story/images/001_characters/4_jerry.png differ diff --git a/Docs/telling_a_story/images/001_characters/5_tom_say1.png b/Docs/telling_a_story/images/001_characters/5_tom_say1.png new file mode 100644 index 00000000..bc7c4003 Binary files /dev/null and b/Docs/telling_a_story/images/001_characters/5_tom_say1.png differ diff --git a/Docs/telling_a_story/images/001_characters/6_four_says.png b/Docs/telling_a_story/images/001_characters/6_four_says.png new file mode 100644 index 00000000..07b29a84 Binary files /dev/null and b/Docs/telling_a_story/images/001_characters/6_four_says.png differ diff --git a/Docs/telling_a_story/images/001_characters/7_tom_jerry_chat.png b/Docs/telling_a_story/images/001_characters/7_tom_jerry_chat.png new file mode 100644 index 00000000..7158ab9c Binary files /dev/null and b/Docs/telling_a_story/images/001_characters/7_tom_jerry_chat.png differ diff --git a/Docs/telling_a_story/images/002_portrait/1_sherlock.png b/Docs/telling_a_story/images/002_portrait/1_sherlock.png new file mode 100644 index 00000000..9e747809 Binary files /dev/null and b/Docs/telling_a_story/images/002_portrait/1_sherlock.png differ diff --git a/Docs/telling_a_story/images/002_portrait/2_add_portrait.png b/Docs/telling_a_story/images/002_portrait/2_add_portrait.png new file mode 100644 index 00000000..06db9891 Binary files /dev/null and b/Docs/telling_a_story/images/002_portrait/2_add_portrait.png differ diff --git a/Docs/telling_a_story/images/002_portrait/4_sherlock_output.png b/Docs/telling_a_story/images/002_portrait/4_sherlock_output.png new file mode 100644 index 00000000..dcee4c94 Binary files /dev/null and b/Docs/telling_a_story/images/002_portrait/4_sherlock_output.png differ diff --git a/Docs/telling_a_story/images/002_portrait/5_john_output.png b/Docs/telling_a_story/images/002_portrait/5_john_output.png new file mode 100644 index 00000000..bb3f084c Binary files /dev/null and b/Docs/telling_a_story/images/002_portrait/5_john_output.png differ diff --git a/Docs/telling_a_story/images/002_portrait/6_say_sherlock.png b/Docs/telling_a_story/images/002_portrait/6_say_sherlock.png new file mode 100644 index 00000000..0f4baa02 Binary files /dev/null and b/Docs/telling_a_story/images/002_portrait/6_say_sherlock.png differ diff --git a/Docs/telling_a_story/images/002_portrait/7_many_portait_images.png b/Docs/telling_a_story/images/002_portrait/7_many_portait_images.png new file mode 100644 index 00000000..579ab734 Binary files /dev/null and b/Docs/telling_a_story/images/002_portrait/7_many_portait_images.png differ diff --git a/Docs/telling_a_story/images/002_portrait/8_two_say_commands.png b/Docs/telling_a_story/images/002_portrait/8_two_say_commands.png new file mode 100644 index 00000000..34b4f097 Binary files /dev/null and b/Docs/telling_a_story/images/002_portrait/8_two_say_commands.png differ diff --git a/Docs/telling_a_story/images/003_stage/1_menu_stage.png b/Docs/telling_a_story/images/003_stage/1_menu_stage.png new file mode 100644 index 00000000..81f8b6a9 Binary files /dev/null and b/Docs/telling_a_story/images/003_stage/1_menu_stage.png differ diff --git a/Docs/telling_a_story/images/003_stage/2_stage_gameobject.png b/Docs/telling_a_story/images/003_stage/2_stage_gameobject.png new file mode 100644 index 00000000..480e93aa Binary files /dev/null and b/Docs/telling_a_story/images/003_stage/2_stage_gameobject.png differ diff --git a/Docs/telling_a_story/images/004_play_music/1_add_playmusic_command.png b/Docs/telling_a_story/images/004_play_music/1_add_playmusic_command.png new file mode 100644 index 00000000..9359b160 Binary files /dev/null and b/Docs/telling_a_story/images/004_play_music/1_add_playmusic_command.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/1_menu_command_portrait.png b/Docs/telling_a_story/images/005_portrait_command/1_menu_command_portrait.png new file mode 100644 index 00000000..00488352 Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/1_menu_command_portrait.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/2_portrait_command.png b/Docs/telling_a_story/images/005_portrait_command/2_portrait_command.png new file mode 100644 index 00000000..68df757b Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/2_portrait_command.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/3_portrait_output copy.png b/Docs/telling_a_story/images/005_portrait_command/3_portrait_output copy.png new file mode 100644 index 00000000..cbbc5316 Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/3_portrait_output copy.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/3_portrait_output.png b/Docs/telling_a_story/images/005_portrait_command/3_portrait_output.png new file mode 100644 index 00000000..a1aeae83 Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/3_portrait_output.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/4_new_command_portrait.png b/Docs/telling_a_story/images/005_portrait_command/4_new_command_portrait.png new file mode 100644 index 00000000..89e19afa Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/4_new_command_portrait.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/5_sherlock_say copy.png b/Docs/telling_a_story/images/005_portrait_command/5_sherlock_say copy.png new file mode 100644 index 00000000..a4f7aa03 Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/5_sherlock_say copy.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/5_sherlock_say.png b/Docs/telling_a_story/images/005_portrait_command/5_sherlock_say.png new file mode 100644 index 00000000..2309578e Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/5_sherlock_say.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/6_john_say copy.png b/Docs/telling_a_story/images/005_portrait_command/6_john_say copy.png new file mode 100644 index 00000000..cfc41335 Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/6_john_say copy.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/6_john_say.png b/Docs/telling_a_story/images/005_portrait_command/6_john_say.png new file mode 100644 index 00000000..dde29e17 Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/6_john_say.png differ diff --git a/Docs/telling_a_story/images/005_portrait_command/7_command_sequence.png b/Docs/telling_a_story/images/005_portrait_command/7_command_sequence.png new file mode 100644 index 00000000..e7935850 Binary files /dev/null and b/Docs/telling_a_story/images/005_portrait_command/7_command_sequence.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/10_correct.png b/Docs/telling_a_story/images/011_menu_maths/10_correct.png new file mode 100644 index 00000000..196adfa8 Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/10_correct.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/11_wrong.png b/Docs/telling_a_story/images/011_menu_maths/11_wrong.png new file mode 100644 index 00000000..ed0172a1 Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/11_wrong.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/1_correct_block.png b/Docs/telling_a_story/images/011_menu_maths/1_correct_block.png new file mode 100644 index 00000000..124ce25d Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/1_correct_block.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/2_edited_say.png b/Docs/telling_a_story/images/011_menu_maths/2_edited_say.png new file mode 100644 index 00000000..bceaa29d Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/2_edited_say.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/3_flowchart_menu.png b/Docs/telling_a_story/images/011_menu_maths/3_flowchart_menu.png new file mode 100644 index 00000000..0170deba Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/3_flowchart_menu.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/4_menu_correct.png b/Docs/telling_a_story/images/011_menu_maths/4_menu_correct.png new file mode 100644 index 00000000..b4f3d96d Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/4_menu_correct.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/5_connected_blocks.png b/Docs/telling_a_story/images/011_menu_maths/5_connected_blocks.png new file mode 100644 index 00000000..59e7ca07 Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/5_connected_blocks.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/6_add_menu.png b/Docs/telling_a_story/images/011_menu_maths/6_add_menu.png new file mode 100644 index 00000000..7e19dbd4 Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/6_add_menu.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/7_wrong_block.png b/Docs/telling_a_story/images/011_menu_maths/7_wrong_block.png new file mode 100644 index 00000000..6a04b667 Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/7_wrong_block.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/8_three_block_menu.png b/Docs/telling_a_story/images/011_menu_maths/8_three_block_menu.png new file mode 100644 index 00000000..8cdfd038 Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/8_three_block_menu.png differ diff --git a/Docs/telling_a_story/images/011_menu_maths/9_menu_running.png b/Docs/telling_a_story/images/011_menu_maths/9_menu_running.png new file mode 100644 index 00000000..ea8fbe9f Binary files /dev/null and b/Docs/telling_a_story/images/011_menu_maths/9_menu_running.png differ diff --git a/Docs/telling_a_story/images/06_camera_background/1_background_black.png b/Docs/telling_a_story/images/06_camera_background/1_background_black.png new file mode 100644 index 00000000..659f6c37 Binary files /dev/null and b/Docs/telling_a_story/images/06_camera_background/1_background_black.png differ diff --git a/Docs/telling_a_story/images/07_background_sprite/1_sprite.png b/Docs/telling_a_story/images/07_background_sprite/1_sprite.png new file mode 100644 index 00000000..f5bbe265 Binary files /dev/null and b/Docs/telling_a_story/images/07_background_sprite/1_sprite.png differ diff --git a/Docs/telling_a_story/images/08_add_view/1_menu_view.png b/Docs/telling_a_story/images/08_add_view/1_menu_view.png new file mode 100644 index 00000000..9007e5a2 Binary files /dev/null and b/Docs/telling_a_story/images/08_add_view/1_menu_view.png differ diff --git a/Docs/telling_a_story/images/08_add_view/2_gameobjects copy.png b/Docs/telling_a_story/images/08_add_view/2_gameobjects copy.png new file mode 100644 index 00000000..b49fc3a3 Binary files /dev/null and b/Docs/telling_a_story/images/08_add_view/2_gameobjects copy.png differ diff --git a/Docs/telling_a_story/images/08_add_view/2_gameobjects.png b/Docs/telling_a_story/images/08_add_view/2_gameobjects.png new file mode 100644 index 00000000..0fe0e4a9 Binary files /dev/null and b/Docs/telling_a_story/images/08_add_view/2_gameobjects.png differ diff --git a/Docs/telling_a_story/images/08_add_view/3_resize_view.png b/Docs/telling_a_story/images/08_add_view/3_resize_view.png new file mode 100644 index 00000000..533155dd Binary files /dev/null and b/Docs/telling_a_story/images/08_add_view/3_resize_view.png differ diff --git a/Docs/telling_a_story/images/08_add_view/4_move_resize_handles.png b/Docs/telling_a_story/images/08_add_view/4_move_resize_handles.png new file mode 100644 index 00000000..08c57dfa Binary files /dev/null and b/Docs/telling_a_story/images/08_add_view/4_move_resize_handles.png differ diff --git a/Docs/telling_a_story/images/08_add_view/5_menu_fade_to_view.png b/Docs/telling_a_story/images/08_add_view/5_menu_fade_to_view.png new file mode 100644 index 00000000..1a0a6f2b Binary files /dev/null and b/Docs/telling_a_story/images/08_add_view/5_menu_fade_to_view.png differ diff --git a/Docs/telling_a_story/images/08_add_view/6_drag_view.png b/Docs/telling_a_story/images/08_add_view/6_drag_view.png new file mode 100644 index 00000000..705d1bb1 Binary files /dev/null and b/Docs/telling_a_story/images/08_add_view/6_drag_view.png differ diff --git a/Docs/telling_a_story/images/08_add_view/7_scene_running.png b/Docs/telling_a_story/images/08_add_view/7_scene_running.png new file mode 100644 index 00000000..5ffc8a1d Binary files /dev/null and b/Docs/telling_a_story/images/08_add_view/7_scene_running.png differ diff --git a/Docs/telling_a_story/index.md b/Docs/telling_a_story/index.md new file mode 100644 index 00000000..71c32ae5 --- /dev/null +++ b/Docs/telling_a_story/index.md @@ -0,0 +1,420 @@ +# Telling a story {#telling_a_story} + +Having got up and running, here are some next steps to get you familiar with the storytelling features in Fungus. + + +## Adding Characters, for use in Say commands + +We can associated words spoken by the Say Command with a particular Character. Consider the following Tom and Jerry scene: + +``` +[Tom] Where is that mouse? +[Jerry] Where is that cat? +[Tom] Aha... +[Jerry] Arrrrggggggg!!!!!!! +``` + +To implement the above in Fungus we need to create and name two Characters. Do the following: + +1. (setup) Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename the Flowchart Block "cat and mouse". + +1. Choose menu: +
```Tools | Fungus | Create | Character```: +
+![Menu create character](./images/001_characters/1_menu_character.png "Menu create character") +
+
+ +1. You should now see a new gameObject "Character" in the Hierarchy window, named Character. +
+![new character](./images/001_characters/2_new_character.png "new character") +
+
+ +1. Ensure gameObject "Character" is selected, and edit its properties in the Inspector. Rename the gameObject to "Character1 - Tom", then in its Character (Script) component set the Name Text to "Tom" and the Name Color to red: +
+![character tom red](./images/001_characters/3_tom.png "character tom red") +
+
+ +1. Repeat the previous two steps to create a second character "Character2 - Jerry", then in its Character (Script) component set the Name Text to "Jerry" and the Name Color to blue: +
+![character jerry blue](./images/001_characters/4_jerry.png "character jerry blue") +
+
+ +1. Now we have our two character gameObjects, we can assign them to any Say commands as appropriate. + +1. Create a Say Command for Tom, with text "Where is that mouse?", setting the Character of this Say command to "Character1 - Tom": +
+![tom say where cat](./images/001_characters/5_tom_say1.png "tom say where cat") +
+
+ +1. Repeat the above step for the 3 remaining statements, for: + - Jerry "Where is that cat?" + - Tom "Aha..." + - Jerry "Arrrrggggggg!!!!!!!" +
Assigning the appropriate Character for each Say Command from the menu of Character gameObjects in the Hiearchy. + +1. You should now have a sequence of 4 Say commands in your Block: +
+![tom jerry conversation](./images/001_characters/6_four_says.png "tom jerry conversation") +
+
+ +1. When you run the scene you should see a sequence of statements, clearly showing who is saying what - both the character name is given, and also that name is coloured according to the properties we set for the character gameObjects (red for Tom, and blue for Jerry): +
+![tom jerry conversation output](./images/001_characters/7_tom_jerry_chat.png "tom jerry conversation output") +
+
+ + +## Listing portrait image(s) for use by Characters + +If you add one or more portrait images to a character, then each Say command for that character can define which of those portrait images should be displayed, alongside the (colored) name of the Character. + +To add portrait images to a character do the following: + +1. (setup) Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename the Flowchart Block "The case of the missing violin". + +1. Create a character, and in the Inspector give your character Name Text (we chose "Sherlock") and a name color. + +1. Now in the Inspector click the Add Portrait button (the plus-sign "+"), to get a 'slot' into which to add a portrait image: +
+![add portrait](./images/002_portrait/2_add_portrait.png "add portrait") +
+
+ +1. Drag the appropriate image into your new portrait image slot (in this screenshot we used the 'condident' image from the Sherlock example project). Also set the direction that the image is facing (left / front / right): +
+![sherlock image](./images/002_portrait/1_sherlock.png "sherlock image") +
+
+ +1. Create a second character (e.g. John, using Name Color blue, and portrait image 'annoyed'). + +1. Now select your Block in the Fungus Flowchart, so you can add some Commands to be executed... + +1. Create a Say command, for your Sherlock Character, saying "Watson, have you seen my violin?" and choosing portrait 'confident' (since this is the only we added to the Character): +
+![sherlock Say command](./images/002_portrait/6_say_sherlock.png "sherlock Say command") +
+
+ +1. Add a second Say command, this time for Character John, saying "No, why don't you find it yourself using your amazing powers of deduction..." and choosing the 'annoyed' portrait for John. +
+![2 say commands](./images/002_portrait/8_two_say_commands.png "2 say commands") +
+
+ + +1. When you run the scene you should see a sequence of statements, clearly showing who is saying both with (colored) name text AND also the portrait image you selected for each Say command: +
+![sherlock output](./images/002_portrait/4_sherlock_output.png "sherlock output") +
+![john output](./images/002_portrait/5_john_output.png "john output") +
+ +As you can see in some of the Fungus Example projects, many games will have a wide range of different portrait images for each character, to allow a full range of visual expression of emotion to support the text of Say commands: +
+![sherlock image list](./images/002_portrait/7_many_portait_images.png "sherlock image list") +
+
+ + +## Add a Stage + +Portrait images can be used in two ways in Fungus. + +- They can be shown as part of the **Say** commands in the Say Dialog. +- Alternatively Portraits can be displayed and moved around the screen inside Fungus **Stages**, using the Portrait Command. + +Create a simple stage that covers the whole game Window as follows: + +1. (setup) Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename the Flowchart Block "stage demo". + +1. Create a Fungus Stage gameObject in the scene by choosing menu: +
```Tools | Fungus | Create | Stage```: +
+![menu add stage](./images/003_stage/1_menu_stage.png "menu add stage") +
+
+ +1. You should now see a new gameObject "Stage" added to the scene Hierarchy. + +1. If you select it you will see its properties in the Inspector. We can leave the default settings, since these are for the stage to cover the whole Game window. There are some child gameObjects inside the Stage, but you don't need to worry about these unless you are doing some advanced customisation of stages for a particular game effect. +
+![stage gameObject](./images/003_stage/2_stage_gameobject.png "stage gameObject") +
+
+ + +Now you have added a Fungus Stage to your scene, you will be able to make large Portrait images appear / move in-out of the screen using the **Portrait** Command in Fungus Flowchart Blocks... + + + +## Displaying Portrait images on stages with the Portrait command + +Once you have a Fungus Stage, and a character then you can instruct Fungus to display / move onscreen the Character Portrait images. To make character images appear as part of a scene do the following: + +1. (setup) Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename the Flowchart Block "sherlock enters dramatically". + +1. Create a Fungus Stage gameObject in the scene by choosing menu: +
```Tools | Fungus | Create | Stage```. + +1. Create a new character, name the gameObject "Character1 - Sherlock", set the Name Text to "sherlock" and the Name Color to green. Add to this character a portrait (we used the sherlock-confident image from the Fungus Example project "Sherlock"). And set the image facing to the appropriate side (in our case: left): +
+![sherlock image](./images/002_portrait/1_sherlock.png "sherlock image") +
+
+ +1. Add a Portrait Command by clicking the Add Command button (the plus-sign "+"), then choosing menu: +
+```Narrative | Portrait```: +
+![add command portrait](./images/005_portrait_command/1_menu_command_portrait.png "add command portrait") +
+
+ +1. You will now see your new Portrait command in the top half of the Inspector, and its Command properties in the bottom half of the Inspector. Note the red exclamation mark at the right of the highlighted (green) Command row - this indicated when a command has one or more required properties that have not been set. We see the error message *"No character selected"*: +
+![new command portrait](./images/005_portrait_command/4_new_command_portrait.png "new command portrait") +
+
+ +1. Set the portrait's character to "Character1 - sherlock", and set the following properties: + - Portrait: confident + - Facing: <-- (left) + - Move: Yes (check the checkbox) + - From Position: Offscreen Right + - To Position: Right +
+![command portrait for sherlock](./images/005_portrait_command/2_portrait_command.png "command portrait for sherlock") +
+
+ +1. When you run the scene, the Sherlock portrait image should move into view having started from Offscreen - Right. The image stops when it gets to about a third the way onto the screen: +
+![sherlock portrait output](./images/005_portrait_command/3_portrait_output.png "sherlock portrait output") +
+
+ +Note, a common Command flow sequence is: + +- to have a character enter on screen (Portrait command), +- then have that character say something (Say command), +- then have another character enter the screen (Portrait command), +- and then that second character says something (Say command). + +Here is just such a sequence for the "Case of the missing violin" two-sentence scenario explored in the recipe to learning how to create Fungus Characters (recipe: Listing portrait image(s) for use by Characters):
+![sherlock portrait output](./images/005_portrait_command/3_portrait_output.png "sherlock portrait output") +
+
+ +Here we see the Play Mode user experience of the output of running such a workflow: +
+![sherlock portrait then say](./images/005_portrait_command/5_sherlock_say.png "sherlock portrait then say") +
+
+![john portrait then say](./images/005_portrait_command/6_john_say.png "john portrait then say") +
+ +We can also see that the character that is Say'ing something, has a WHITE-outline around its Stage portrait, to visually reinforce to the user which character is speaking at any point in time... + + +## Play some music +Music sound clips loop, so they are restarted once they have finished playing. Often the first Command in a Block is a **Play Music** Command. Add music to a Block as follows: + +1. (setup) Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Add a Play Music Command to the current Block by clicking the Add Command (plus-sign "+" button) in the Inspector, and then choosing menu: ```Audio | Play Music```. + +1. Ensure the Play Music command is selected (green highlight) in the top of the Inspector, and then drag the desired music clip file into the "Music Clip" property in the bottom half of the Inspector: +
+![Add Play Music command](./images/004_play_music/1_add_playmusic_command.png "Add Play Music command") +
+
+ +1. Change the volume as desired +
(the default is 1, values are between 0.0 and 1.0, representing percentages of volume from 0% - 100%). + +1. Play your scene - the music clip should play, and keep looping. + +NOTE: If you wish to start playing the music clip from a known time-point (rather than from the beginning), then enter the desired time-point in the Inspector property "At Time" for your Play Music command. + + +## Add menu commands to branch to other blocks +Let's use a Say command above to ask a tricky mathematical question, and demonstrate the Menu command by offering the user a choice been "correct' and "incorrect" answers. Menu commands transfer control to another block - so we'll need to add 2 new blocks to correspond to the 2 answers. +Do the following: + +1. (setup) Create a new scene, add a Fungus Flowchart to the scene, and select the Block in the Flowchart. + +1. Rename the Block in the Flowchart to "Question". + +1. Create a Say command, with **Story Text** to ask the question: "Is 2 + 2?". + +2. Uncheck the "Wait For Click" checkbox (this is so we see the menu options immediately after the Say command has displayed the question): +
+![maths say command](./images/011_menu_maths/2_edited_say.png "maths say command") +
+
+ +3. Create a new Block, named "Correct" which contains a **Say** command with the text "Well done, you are very mathematical!". Click the plus-sign button in the Flowchart window to add a new Block to the Flowchart, rename it "Correct" and then add that Say command: +
+![correct block](./images/011_menu_maths/1_correct_block.png "correct block") +
+
+ +4. Select the "Question" block, and add a Menu command by clicking the plus-sign add Command button in the Inspector and then choosing menu: ```Narrative | Menu```. +
+![add menu command](./images/011_menu_maths/6_add_menu.png "add menu command") +
+
+ +5. With this new Menu command selected (green) in the top half of the Inspector window, set the **Text** to "Yes" and the **Target Block** to your new "Correct" block: +
+![menu command](./images/011_menu_maths/4_menu_correct.png "menu command") +
+
+ +6. You should now see how the 'flow' of commands can change from Block "hello" to Block "Correct" in the Flowchart window: +
+![flow between blocks in Flowchart](./images/011_menu_maths/5_connected_blocks.png "flow between blocks in Flowchart") +
+
+ +7. Add a second new Block named "Wrong", containing a Say command with text "Bad luck, perhaps consider a non-mathematical career path..." +
+![block for wrong answer](./images/011_menu_maths/7_wrong_block.png "block for wrong answer") +
+
+ +8. Now we need to add another Menu command to our "hello" block, offering the user the "No" answer to our maths question, and passing control to Block "Wrong" if they disagree that 2 + 2 = 4. Select the "hello" block, and add a Menu command. With this new Menu command selected (green) in the top half of the Inspector window, set the **Text** to "No" and the **Target Block** to your new "Wrong" block. + +9. You should now see in the Flowchart window how block "hello" can pass control to either block "Correct" or Block "Wrong" - depending on which menu answer the user selects. +
+![block connected to 2 others](./images/011_menu_maths/8_three_block_menu.png "block connected to 2 others") +
+
+ +10. Run the scene, and you should see the Say question appear at the bottom of the screen, and also the two Menu buttons "Yes" and "No" in the middle of the screen. Clicking "Yes" then runs the "Correct" Block's commands, and clicking "No" runs the "Wrong" block's commands: +
+![menu running](./images/011_menu_maths/9_menu_running.png "menu running") +
+
+ +
+![correct screen](./images/011_menu_maths/10_correct.png "correct screen") +
+
+ + +
+![wrong screen](./images/011_menu_maths/11_wrong.png "wrong screen") +
+
+ + +## Change Camera background colour + +Unity cameras determine what the user sees when a scene is running. When nothing is present in all or part of the camera's rectangle a solid "Background" colour is displayed. Unity cameras have a default Background of a medium dark blue colour. You can change this as follows: + +1. (setup) Create a new 2D scene, unless you already have a scene with which to work. + +1. Select the Main Camera in the Hierarchy. + +1. In the Inspector for the Camera component, click and choose a different value for the Background property - often black works well. +
+![camera background colour](./images/06_camera_background/1_background_black.png "camera background colour") +
+
+ +1. Now when any part of the camera rectangle (frustrum) shows no gameOjects then your custom Background colour will be what the user sees. + + +## Add a background sprite + +To add any sprite image file from your Unity Project folder into the current scene, simply drag a reference to the sprite image file from the Project window onto the Scene window, and rotate / resize desired. The sprite will appear as a new gameObject (with same name as Sprite Project image file) in the Hierarchy window: +
+![sprite into scene](./images/07_background_sprite/1_sprite.png "sprite into scene") +
+ +NOTE: You may not be able to see the sprite, because what we see depends on the current settings for the camera. What the camera shows, how it moves etc. can be controlled by Fungus Views and Commmands relating to Views. + + +## Adding and customising a view + +What the main camera of a scene displays to the user, and how it moves etc. can be controlled by Fungus Views and Fungus Commmands relating to Views. A Fungus View is a special gameObject in the Hierarchy, it appears as a green outlined inner rectangle, with two filled green rectangles on the left and the right. The ratio of the outlined inner rectangle is 4:3. The ratio of the outer rectangle (which includes the two filled green left and right rectangles) is 16:9. These two ratios cover almost every common phone, tablet and computer screen width-to-height ratio. So arranging the view so that a background Sprite image looks good for both inner- and outer- rectangles of a view, pretty much ensures your game will look good on any device. Setting the background color of the camera to something like black also means on the rare device that has an odd ratio showing content outside of the view outer rectangle, the game should still look perfectly acceptable. + +To add a view to the current scene do the following: + +1. (setup) Create / Edit a scene that has a Sprite background image gameObject + +1. Choose menu: ```Tools | Fungus | Create | View```: +
+![menu new view](./images/08_add_view/1_menu_view.png "menu new view") +
+
+ +1. Rename this View as "View1". + +1. Use the two white squares to resize the view (it maintains its proportions). Use the center square outline, or vertical and horizontal arrows to move the View around the Scene window. +
+![move and resize handles](./images/08_add_view/4_move_resize_handles.png "move and resize handles") +
+
+![new view](./images/08_add_view/2_gameobjects.png "new view") +
+
+ +1. Ensure the View is selected in the Hierarchy, then position the view so that it is approximately centered on your background sprite image + +1. Resize (and if necessary reposition) the View to be as big as possible, but ensuring that its outer rectangle stays within the bounds of the background sprite. (Note we've tinted the Sprite red so the green View rectangles can be more easily seen in this screenshot): +
+![resize view](./images/08_add_view/3_resize_view.png "resize view") +
+
+ +1. Note: You can also rotate the view with the Unity Rotate tool + +NOTE: Utnil you add a "Fade To View" Fungus command, you still may not see the Sprite in the Game window when the scene plays, since the Main Camera has not been oriented to resize and align with the view. + + +## Add a Fade To View command + +Once you have a Scene that contains some background Sprites and Fungus Views, you are ready to use the Fungus camera related Commands to control what the user sees. The simplest camera control is to make the Game window fade from a solid colour to the Main Camera being sized, positioned (and if necessary rotated) to show a specified Fungus View. Do the following: + +1. (setup) Create / being editing a Scene containing a background Sprite image, and a Fungus View that has been positioned to show all / some of the Sprite. + +1. In the Fungus Flowchart rename the Block "Camera Control". + +1. Add a new "Fade to View" Command to the Block. First click the Plus button in the bottom half of the Inspector window, to add a new Command, then choose menu: ```Camera | Fade To View```: +
+![menu Fade to View](./images/08_add_view/5_menu_fade_to_view.png "menu Fade to View") +
+
+ +1. Now Drag "View1" from the Hierarchy window into the "Target View" property of the Fade to View Command in the Inspector: +
+![assign Target View](./images/08_add_view/6_drag_view.png "assign Target View") +
+
+ +1. (We'll keep the defaults of 1 second and fade From Color of black). + +1. When you run the Scene the Game window should start off solid black, and then slowly the background Sprite image within the View rectangle should fade into view. +1. Now Drag "View1" from the Hierarchy window into the +
+![menu Fade to View](./images/08_add_view/7_scene_running.png "menu Fade to View") +
+
+ diff --git a/Docs/training_course/images/training.png b/Docs/training_course/images/training.png new file mode 100644 index 00000000..d7fbec58 Binary files /dev/null and b/Docs/training_course/images/training.png differ diff --git a/Docs/training_course/index.md b/Docs/training_course/index.md new file mode 100644 index 00000000..3a20ec61 --- /dev/null +++ b/Docs/training_course/index.md @@ -0,0 +1,37 @@ +# Fungus Training Course + + + + +
 
+ +## Course Description + +This course is aimed at anyone who wants to make interactive story based games, but, who doesn't know how to code. + +Fungus is a free Unity 3D plugin that allows non coders (like me) access to some of Unity's core features. + +If you have never used game development software, or if you have struggled with code trying to make games, Fungus and this course are exactly what you need. + +## What are the requirements? + +- A Mac or PC that is capable of running Unity 3D. +- The latest version of Unity 3D (we will talk you through download and install on the course). +- The latest Version of Fungus (We will talk you through download and install on the course). + +## What am I going to get from this course? + +- Over 43 lectures and 8 hours of content! +- You will have a Full working knowledge of Fungus and how it integrates with Unity. +- You will be able to create narrative story games, point and click adventures and hidden object games. +- You will be able to publish your games to Unity’s webplayer and WebGL and have them on your own website, publish them to Android and IOS versions (if you have a Apple developer Licence) and sell them through - Google play or the apple store. +- Most importantly you will be able to do all of this without writing one line of code. + +## What is the target audience? + +- If you don’t know how to code and want to make Interactive Story Games. This course is for you. +- If you’re an artist, illustrator or writer and would like to delve into game development in an easy and approachable manner, this course if for you. +- If you have struggled with code to create games in unity, this course is for you. +- If you're able to code and know your way round unity and love the joy of a visual coding interface, this course is for you. diff --git a/Docs/tutorial_videos/index.md b/Docs/tutorial_videos/index.md new file mode 100644 index 00000000..3c945b1e --- /dev/null +++ b/Docs/tutorial_videos/index.md @@ -0,0 +1,71 @@ +# Tutorial Videos {#tutorial_videos} + +These free tutorial videos cover most of the functionality available in Fungus. + +The videos are also available as a [YouTube playlist](https://www.youtube.com/watch?v=F1vmEtQ7k6M&list=PLiMlyObJfJmUohJ_M2pJhtrNKuNECo2Uk&index=1). Many thanks to [Paul Mc Grath](http://whackala.com) for contributing the videos, and [Eric Chen](https://twitter.com/Eric_hjk) for Chinese subtitles. + +## Fungus Overview + + +## Installing Fungus in your project + + +## Basics of using Fungus + + +## Using Event Handlers + + +## Controlling the camera + + +## 2D graphics with Sprites + + +## Playing music and sound effects + + +## Controlling animations + + +## Narrative based gameplay + + +## Command flow and loops + + +## Scripting scene objects + + +## Using variables to track state + + +## Tweening game objects using iTween + + +## Supporting multiple languages + + +## Editing story text + + +## Using Spine animations + + +## Custom commands and event handlers + + +## Controlling Unity UI objects + + +## Unite Europe 2015 talk + + +## Fungus Live Stream #1 + + +## Fungus Live Stream #2 + + +## Fungus Live Stream #3 +