Vanilla Nether portals have a mechanic that doesn't simply spawn a portal in the corresponding location like BP does, but (AFAIK):

• Looks for a safe, preferably non-buried spot in a small radius
• Automatically chooses the best Y-coordinate for the portal so that it's placed on solid ground
• Links the portal to any nearest portal within that radius

This was very nice, because:

• Portals did not spawn buried or in the air most of the time
• You could create a portal deep in your basement that leads to a normal height portal in the Nether
• You could place portals in more convenient locations within a certain radius

Might it be possible to support this at least optionally and maybe with some drawbacks? If necessary, there might be a rule that one portal is linked to only one other portal, and any previous ones are disabled.

When I disable the "replace Nether portals" option, portals work as expected - a portal built in the same space in the Overworld creates a portal outside of netherrack.

Could you attach a zip file of the world with that portal frame built but not yet lit?
That should be simple enough and be sufficient for me to unambiguously reproduce the issue.

but are you sure you can't reproduce this already?..

I'd rather have a concrete, reproducible setup (see above) than randomly trying on my own without knowing precisely what I'm looking for.

Last time I tried (which admittedly wasn't very recent), portal placement was working as I was expecting it to do. Note that underground portals are expected if there's sufficient space and a sufficiently sized, level floor in the cave for the portal and that spot is closer to the optimal position than any overground spot (should be the same in vanilla as well though).

Here is a vanilla map so that you could try the vanilla behaviour as well.

In the first world, BP will create a portal above lava. Vanilla will try to find the nearest safe place, which is so far that the way back creates another portal in another place. (As I understand, this is unavoidable with BP mechanics? But this is not the biggest problem.)

In the second world, I went through that portal and created two more portals. In vanilla, those will both lead to the ground level. In BP, those will both be buried completely in rock.
portality.zip
portality2.zip

BP already does all the things you listed. See e.g. first paragraph of #203 (comment) for details.

Also, vanilla does not link portals at all. Your destination depends solely on where you're currently standing, so a single portal can actually end you up in two different places depending on where you stand in it.
That obviously cannot work with BP. Neither can two portals in the overworld link to one portal in the nether (same reason but in reverse). As such, you cannot simply link two portals in BP, you have to build two frames of identical shape and only after both are built, light one of them.

I've tried this again. Linking to another portal of a similar shape at slightly altered coordinates works! This includes Y coordinate and XZ coordinates. I must have done something stupid like different portal shapes. :)

However, one issue persists, and I've just tried it again, this time being certain that I am wrong and expecting to see the correct behaviour. When I construct a portal (I've tried the "vanilla" shape), most of the time it's buried in netherrack or stone. Build one in the Overworld on the ground, and it goes to netherrack without looking for an unobstructed spot. Build one at lava-level in the Nether, and it is buried in stone, not trying to go up to ground level. Maybe the "look around" radius is set too low, especially on the Y axis?..

When I disable the "replace Nether portals" option, portals work as expected - a portal built in the same space in the Overworld creates a portal outside of netherrack. When I re-enable BP and use the same portal, it doesn't even link to that one and creates another one instead (this I've tried yesterday, but did not confirm again on another map now).

I could share some system information, and a level seed with instructions on where to place the portal to reproduce the behaviour, but are you sure you can't reproduce this already?..

Thanks for the worlds. That's indeed not how things are supposed to work.

Above commit fixes the bug which basically caused the preferred-spot-searching-algorithm to reject every single spot. It'll land in BP 0.3.7.3 at some time later today.

Even with that fix, BP's portals will however still be positioned differently than vanilla portals are (but no longer floating in the air or buried in stone, instead in your examples the first one will be on the side of a cliff and the other two will be in caves).
Afaict the reason for this isn't that the search radius is too small, it's actually because it's too large (64 blocks in each direction of the xz-plane instead of the vanilla 16), so BP finds spots which are closer (e.g. same y but 20 blocks on x, so 20 total) which vanilla would have never found (since it only looks at most 16 blocks on x, but it does check the entire y, so instead it finds a spot 40 blocks down, so 40 total. and even though BP will find both, it'll choose the closer one).
While I don't think that's an issue at all in the nether, it does cause you to end up in overworld caves more often than on the surface (since there's a good chance there aren't any caves in the vanilla 33x256x33 search box but that chance is significantly lower for BP's 129x256x129 box). Not yet sure if I want to change that.

Thank you! Now I can add this mod and impress my friends without any downsides. :) And this mod is really impressive; when I saw it, I thought "there's no way it could be possible!", but I tried it and saw it myself!

I agree that ending up in a cave is certainly an interesting mechanic!

On the other hand, this makes it harder to calculate positions for your portal network, since you have to keep Y in mind, and there might be a cave below you. That box looks too big! Also, you have a chance to pop out inside someone's house, bringing a portal straight to hell with you. :) That is certainly fun and interesting, unless that is not the desired effect...

I would suggest adding an option to stick closer to the vanilla mechanics (as far as it is possible with "real portal linking": keep the box vanilla-sized and maybe even prefer above-ground positions (search from the top in the Overworld and from the bottom in the Nether?). Also, if there is already an unlinked portal within the box, then link to that portal instead of creating a new one in a better place (or is it already doing that?).

I would suggest adding an option to stick closer to the vanilla mechanics (as far as it is possible with "real portal linking": keep the box vanilla-sized and maybe even prefer above-ground positions (search from the top in the Overworld and from the bottom in the Nether?).

I opened a separate issue for the option to reduce the search box size: #425
I don't think vanilla prefers above-ground positions in any way. At least I've had portals spawn in caves with vanilla as well. AFAIK it's really just the significantly reduced chance of there being a sufficiently sized cave in the search box.

On the other hand, this makes it harder to calculate positions for your portal network, since you have to keep Y in mind, and there might be a cave below you.

Pre-built, empty frames of matching size always take priority over generating new frames. The same box size is used to search for them (though that might change with above ticket) and, in case there are multiple, the closest one gets chosen. Only if there is no matching, empty frame in the box, will BP generate a new one.
The empty-frame-search is also the reason the radius is that large, to make it easier to manually link portals (and iirc it approximately matches the radius vanilla uses when searching for existing portals).

Also, if there is already an unlinked portal within the box, then link to that portal instead of creating a new one in a better place (or is it already doing that?).

See above. Yes, it does.

Could you please also explain the (and reasoning) behind portal orientation? I'm trying to make a portal network, and some of my portals are "flipped" (I step in facing north and step out facing south), but not all of them (in other portals, I step in facing north and step out facing north). And also what happens with portals not facing the same direction - I didn't even try to guess their principle.