Phone Menu plugin guide

phoneMenuPluginGuide.md

Phone Menu plugin guide

---

Plugin Overview

This plugin adds a mobile phone (smartphone) menu with an alternative messaging system. You can customize the phone menu by adding items (phone apps) through the Plugin Parameters.

Plugin Customization:

• Customizable Resources: The plugin includes resources located in img\pPhoneMenu. You can edit these resources to suit your needs.
• Visual Customization: Modify the visual appearance of the phone menu and apps by exploring the data\PKD_PhoneMenu folder.

---

Script Calls

General Phone Menu Controls:

• Open Phone Menu: Phone.Show();
• Close Phone Menu: Phone.Hide();
• Disable Phone Menu: Phone.Disable();
• Enable Phone Menu: Phone.Enable();

Managing Apps:

• Add App: Phone.AddApp("ID");

• Remove App: Phone.RemoveApp("ID");

• Open App Directly: Phone.OpenApp("ID");

  Example:

  Phone.AddApp("saveApp");
  Phone.RemoveApp("loadApp");

Phone Customization:

• Change Phone Image: Phone.ChangePhone("NAME");
  (Image should be in img\pPhoneMenu folder)

• Change Wallpaper: Phone.ChangeWallpaper("NAME");

Gallery App:

• Unlock Gallery Picture: Phone.UnlockGalleryPicture("NAME");
  NAME should match the Picture field in the Gallery Picture Plugin Parameter.

• Change Gallery Background: Phone.ChangeGalleryWallpaper("NAME");

Shop App:

• Add Item to Shop: Phone.AddItemInShop("ITEM_ID");
• Remove Item from Shop: Phone.RemoveItemFromShop("ITEM_ID");
• Clear All Shop Items: Phone.ClearShopItems();

Contacts App:

Visual Customization

Edit .json files in folder data\PKD_PhoneMenu\ContactsApp to customize the Contacts App appearance.

How make a Call to contact

• Add contact to Contacts List in Plugin Parameters.
• Set parameter Variable for Call Event to variable ID where you want to store the common event ID. Note: You should specify the VARIABLE ID, not the common event ID. Note: Don't forget to set the common event ID in the variable before making a call.

Using variable ID instead of common event ID allows you change the common event ID in the game during on game and story progress.

• In game, go to the Contact screen and click Call button (or press 'Ok' on keyboard/gamepad).

• You can set how long player will wait for the call to be answered in Plugin Parameters for each Contact.

• When contact answers the call, the phone will show the Talking screen and common event starts.

• When call related common event is finished, the phone will show the End Call screen and after that will return to the Contacts screen automatically.

• You can also end the call manually by clicking the End Call button, but only before the call is started or after it is finished.

Control call process from common event

• Script call: PKD_PhoneMenu.AbortCall()
  This script call will abort the call process.

• Script call: PKD_PhoneMenu.EndCall() This script call will end the call process and return to the Contacts screen.

Note: Those script calls are interupts common event execution, so you can use them in the middle of the common event.

Phone Icon on Map:

• Show Phone Icon: PhoneIcon.Show();
• Hide Phone Icon: PhoneIcon.Hide();
• Enable Phone Icon: PhoneIcon.Enable();
• Disable Phone Icon: PhoneIcon.Disable();

Notifications:

• Show Notification:

  Phone.Notify({image: "NAME", text: "TEXT", textPos: [X, Y], se: "FILENAME" });

  Image should be from the img\pPhoneMenu folder.

  Examples:

  Phone.Notify({image: "Notify_NewMessage"});
  Phone.Notify({image: "Notify_NewMessage", text: "Hello!"});
  Phone.Notify({image: "Notify_NewMessage", text: "Hello!", textPos: [10, 20]});
  Phone.Notify({image: "Notify_NewMessage", text: "Hello!", textPos: [10, 20], se: "Attack1" });

Modal Menu:

• Simple Modal Message:

  Phone.ShowModalMessage("TITLE TEXT", "BUTTON TITLE");

