VAM VERSION WARNING: The last version of VAM is needed for the plugin.
How to use
- Open or create a scene.
- Create a new empty atom
- Select the empty atom and go in the plugin tab
- Add one of the plugins from VAMStoryto the atom using:
- vamstory.cslist ( story and dialogs )
- vamstory_actions.cslist ( button, toggle and slider panels/walls )
- vamstory_director.cslist ( triggers management )
You can also download HZMDemos and test the two scenes included to help you figuring out the plugin.
VERY IMPORTANT USAGE WARNING
VAMStory needs all it's atoms to be ON at all times. Either directly (the empty holding VAMS scripts) or indirectly (parent atom) More information here.
What is this ?
VAMStory is a plugin that allows story creation with dialogs. It is also made in a way that will help you control the flow of your scene. If you like RenPy stories, then as @VRStudy said, this is the VaMPy of VaM.
VAMStory is not limited to dialog and story creation. It also features several other plugins to control your scene:
- VAMStoryActions to create buttons, toggles and sliders panels/walls (handy even for non-story driven scenes).
- VAMStoryDirector to create and manage triggers to control the flow of the scene.
VAMStory
The concept
VAMStory revolves around a design based on groups containing dialogs. Like this:
But groups also allow the creation of answers, so you could imagine a story in a more complex manner like this:
To summarize the base concept :
- You create groups
- In every group you can create several dialog lines
- Every group can contain up to three answers
Base creation process
When the base story is created (if you start from scratch in a new scene), you will already have a group and a first basic line created.
(1) Group/Dialog controls helps you control the content, you can navigate throught dialogs or groups, create or delete them.
Dialog Line ID allows you to select one of the dialog in the current group.
Dialog Group ID allows you to select on of your groups.
When you'll change this dropdowns, the left column will update to show you the proper dialog.
(2) The left column, is dedicated to the dialog content.
You can type the text, and customize the dialog appearance from delay, triggers, to avatar image or position.
In the Group/Dialog controls, you have two important buttons that helps you iterate quickly:
- Test current group allows you to immediately start the current group in the scene. Know that it respect everything, so it will trigger the group trigger, first dialog show trigger and so on.
- Edit displayed dialog is a shortcut for the plugin UI. Let's imagine you're doing a big story and you have a lot of dialogs. When you're testing a dialog in the scene, you notice a typo in the text. You might not remember the ID of the group or the dialog, so... you just open the plugin, click on this button, and it will immediately select the correct group and dialog displayed in the scene.
The Source/Target dropdown is meant for you to select your wanted dialog. The ID inside means "GroupID_DialogID". In this case, Group 1 Dialog 0 has been chosen.
The system works in two ways. If you hit copy to current dialog. It will grab all the dialog data selected in Source/Target and paste it in your currently selected dialog.
If you hit transfer to selected dialog, it will grab all the currently selected dialog data and send it to the selected dialog in Source/Target.
There is no undo, so be careful with the button you hit
These options are group based. They will not change per dialog. ("duh" you might say, but I prefer to be crystal clear)
Save group position will allow to save the atom position inside the scene. The atom will be moved at this position when the group starts.
Edit Group Trigger allows you to add triggers for this group. It will be executed also when the group starts just like the group position.
And the answers are pretty simple. You can enable up to three by checking the boxes. Type some text and add a trigger to do something when the player makes his choice.
It is important to know that answers will only show up with the final dialog line of a group.
Base scene use
I'm not gonna go into details for the global options. They are more or less self-explanatory. One thing is important tho, it's the (1) Edit Story Trigger.
This trigger is executed when the scene has finished loading and VAMStory is completely loaded and ready.
This is the place where you would put the first group that has to start and pretty much anything you would need when your scene starts.
This might be also a perfect way to reset a story if you make a button "restart" at the end of your scene.
During scene gameplay, VAMStory behaves like this:
- The main dialog area auto-skip to the next dialog of the group when clicked IF you're not on the last dialog line of the group.
It also executes the on click dialog trigger. - When the group reaches the last dialog line, it will not skip to the next group. You will have to create your own trigger to go to another group.
- Answers do the same: they don't have any behavior by default, you will have to create your own trigger to do something.
- The tiny eye hides the UI so that your awesome players can enjoy your awesome boobz touching animations without a UI in their face.
Manual triggers
VAMStory manual triggers allows a couple of things:
Start Dialog Group ID allows to start a dialog group. This is what you should use to start your story, or change group.
Show Dialog UI and Hide Dialog UI, shows... and hide... the dialog UI in the scene. This is another way to hide it completely if you'd wanted to use your own buttons to do that. It will keep the current state it's in while hidden.
Execute Story Trigger... well will execute the story trigger. As mentionned, this is the perfect way to reset your story.
All options below starting with Global_Opt_xxxx can be modified during runtime if you want. All other storables starting with Dial_xxxxx are the plugin datas. Since there is no easy way to hide them with VaM's api they are visible... there is no point using them during a scene playthrough.
Advanced use cases
I initially wanted to add appearance customization on a per dialog basis. But this would make the UI extremely big and complex to approach (and VaM micro UI size does not help). Since it is unlikely to be needed everytime, this is where manual "triggers" are pretty neat.
As you can change the global options, you could use the group or dialog triggers to operate changes while the discussion goes on. Like this for instance:
- At Dialog 0 you could set a trigger that changes the font and background color
- At Dialog 3 you could set a trigger that changes the font and background color for Ella's clone.
Don't limit this approach to when dialogs shows up. You could do it on click, on groups, on answers... whatever you need.
With all the triggers included you're pretty much free to make crazy branching stories. You could also use several VAMStory plugins in your scene and use other plugins handling logic to start one or another story.
The possibilities are endless, only your imagination is the limit.
Dialogs and Auto-skip feature
Since 1.32, dialogs in VAMStory can have an auto-skip delay. VAMStory handles the system automatically for standard dialogs or the three questions at the end of a group.
Here are a couple of things you need to remember when using auto-skip:
- The auto-skip is just like clicking on the dialog window... but automatically. So if you want actions to occur either on click or auto-skipping, edit the On Click Trigger for the dialog.
- If you use an auto-skip delay at the end of a group, and you use in combination a panel from VAMStoryActions, you need to use the action Clear Autoskip dialog timer in each button of the VAMStoryActions panel. If you don't, the normal behavior of the dialog will occur EVEN IF you have clicked on one of the actions.
- The Clear Autoskip dialog timer action can be used to stop an auto-skip timer from any source (a button, a plugin, whatever you can imagine).
VAMStoryActions
The concept
VAMStoryActions is a way to reduce the number of atoms you have to create to add a user interface inside a scene.
With a few clicks, you can create a big panel of buttons, toggles and sliders.
This is an extremely efficient way to manager tiny or huge user interface in your scene. Which means, this plugins works for either story-driven scenes AND non-story driven scenes. For instance, scenes focused on character customization could be done and controlled in less than a handful of minutes compared to the native atom UI system (and with way more flexibility and customization settings).
You can use VAMStoryActions as a simple standalone atom, allowing you to place it anywhere in the scene. Or as an hidden atom to "steal it" when a VAMStory group reaches the answer phase.
Video tutorial (panel)
Using as additional buttons for VAMStory
This can be done on every group.
You have the exact same freedom on your VAMStoryActions as a normal "standalone" panel. You can customize the actions, the colors, text, material... so that it fits in your story user interface.
There is no limit on the number of VAMStoryActions present in a scene, so feel free to use it as much as you want to really customize the story experience.
POI System
Since 1.26, Actions can behave like a POI (point of interest). This could be a solution to make like a scavenger hunt to find interactable spots in a scene, or simply draw the attention of the player.
Just check POI Enabled and set your options.
POI Type: the appearance of the POI while hidden.
POI Behavior: Distance, Look Direction or both. Distance will enable the action panel if you are close enough no matter where you are looking. Look direction will enable the action panel if you are looking at it. Both will take distance and look direction in account before showing it.
POI Activation distance: the maximum distance at which the action panel is visible. Above that distance, the panel will hide and show the POI animation.
POI display distance: the maximum distance at which the poi animation is visible. Above that distance, the POI animation will deactivate.
You should always keep the POE activation distance lower than the POI display distance.
POI Look margins: left and right margin for the look at direction. The higher the number the more the player needs to look at the POI directly to show it.
POI vertical offset: a bit of vertical offset if you want to put the POI animation on a table and display the Action panel above for instance.
Header and Footer
The Header and Footer options allows you to add either a text box above your actions, a global slider below your actions. Or both if you want.
The header text has pretty much the same options as the actions and is styled independently. It is not meant to be interactive, it can be either a title for the panel, or a mini-story for your actions.
This header text or slider will also transfer below a VAMStory panel if you're using that feature.
General tips, tricks & recommandations
Avatars (or pictures)
Like some people on the hub tend to think: pushing 4K or 8K textures is not a good move everywhere. For avatars and any icons/pictures you can customize in VAMStory, I suggest keeping reasonable resolutions. Especially since you will use unoptimized pngs or jpgs (they are not "compiled textures" like in the engine).
For avatars, a resolution of 512 is good enough (and already huge). And to be honest: for any non-important textures, you should never go over 1024.
Keep that in mind for your final .var size but also for the amount of VRAM huge avatars are going to consume.
For pngs, you got an optimization guide I wrote a while ago if needed.
Extra huge special thanks
First and foremost, I can't thank enough @Spacedog again. He is the reason why this plugin exists, and all his ideas and long hours spent writing and scripting story driven content has made this plugin really cool.
I can't also thank enough other creators on the hub ( like @PetaZwega for instance ) who gave me ideas while playing through their awesome story driven scenes.
Also a huge thanks to @VRStudy to send me a code snippet for the follow system.
And finally, @Saint66, @ilovebooties, @atani, @Spacedog... thank you so much for the beta-testing. This is one of the most precious thing ever. And this helped me a lot to release something more stable! <3
Again: reviews are not a report section, your review should be limited to "Does not work with subscenes" eventually, but full reports should be written in the discussion.