Your portals. Your colors. Your rules!

Description

MultiPortals is a powerful VScript-driven instance for Portal 2 that allows map makers to implement fully customizable, multi-colored portal pairs. Break free from the standard blue and orange! Define unique colors, effects, and behaviors for up to 127 different portal pairs, all controlled directly within the Hammer editor.

See It in Action!

Check out the official demonstration video to see what MultiPortals V2 can do:

Why MultiPortals?

MultiPortals is the most flexible and easy-to-use solution for customizing portals in Workshop maps:

• Fully VScript-Driven: No complex entity logic. The instance is stable, efficient, and easy to configure.

• Custom Portal Colors: Define any color you want for each portal using simple RGB values.

  🎥 Video: Custom Colors Demo

  frame3.mp4-compressed.mp4

• Dynamic Lighting: Portals cast beautiful, smooth, colored light on world geometry and models. (This is optional and can be disabled for performance).

  🎥 Video: Dynamic Lighting Demo

  frame5.mp4-compressed.mp4

• Support for up to 127 different portal pairs with individualized settings!

  🎥 Video: Multiple Portal Pairs Demo

  frame4.mp4-compressed.mp4

• Customizable Effects:

  • A stylish, smooth portal closing animation.
  • Use the auto-colored default portal particles or specify your own custom particle effects.
  • Per-portal colored ghosting effect.
  🎥 Video: Ghosting Demo

  frame6.mp4-compressed.mp4

• Advanced Control:

  • Activate/deactivate static portals using I/O commands. Perfect for button-activated puzzles.
  • A simple VScript API to interact with portals from your own scripts.

• Highly Configurable: Control everything from portal ID and colors to brightness and optional features right from the func_instance properties.

Installation

1. Download the latest release from the Releases Page.
2. Extract the contents of the CustomContent folder into your .../Portal 2/portal2/ directory. This will add the necessary scripts and materials files.
3. Copy the multiportals.vmf file from the downloaded archive into your Hammer instances folder (e.g., .../sdk_content/maps/instances/).
4. When your map is ready, pack the content from CustomContent into your BSP map.
5. Don't forget to give me a credit in the description :D

If you want, you can customize assets files to get more unique portal pairs!

Usage in Hammer

1. Create a func_instance entity in your map.
2. In the VMF Filename property, browse to and select the multiportals.vmf instance file.
3. (CRITICAL) Give the func_instance a unique Name (e.g., multiportals_pair_1). This name is used as a prefix for all its child entities.
4. Go to the Replace tab in the entity's properties to configure your portal pair.

Instance Parameters (Replace Keyvalues)

Use the Replace tab to set these parameters.

Key	Description	Example Value
$portal-id	(Required) A unique ID for this portal pair (0-127). This sets the portalgun_linkage_id. Do not repeat this ID across other instances.	1
$portal1-color	The color of the first portal in R G B format.	255 128 0 (Orange)
$portal2-color	The color of the second portal in R G B format.	128 0 255 (Purple)
$portals-color-scale	A brightness multiplier for the portal color. Useful for HDR.	1.5
$withGhosting	Enable (1) or disable (0) the portal ghosting effect.	1
$withDynamicLight	Enable (1) or disable (0) dynamic lighting. Disable for better performance.	1
$custom-edge-particle	The name of a custom particle system for the portal's edge. Leave empty to use the default, auto-colored particle.	my_custom_portal_fx

Advanced Usage

Controlling Static Portals with I/O

You can open and close the portals from this instance using inputs. This is perfect for puzzles that don't use the player's portal gun. The target names for the portals are generated automatically based on the instance name:

• First Portal: [Instance Name]-portal1
• Second Portal: [Instance Name]-portal2

Available Inputs:

• FireUser1: Opens the portal with the standard animation.
• FireUser3: Closes the portal with the standard animation.
• FireUser4: Closes the portal instantly.

Example: To have a button open a static red portal, send the button's OnPressed output to my_red_portals-portal1 with the input FireUser1.

VScript API

