PLK_RelationshipSystem

No need to set any window if you don't want to. I have attached a demo file.
If you need anything, please feel free to contact us.

1. Installation and Initial Setup

Step 1: Install the Plugin

• Copy the PLK_RelationshipSystem.js file into the js/plugins/ directory of your RPG Maker MZ project.
• Open RPG Maker MZ, access the Plugin Manager, and click on "New Plugin". Choose PLK_RelationshipSystem from the list.
• Ensure the plugin is turned on by checking the "ON" box.

Step 2: Configure Basic Parameters

• In the Plugin Manager, locate defaultFirstName. This is the text that will appear in the main menu as an option to open the custom relationship scene. You might set it to "RelationshipSystem" or any other desired label.
• Next, configure the Sort Buttons Settings. These buttons will appear in your custom scene, enabling sorting of items. Use the provided structures to set button images, positions, sizes, and associated actions.

Note: Before proceeding with further customization, review the plugin parameters to ensure they align with your intended design. This initial configuration sets the foundation for all subsequent customizations.

2. Using Plugin Commands to Control the System

The PLK_RelationshipSystem plugin exposes several commands to manipulate its functionality during gameplay. Here's a detailed explanation of each core command, with guidance on how and when to use them.

A. Opening and Closing the Custom Scene

Command: openCustomScene

• Purpose: Opens the custom relationship scene.
• How to Use: Call this command from an event, script, or another plugin to present the custom scene to the player.
• Effect: The scene (Scene_CustomSystem) is loaded, initializing various windows and preparing to display the list of items and relationships.

Note: Ensure that the system is enabled through enableCustomSystem before trying to open the scene if you need it to appear as an option in the main menu.

B. Enabling and Disabling the System

Command: enableCustomSystem

• Purpose: Activates the custom system option in the main menu.
• How to Use: Use this command to make the relationship system accessible via the main menu.
• Effect: The main menu command for the custom system appears or refreshes, allowing players to select it.

Command: disableCustomSystem

• Purpose: Deactivates the custom system option in the main menu.
• How to Use: Use when you want to hide or disable the relationship system from players.
• Effect: The custom system option is removed from the main menu.

C. Adding Items from Events

Command: addListItemFromEvent

• Purpose: Manually add a new item to the relationship system using data from a specific event.
• Detailed Steps:
  1. Specify the eventId to identify which event to use.
  2. Provide the text that will be displayed as the item name.
  3. Write a description for the item. Use \N to insert line breaks.
  4. Optionally, provide a mapName; if omitted, the current map’s name is used.
  5. Enter a commonEventId to associate a common event with this item.
  6. Specify relationships as a formatted string like "Friend:1:34,Enemy:2:45" where each relationship has a name, a variable ID, and an icon ID.
  7. Provide a backgroundImage filename for the item's background layer.
• When to Use: When you want to add an item programmatically, perhaps after a specific event or condition is met in the game.
• Example Use-Case: After defeating a boss, you might add a special item "Sword of Valor" with relationships to certain characters using this command.

Command: addListItemFromEventWithStructRels

• Purpose: Similar to the previous command but accepts a structured array of relationships.
• Detailed Steps:
  1. Follow similar steps as addListItemFromEvent.
  2. Instead of a string, supply the relationships parameter with a JSON array of relationship objects, each containing name, varId, and iconId.
• When to Use: When you need to add multiple relationships in one go without manually formatting a string.
• Example Use-Case: Add an item with several relationships at once by passing an array like [{"name":"Ally","varId":3,"iconId":12},{"name":"Rival","varId":4,"iconId":22}].

D. Customizing Window Appearance and Behavior

Command: setWindowSettings

• Purpose: Adjusts various settings for a specified window in the custom scene.
• Detailed Parameters and Usage:
  • windowName: Choose which window to configure (e.g., listWindow, descriptionWindow, etc.).
  • x, y: Set the position of the window on the screen.
  • width, height: Define the dimensions of the window.
  • itemHeight: Specify the height allocated to each item within list-like windows.
  • backOpacity, opacity: Control the transparency of the window background and overall window.
  • windowSkin: Provide a custom skin file for the window.
  • startDirection, exitDirection: Decide the direction from which the window will slide in when opened and slide out when closed. Options: none, top, bottom, left, right.
  • slideEnabled, slideFrames: Enable or disable sliding animations and set how many frames the slide takes.
  • itemBackgroundColor: Set the fill color for item backgrounds.
  • itemBackgroundShape: Choose a shape for the item background (e.g., rectangle, circle, etc.).
  • itemBackgroundBorderColor, itemBackgroundBorderWidth, itemBackgroundBorderScale: Customize the border appearance around item backgrounds.
• How to Use: Use this command in an event or script to change the appearance and behavior of a specific window in real-time.
• Example: As provided earlier, configure listWindow properties to change its size, position, background shape, and other attributes.

You can edit the UnlimitedCustomShapes file to draw the background image if you want, it should be placed above the PLK_RelationshipSystem.

E. Setting Fade In/Out for Scenes

Command: setFadeSettings

• Purpose: Configures whether scenes will fade in and out and sets the duration of these effects.
• Detailed Parameters:
  • useFadeIn: Enable or disable fade in at the start of the scene.
  • fadeInDuration: Specify how long the fade in should last, measured in frames.
  • useFadeOut: Enable or disable fade out when exiting the scene.
  • fadeOutDuration: Specify the fade out duration in frames.
