Entities & Action Types

As you already know, VNgen is built upon the Quantum framework by XGASOFT and provides a custom implementation of qScript with its own events and collection of actions.

VNgen actions are categorized into groups, where each group relates to a separate entity. Currently, there are 10 primary entity types and 4 sub-types in VNgen:

  • The Perspective Camera
  • Scenes
  • Characters
    • Character Attachments
  • Emotes
  • Textboxes
  • Text
    • Labels
    • Prompts
  • Buttons
  • Options
  • Audio
    • Vox
  • Effects

Each entity may have as many as 15 actions or even more, but don't worry: while it might seem like a lot to learn, most VNgen actions and functions are standardized, so you only need to familiarize yourself with one entity to have a basic grasp on all of them. There are exceptions, however, so be sure to read the full reference guide to get the most out of VNgen.

In general, each entity possesses functions to...

  • Create a new instance of an entity
  • Modify an existing entity's position, scale, rotation, and color blending
  • Replace an existing entity with a new one
  • Destroy an existing entity
  • Animate an existing entity
  • Deform an existing entity
  • Apply a shader on an existing entity

Some actions have multiple variants to suit different needs. But again, these are mostly standardized across other entities. The best example of this is extended functions, which provide the same functionality as their simpler counterparts while extending the number of available options to customize the entity being modified.

Example

vngen_textbox_create("textbox", spr_textbox, 0, 1080, 0, trans_fade, 3);
vngen_textbox_create_ext("textbox", spr_textbox, orig_left, orig_bottom, 0, 1080, 0, scale_stretch_x, trans_fade, 3, ease_cubic_out);
caution

This example is merely to demonstrate what the two variations of 'create' actions look like side-by-side.

Because both simplified and extended scripts serve the same purpose, they should never be used to create the same entity twice as shown in the example above.

In the example above, both action scripts will create a new textbox named "textbox", display it at the bottom of the screen, and fade in with a duration of 3 seconds. However, there are a few key differences in the way each customizes the way the textbox is displayed:

  • The extended script overrides the sprite alignment (or origin point) in real-time, while the simplified script adopts the default origin point assigned to the sprite named 'spr_textbox'.
  • The extended script stretches the sprite to always fill the screen horizontally, regardless of resolution, while the simplified script displays the textbox sprite at its native resolution.
  • The extended script modifies the transition animation timing with an ease mode, while the simplified script uses linear timing by default.

Each of these properties will be covered in detail later, so don't worry about all the extended options for now. This just goes to show why multiple versions of the same function exist: VNgen grows with you the more you learn about it!

In the end, simplified and extended actions are all just different ways to perform the same fundamental operations: create, modify, replace, animate, destroy. Learn these operations, and you'll be creating with VNgen in no time!