For advanced scripting, you can interact with MultiPortals instances from your own VScript files.

Getting a Portal Instance

Use the global function GetCustomPortal to get a handle to any portal instance.

GetCustomPortal(pairId, portalIdx)

• pairId (integer): The ID you set in $portal-id.
• portalIdx (integer): The portal index (0 for the first, 1 for the second).

Available Methods & Properties

Once you have a CustomPortal instance, you can use the following methods and properties:

Method	Parameters	Description
Open()	—	Opens the portal with the opening animation.
Close(animTime)	animTime (float, default: CLOSE_TIME (0.3))	Closes the portal. Pass 0 to close instantly.
Fizzle(animTime)	animTime (float, default: CLOSE_TIME (0.3))	Closes both portals in the pair.
GetPartner()	—	Returns the CustomPortal instance of the partner portal.
SetColor(color, runEvent)	color (string / Vector), runEvent (bool, default: true)	Dynamically changes the portal's color.
SetColorScale(value, delay)	value (float), delay (float, default: 0)	Sets the brightness multiplier.

Key properties:

• portal (CBaseEntity): The underlying prop_portal entity.
• isOpen (bool): Whether the portal is currently open.
• pairId (int): The pair ID.
• color (Vector): Current portal color.

Example VScript Code:

// Get the first portal from the pair with ID 1
local myPortal = GetCustomPortal(1, 0); 

if (myPortal) {
    // Dynamically change its color to green
    myPortal.SetColor("0 255 0");

    // Programmatically open it
    myPortal.Open();

    // Close the partner portal instantly
    local partner = myPortal.GetPartner();
    if (partner && partner.isOpen) {
        partner.Close(0);
    }
}

Responding to Portal Events with VScript (MP_Events)

For even deeper integration, MultiPortals fires several VScript events that you can listen to from your own scripts. This allows you to create custom logic that reacts to what the portals are doing. To use this, you must subscribe a function to an event using the AddAction() method.

Event Name	Arguments Passed to Your Function	Description
ChangePortalPair	pairId (integer)	Fired when the active portal gun linkage ID is changed.
ChangePortalColor	instance (CustomPortal), color (Vector)	Fired when a portal's color is changed via .SetColor().
OnOpened	instance (CustomPortal)	Fired when a portal is opened and begins its opening animation.
OnClosed	instance (CustomPortal)	Fired when a portal is closed and begins its closing animation.

Example VScript Code:

// This function will run whenever ANY MultiPortal is opened.
function MyCustomOnOpenedAction(portalInstance) {
    // 'portalInstance' is the CustomPortal object that was opened.
    local portalName = portalInstance.portal.GetName();
    printl("A portal was opened: " + portalName);
    
    // You can check its pair ID and trigger custom logic.
    if (portalInstance.pairId == 3) {
        EntFire("my_secret_relay", "Trigger");
    }
}

// Subscribe the function to the 'OnOpened' event
MP_Events.OnOpened.AddAction(MyCustomOnOpenedAction);

Addons & Extensions

This section is dedicated to community-created scripts and instances that extend the functionality of MultiPortals. If you've built something cool that uses the MP_Events API, let us know!

• (More content coming soon!), frfr

Important Notes

For Players: How to Disable Ghosting I'm a player, what if I want to disable the forced ghosting effect for multiportals? Use multiportal_draw_ghosting_off or portal_draw_ghosting_disable, they are equivalent.

Note: Do not place your map at the origin coordinates (0, 0, 0), as there will be an unnecessary portal particle.

Warning: When you are ready to publish your map, you MUST pack all the custom content (/scripts/, /materials/) into your final .bsp file. Use a tool like Pakrat or other to do this, otherwise other players will not see the portals correctly.

Examples TODO

The MultiPortals package includes example maps to demonstrate its capabilities. Feel free to explore them to gain a better understanding of how to use the features and unleash your creativity! Check the Examples folder!

Credits

The MultiPortals was created by LaVashik. Please give credit to LaVashik when using this in your projects :>

Protected by the MIT license.