What is a PortalSymbol?

[Asuna Yuuki Nagato]

In ZScript we have PortalSymbols.cpp

What is a Portal Symbol?

Is a warp a portal, or is a portal a warp?

[BegaVega]

That's script access to portal objects; an object that's left behind by the Mirror item if it's set to leave behind a return portal, but you can also create them for generic purposes via script.

Inside the file is:

{ "getX",                    0,         ZTID_FLOAT,   PORTALX,         0,  { ZTID_PORTAL },{} },

the part after ZTID_FLOAT/ZTID_BOOL/etc is the name of the ZASM command for the ZScript on the left (in this case, portal->X (get and set are removed from the beginning)). So, we have the ZASM "PORTALX"; all ZASM commands are represented with the code to run inside "ffscript.cpp", so take PORTALX and search for it; first result is:

case PORTALX:
		{
			ret = -10000;
			if(portal* p = checkPortal(ri->portalref, "X"))
				ret = p->x.getZLong();
			break;
		}

Hmm, checkPortal might give us some results. If you don't have notepad++ or some other good text editor (examples include Notepad++, VSCode, Visual Studio 2022, etc), now would be a good time to find a preferred one, as we want to "find in all files" for checkPortal (it's a tab when you Ctrl F in notepad++).

extern portal mirror_portal;
portal *checkPortal(int32_t ref, const char *what, bool skiperr = false)
{
	if(ref == -1)
		return &mirror_portal;
	portal* p = (portal*)portals.getByUID(ref);
	if(!p)
	{
		if(!skiperr)
			Z_scripterrlog("Invalid portal pointer access (%ld) for '->%s'\n", ref, what);
		return nullptr;
	}
	return p;
}

Okay, it seems like it has a default value of mirror_portal; the presence of a default value implies they're used for more than other things, maybe this is a script created object you can just use? Either way, we have a lead in mirror_portal, so lets search for where things might be setting it with a find in files, whole word and case sensitive.

void gamedata::load_portal()
{
#ifndef IS_EDITOR
	mirror_portal.clear();
	portal* tmp = loadportal(saved_mirror_portal);
	if(tmp)
	{
		mirror_portal = *tmp;
		delete tmp;
	}
#endif
}

Seems like load_portal() loads it from saved_mirror_portal, so we have two options of searching; either where the function load_portal() is being called, or saved_mirror_portal itself. Searching for saved_mirror portal leads us to set_portal() as the only thing (that isn't save data being read) as the only thing setting stuff for it, and regardless of if you search for load_portal() or set_portal(), they both lead to the same place: void HeroClass::doMirror(int32_t mirrorid)

Searching for doMirror gives us:

case itype_mirror:
			doMirror(itemid);
			if(Quit)
				return false;
			ret = false;
			break;

So we see that the mirror item is what it's used for.

There's a complaint to be made that ZScript_Additions.txt points you to an html file that isn't even included in ZC; and that the html it's trying to point you to hosted on the website doesn't even list portals normally and that you have to use the search functionality of said documentation to even find portals, but here's documentation: https://zquestclassic.com/docs/zscript/?jump=portal

[Asuna Yuuki Nagato]

Ah ok, so it's for the mirror and return portals from Zelda 3. Got it - thanks.