Best practices for handling dynamic aspect ratios and resizing?

[Joshua-Beatty]

Hi All,

I have just stumbled upon Excalibur and it looks incredibly promising and interesting. I am in the process of trying to build a small scale game with the framework to get a feel for it. My end goal would be to have a game that could run on mobile, and any web browser. Looking at the docs here I see a few different scaling methods. Ideal I would have like a 16:9 "safe area"(This is how i have generally seen it talked about in other engines) like DisplayMode.FitScreen, but I would still like to be able to display content outside of this safe area, to give a cohesive look on all aspect ratios, with no black bars.

Currently my solution is to use DisplayMode.FillScreen and manually calculate a 16 by 9 safe area, but this gets more complicated quickly when resizing happens and all elements need to be re positions. This alone is not a deal breaker, but I want to make sure I am going about this the best way possible, and that I am not missing any easy fixes for this from the documentation.

---

Edit:
Another Idea I have is to something along these lines:

const vw = Math.max(document.documentElement.clientWidth || 0, window.innerWidth || 0)
const vh = Math.max(document.documentElement.clientHeight || 0, window.innerHeight || 0)
const game = new Engine({
    width: vw,
    height: vh,
    canvasElementId: "game",
    displayMode: DisplayMode.FitScreen,
});

Where the aspect ratio is dynamic upon the initial load but then uses FitScreen for that ratio. This gives a good experiences on browsers and mobile devices, and if resized it still acts mostly okay.

---

Edit 2:

Another idea I have:

const vw = Math.max( document.documentElement.clientWidth || 0, window.innerWidth || 0 );
const vh = Math.max( document.documentElement.clientHeight || 0, window.innerHeight || 0 );
let game;
if (vw / vh <= 16 / 9) {
  game = new Engine({
    width: vw * 1280 / vw,
    height: vw * 1280 / vw * vh / vw,
    canvasElementId: "game",
    displayMode: DisplayMode.FitScreen,
    backgroundColor: Color.Black,
  });
} else {
  game = new Engine({
    width: vh * 720 / vh * vw / vh,
    height: vh * 720 / vh,
    canvasElementId: "game",
    displayMode: DisplayMode.FitScreen,
    backgroundColor: Color.Black,
  });
}
game.currentScene.camera.x = 0;
game.currentScene.camera.y = 0;

So you always have a 1280*720 logical pixels in the center, that you can position all elements absolutely around, but still has the same downside as before of when it is resizes, but it is significantly easier to position the different elements.

[eonarheim]

Hi @Joshua-Beatty

Thanks for the kind words!

This is definitely a desirable feature to allow a safe area without black bars. I'll add an issue to look into this being rolled into Excalibur. I'm away from my computer for a while but I'll document it as soon as I can.

Would you want something that would preserve the aspect ratio, but "scale" and center the viewport to hide the black bars? It looks like unity will return a read-only safe area bounding box based on the current screen over scan, does something like that sound like it meets your expectations?
https://docs.unity3d.com/ScriptReference/Screen-safeArea.html

Do you have an example of what the most desirable resizing experience might look like to you in your use case?

In the current state I think your solutions are the best that can be done without changing Excalibur. Very cool stuff you've got!

cc @jedeen @kamranayub

[Joshua-Beatty]

I went ahead and created a fork for this where I could test out implementing this. It works fantastic, but only as long as the camera is set to 0, 0.

I think the x and y of the camera would need to modified on resize(To keep the current "content area" centered)? I am unsure if a screen/camera offset like this is something that is currently supported in the code base, because I have mainly just been poking around.

[Joshua-Beatty]

Using that same fork, and locking the camera to an actor at the center of the content, even with 0,0 at the top left, gives the perfect behavior.

[Joshua-Beatty]

Some further testing, it looks like my first implementation actually works correctly, and that the camera just needs to re positioned once when the game is initialized.

[eonarheim]

Hi @Joshua-Beatty I think your fork is pretty close to the solution we are looking for! I like the new DisplayMode.FitContent name.

If you want to contribute, please make a PR from your fork and we can help sort out any issues you've identified.

[chrisMYchen]

Just wanted to comment that I am picking this back up. I used the code from @Joshua-Beatty's fork and it worked perfectly for what I was expecting. Thanks!

I opened a new discussion related to me trying to test this and develop with a fork here. I'd love to open a PR if I can get some help with this! #2465