• Simple Modal Choice with 2 Buttons:

  Phone.ShowModalQuestion("TITLE TEXT", "BUTTON 1 TITLE", BUTTON_1_ACTION, "BUTTON 2 TITLE", BUTTON_2_ACTION);

• Modal Menu from Event Body Choices:

  Phone.ShowModalMenu("TITLE TEXT", ID, FromMap?);

  • FromMap: (optional) If TRUE, message body loads from the Event (ID) on Messages Map instead of Common Event ID.

  Examples:

  Phone.ShowModalMessage("Autosave done!", "OK");
  Phone.ShowModalQuestion("Load autosave?", "Yes", 1, "No", "console.log('canceled')");
  Phone.ShowModalMenu("Select wallpaper", 4, false);

---

Messaging System

Adding a New Message:

• Add Message:

  Phone.AddMessage("A", "N", ID, FromMap?);

  • A: Avatar image name
  • N: Sender’s name
  • ID: Common event ID for conversation content
  • FromMap: (optional) If TRUE, message body loads from the Event (ID) on Messages Map instead of Common Event ID.

  Examples:

  Phone.AddMessage("avaActor1", "John", 22); // From Common Event ID 22
  Phone.AddMessage("avaActor2", "Alice", 4, true); // From Messages Map, event 4
  Phone.AddMessage("avaKasey", "\\N[6]", 1, true); // You can use control character for name

Other Messaging Functions:

Script calls:

• Check for New Messages: Phone.IsHaveNewMessages();
  Returns true if there are any unread messages.

• Change Messages Background: Phone.ChangeMessageWallpaper("NAME");

• Delete Conversation:

  Phone.DeleteConversation("N");

  Example:

  Phone.DeleteConversation("John");

Speaker face and name

If you set Face and Name fields in Show Text command, the plugin will automatically use them as the sender's avatar and name in the message system.

You can use control characters \N[x] in the Name field to show the name of the character speaking.

Wait for Message:

To show the text "N is writing..." before the Wait command, you need to add the following script call BEFORE the Wait command:

• this.phoneSetWaitFor('name');

Change Message Style:

• this.phoneSetMessageStyle('style');
  Change the message style to the specified style.

• Style must be defined in the file data\PKD_PhoneMenu\MessagesApp\NUI_MessagesStyles.json

Show image in message:

• this.phoneSendImage('imageName');
  Show an image in conversation.

• Right after this script call you should add Empty Message Show Message command with empty text

• Image should be in pictures folder.

Show default system messages in conversation:

• You can now display regular messages by calling:
• this.phoneSwitchToDefaultMessages();

All subsequent messages will be shown using the default message system. To switch back to the Messages App, use:

• this.phoneSwitchBackToMessages();

Text Drawing Methods:

• Extended Text Mode:

  • Enable all RPG Maker control characters (colors, images, etc.) by setting Extended Text to TRUE in Plugin Parameter.
  • Note: This method might have issues with word wrap and text auto height. Use /n to manually adjust text height.

• Simple Text Mode:

  • Set Extended Text to FALSE for simpler text configuration, more flexible styles, and better word wrap.
  • Supported control characters: \G, \N[x], \P[x], \V[x]

Extra Control Characters (Only if "Extended Text" is TRUE):

• Show Icon with Custom Size:

  \Isz[INDEX, SIZE, DX, DY]

  Example:

  \Isz[89, 20, 0, 0]

• Show Picture (from Pictures folder):

  \Psz[NAME, WIDTH, HEIGHT, DX, DY]

  Example:

  \Psz[Actor1_1, 220, 220, 0, 0]

Event Commands Support

The application runs its own internal command interpreter, so theoretically, all commands are supported. However, you should avoid commands that require a map scene, as the phone operates in its own scene. Supports label jumps, conditions, and complex nested choices.

---

Save and Load Apps

Since update 2.1 you can use Save and Load apps to save and load the game. If you update from the previous version, you need to add these apps manually in Plugin Parameters.

Go to the Apps -> Edit SaveApp or LoadApp -> Set Common Event to Phone.StartApp('saveApp') or Phone.StartApp('loadApp').

---