• How to Use: Call this command before opening a scene to ensure the desired fade effect settings are applied.

F. Managing Background Images

Command: setSceneBackground

• Purpose: Sets a custom background image for the entire custom scene.
• How to Use: Provide a filename for the background image. The scene will load this image as the main background layer.

Command: setDefaultBackground

• Purpose: Enables the use of a default background image for items or scenes that do not have a specific background set.
• Detailed Parameters:
  • enabled: Boolean to toggle the use of a default background.
  • imageName: Filename of the default background image to be used.
• How to Use: Use this command to ensure there's always a fallback background image, improving visual consistency.

G. Bulk Operations on Items

Command: addAllListItemsFromMapWithDefaults

• Purpose: Automatically adds all items from the current map’s events into the system using default settings where necessary.
• Parameters:
  • defaultDescription: The description to apply to items that lack their own.
  • defaultCommonEventId: A fallback common event ID for items without a specified common event.
  • defaultRelationships: Relationships in the form "name:varId:iconId, ..." to apply if not provided by the event.
  • defaultBackgroundImage: A default background image to use for items.
• How to Use: This command is ideal for scenarios where you want to quickly populate the relationship system with all items from a map without manually adding each one.

H. Sorting Items

Command: sortListItems

• Purpose: Sorts items currently in the system based on specified criteria.
• Parameters:
  • sortBy: Determines the sorting criterion (nameAsc, nameDesc, relAsc, relDesc).
  • sortOrder: Reserved for future use (currently not affecting the sort logic).
• How to Use: Trigger this command whenever you need to reorganize the list for better navigation or clarity.

I. Changing Window Skins Dynamically

Command: setWindowSkin

• Purpose: Changes the skin (appearance) of a specified window at runtime.
• Parameters:
  • windowName: The target window to change (e.g., listWindow, descriptionWindow).
  • windowSkin: The file name of the new skin located in img/system.
• How to Use: Use this command to alter the look and feel of windows without restarting the scene, allowing for dynamic theme changes or responses to in-game events.

3. Advanced Behaviors and Features

A. Automatic Event Parsing

As players interact with events on the map, the plugin automatically checks event note tags to create or update list items. This parsing happens in the background:

• When the player starts an event, the system checks for tags like <ListItem:>, <Description:>, and others.
• If the tags exist, a new item is created with the specified details or an existing item is updated.

Benefit: Developers can embed item data directly in events, reducing the need for manual plugin command calls.

B. Item Background Customization

Using the setWindowSettings command, you can specify how each item in a list should look:

• Color and Shape: Define itemBackgroundColor and itemBackgroundShape to change the fill and form of the background behind each list item.
• Border Styling: Adjust itemBackgroundBorderColor, itemBackgroundBorderWidth, and itemBackgroundBorderScale to fine-tune the border around items.
• Integration with ShapeDrawer: If the ShapeDrawer plugin is installed, the system will use it to draw the specified shapes. If not, it logs a warning and falls back to basic behavior.

C. Controller and Input Support

The plugin supports Xbox controller inputs, mapping the Start button to open the relationship scene and using other buttons for sorting:

• Start Button: Opens the custom relationship scene.
• LB/RB/LT/RT: Sort items in different orders (A-Z, Z-A, relationship ascending/descending).

Furthermore, in the Scene_Relationship, input methods such as mouse, touch, keyboard, and joystick are integrated for a seamless experience:

• Mouse/Touch: Buttons respond to clicks and hover effects, and windows support dragging for scrolling.
• Keyboard: Keys mapped to actions like "Get All", "Switch", "Info", and "Back".
• Joystick: Analog stick movements allow scrolling, and buttons trigger corresponding actions.

D. Dynamic Window Sliding and Transitions

Windows in the custom scene slide into view based on configured directions:

• Sliding In: When the scene opens, each window can slide in from a specified edge (top, bottom, left, right), providing a dynamic entrance.
• Sliding Out: Similarly, when closing the scene, windows slide out towards configured exit directions.
• Configuration: These behaviors are controlled by startDirection, exitDirection, and slideFrames within the setWindowSettings command.

4. Practical Workflow Example

Scenario: You want to add a new item "Ancient Amulet" to the system when a player interacts with a specific event, then open the relationship scene where players can view and sort their items.

Steps:

1. Event Setup:
   • In the event that gives the "Ancient Amulet", add note tags:
   • <ListItem: Ancient Amulet> 
   • <Description: A mysterious amulet from ancient times.> 
   • <MapName: Forgotten Temple> 
   • <CommonEvent: 5> 
   • <Relationships: Ally:7:20, Mentor:8:22> 
   • <BackgroundImage: amulet_bg> 
   • <BackgroundScene: temple_bg>

    2. Adding the Item:

• Use an event command to call the plugin command addListItemFromEvent or let the auto-parsing handle it via interaction.

   3.Customize Window (Optional):

• Before opening the scene, you might want to adjust the list window settings. Use setWindowSettings to customize the appearance, shape, and behavior of the list window.

  4.Open the Scene:

• Trigger the openCustomScene command to display the relationship scene.
• The scene loads with the "Ancient Amulet" item displayed in the list, showing its description, map name, character image, and relationships.

  5.Sorting Items:

• While in the scene, use controller buttons or mouse clicks on sort buttons to sort items alphabetically or by relationship metrics.

  6.Interacting with Items:

• Players can select an item to view details, trigger associated common events, or swap items within the relationship scene using available UI elements.