UPDATE from 13th December 2018:This is the practically working WIP version of a custom room viewport, built on top of AGS 3.5.0 (alpha 7):
Build:
https://www.dropbox.com/s/lk7b25a8kwj9jfz/ags-3.5.0--roomviewport-wip5.zip?dl=0The feature is discussed here on github:
https://github.com/adventuregamestudio/ags/issues/473Pull request:
https://github.com/adventuregamestudio/ags/pull/535Source branch:
https://github.com/ivan-mogilko/ags-refactoring/tree/ags3--roomviewportIn short, this feature lets you to change the way ROOM (and all inside it) is shown on game screen. This is done by setting up Room Viewport and Camera.
Camera is an "eye" inside the room, that has certain size and position in room coordinates. The existing "viewport" commands in current AGS serve for the same purpose.
Viewport is a surface on game screen where what camera "sees" gets drawn to. It also has a size and position, but in screen coordinates.
You may imagine a piece of room (the size of camera) is cut out and pasted in the viewport, resized if necessary.
If the Camera is smaller than the viewport, then the room will appear
scaled up on screen. If the Camera is larger than the viewport, the room will appear
scaled down.
Note, that with the smaller Camera size
you may get a scrolling room even with rooms that are equal to game's size.
Extra consequence is that from now on you may have room backgrounds (and essentially - rooms) of any size. For example, 320x120 room in a 320x200 game.
This may be useful if part of your game screen is constantly covered by GUI, or if you want to make one room which is smaller than others.
=======================================================================================
Script API:
builtin managed struct Camera
{
/// Gets/sets the X position of this camera in the room.
import attribute int X;
/// Gets/sets the Y position of this camera in the room.
import attribute int Y;
/// Gets/sets the camera's capture width in room coordinates.
import attribute int Width;
/// Gets/sets the camera's capture height in room coordinates.
import attribute int Height;
/// Gets/sets this camera's room horizontal scaling relative to the viewport it is displayed in.
import attribute float ScaleX;
/// Gets/sets this camera's room vertical scaling relative to the viewport it is displayed in.
import attribute float ScaleY;
/// Gets/sets whether this camera will follow the player character automatically.
import attribute bool AutoTracking;
};
builtin managed struct Viewport
{
/// Gets/sets the X position on the screen where this viewport is located.
import attribute int X;
/// Gets/sets the Y position on the screen where this viewport is located.
import attribute int Y;
/// Gets/sets the viewport's width in screen coordinates.
import attribute int Width;
/// Gets/sets the viewport's height in screen coordinates.
import attribute int Height;
/// Gets the room camera displayed in this viewport.
import readonly attribute Camera *Camera;
};
Viewport is a place
on screen where room is drawn, defined in game coordinates (e.g. 0,0 - 320x200).
Camera is a place
in room which is being drawn. Camera size may be determined in two ways:
a) explicitly setting Width and Height, which tells actual rectangle in the room;
b) setting ScaleX and ScaleY properties to automatically adjust displayed room relative to the viewport's size.
For example, if you set ScaleX/Y to 2.0, then room will appear
zoomed in twice as large as the viewport's size. If you set ScaleX/Y to 0.5, it will appear twice as small (zoomed out).
NOTE: you cannot set camera size larger than the room's background, and it generally does not support "seeing" beyond room's background, same as before.
You access viewport and camera using commands:
Viewport *Game.RoomViewport;
Camera *Room.Camera;
Also:
/// Gets/sets whether the viewport should automatically adjust itself and camera to the new room's background size
Game.AutoSizeViewportOnLoad;
Old viewport functions are now deprecated, they may still be enabled if you set "Script compatibility level" to v3.4.1 or lower.
Here's correspondence between old and new functions:
* SetViewport(x, y); ===> Room.Camera.X = x; Room.Camera.Y = y; Room.Camera.Auto = false;
* ReleaseViewport(); ===> Room.Camera.Auto = true;
* GetViewportX(); ===> Room.Camera.X;
* GetViewportY(); ===> Room.Camera.Y;
Little demonstration:
https://www.dropbox.com/s/l9783w8t1i8qk3t/roomcameramadness.mp4?dl=0At this point nothing of above is set in stone, and I'd very much appreciate any functionality tests and thoughts on script commands.
KNOWN ISSUES: * because of a bug the AGS script does not let you write "Room.Camera.X = 10"; instead you have to do something like:
Camera *cam = Room.Camera;
cam.X = 10;
this is very inconvenient indeed, and I think we need to fixing this issue, or change something in the above script API to make it simplier.
* some possible optimization issues with software renderer when you change camera size too often.
=======================================================================================
The purpose of these features are:
1) Display room in a custom rectangle on screen;
2) Add zoom in/out effects in your game.
3) Potentially - also add rotation to the room view (if I am able to make it work correctly).
This also have a potential to have multiple room cameras in the future, although that may not be easy to add so I don't really plan to do that for AGS 3.5.0. The problem here is not so much in drawing them on screen, but rather in resolving interactions. Right now all the logic in AGS is based on the single viewport into the room: clicks, finding objects on screen, etc. Multiple viewports would demand a good thought and possibly script redesign.
But like I said, drawing them alone is not a problem:
