Author Topic: [Experiment] Custom Room Viewport and Camera  (Read 582 times)

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
[Experiment] Custom Room Viewport and Camera
« on: 22 Oct 2018, 02:11 »
UPDATE from 2nd 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/ecc5ldzi1dqvc5k/ags-3.5.0--roomviewport-wip4.zip?dl=0
The feature is discussed here on github: https://github.com/adventuregamestudio/ags/issues/473
Source branch: https://github.com/ivan-mogilko/ags-refactoring/tree/ags3--roomviewport

In 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.


=======================================================================================


Script API:
Code: Adventure Game Studio
  1. builtin managed struct Camera
  2. {
  3.   /// Gets/sets the X position of this camera in the room.
  4.   import attribute int X;
  5.   /// Gets/sets the Y position of this camera in the room.
  6.   import attribute int Y;
  7.   /// Gets/sets the camera's capture width in room coordinates.
  8.   import attribute int Width;
  9.   /// Gets/sets the camera's capture height in room coordinates.
  10.   import attribute int Height;
  11.   /// Gets/sets this camera's room horizontal scaling relative to the viewport it is displayed in.
  12.   import attribute float ScaleX;
  13.   /// Gets/sets this camera's room vertical scaling relative to the viewport it is displayed in.
  14.   import attribute float ScaleY;
  15.  
  16.   /// Gets/sets whether this camera will follow the player character automatically.
  17.   import attribute bool Auto;
  18. };
  19.  
  20. builtin managed struct Viewport
  21. {
  22.   /// Gets/sets the X position on the screen where this viewport is located.
  23.   import attribute int X;
  24.   /// Gets/sets the Y position on the screen where this viewport is located.
  25.   import attribute int Y;
  26.   /// Gets/sets the viewport's width in screen coordinates.
  27.   import attribute int Width;
  28.   /// Gets/sets the viewport's height in screen coordinates.
  29.   import attribute int Height;
  30.   /// Gets the room camera displayed in this viewport.
  31.   import readonly attribute Camera *Camera;
  32. };
  33.  

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:
Code: Adventure Game Studio
  1. Viewport *Game.RoomViewport;
  2. Camera *Room.Camera;
  3.  

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=0

At 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:
Code: Adventure Game Studio
  1. Camera *cam = Room.Camera;
  2. cam.X = 10;
  3.  
   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.
Add spoiler tag for Hidden:
But like I said, drawing them alone is not a problem:

« Last Edit: 03 Dec 2018, 14:44 by Crimson Wizard »

Danvzare

  • The Man with No Name
    • I can help with AGS tutoring
    •  
    • I can help with proof reading
    •  
    • I can help with scripting
    •  
    • I can help with voice acting
    •  
Re: [Experiment] Custom Room Viewport and Camera
« Reply #1 on: 22 Oct 2018, 11:35 »
Ooh, sounds useful.
With something like that, it should be possible to make some really cinematic looking games.

Re: [Experiment] Custom Room Viewport and Camera
« Reply #2 on: 22 Oct 2018, 23:29 »
Multiple cameras could be used for minimaps. Other than this I don't see much use for multiple cameras.

I am adding below an error that occurs when I leave this AGS and an error that occurs when I open this AGS after closing it.
Add spoiler tag for Hidden:


Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: [Experiment] Custom Room Viewport and Camera
« Reply #3 on: 22 Oct 2018, 23:50 »
Multiple cameras could be used for minimaps. Other than this I don't see much use for multiple cameras.

Basically any case of looking into something while still seeing your current position: zooming into an item/object or peeing into a keyhole, simulating an event in "another room" without actually changing rooms - all this could be simulated by displaying a separate and otherwise unaccessible part of the room in a second viewport. Showing two or more locations at once during cutscene. Split-screen multiplayer. These are cases I may think of.

It may be non optimal for a minimap though, since engine will have to process every sprite it sees, including its tints, lighting, scaling, walkbehinds etc.


I am adding below an error that occurs when I leave this AGS and an error that occurs when I open this AGS after closing it.

This might be a previously reported error that happens when you close the 3.5.0 Editor. But this time there is some interesting information about SpriteCache destructor.
« Last Edit: 23 Oct 2018, 00:23 by Crimson Wizard »

Danvzare

  • The Man with No Name
    • I can help with AGS tutoring
    •  
    • I can help with proof reading
    •  
    • I can help with scripting
    •  
    • I can help with voice acting
    •  
Re: [Experiment] Custom Room Viewport and Camera
« Reply #4 on: 23 Oct 2018, 11:58 »
Multiple cameras could be used for minimaps. Other than this I don't see much use for multiple cameras.
I can. Finally we can make a splitscreen adventure game! :-D

And yes, I have always wanted to do that.

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: [Experiment] Custom Room Viewport and Camera
« Reply #5 on: 18 Nov 2018, 23:08 »
Updated the test build, now supports Software renderer too (this means 8-bit games):
https://www.dropbox.com/s/au7nw0zjrr13eaq/ags-3.5.0--roomviewport-wip2.zip?dl=0

Built on top of the latest 3.5.0 Alpha 7, so to test this you may install a copy of 3.5.0 somewhere and unpack the archive over it.

Still TODO:
- Better script API to manage the new viewport/camera functionality;
- Some optimisation for software rendering.
- more testing...
- Actually allowing room backgrounds of any size (less than game screen).
« Last Edit: 18 Nov 2018, 23:10 by Crimson Wizard »

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: [Experiment] Custom Room Viewport and Camera
« Reply #6 on: 30 Nov 2018, 00:04 »
New update: https://www.dropbox.com/s/e8i10xh8x28dn6q/ags-3.5.0--roomviewport-wip3.zip?dl=0

This mostly fixes some issues with software renderer.

Crimson Wizard

  • Local Moderator
  • AGS Project Tracker Admins
    • Best Innovation Award Winner 2013, for spearheading the AGS 3.3.0 project
    •  
    • Lifetime Achievement Award Winner
    •  
    • Crimson Wizard worked on a game that was nominated for an AGS Award!
      Crimson Wizard worked on a game that won an AGS Award!
Re: [Experiment] Custom Room Viewport and Camera
« Reply #7 on: 02 Dec 2018, 17:20 »
Alright, here's practically working version with a new script API:
https://www.dropbox.com/s/ecc5ldzi1dqvc5k/ags-3.5.0--roomviewport-wip4.zip?dl=0

Script API:
Code: Adventure Game Studio
  1. builtin managed struct Camera
  2. {
  3.   /// Gets/sets the X position of this camera in the room.
  4.   import attribute int X;
  5.   /// Gets/sets the Y position of this camera in the room.
  6.   import attribute int Y;
  7.   /// Gets/sets the camera's capture width in room coordinates.
  8.   import attribute int Width;
  9.   /// Gets/sets the camera's capture height in room coordinates.
  10.   import attribute int Height;
  11.   /// Gets/sets this camera's room horizontal scaling relative to the viewport it is displayed in.
  12.   import attribute float ScaleX;
  13.   /// Gets/sets this camera's room vertical scaling relative to the viewport it is displayed in.
  14.   import attribute float ScaleY;
  15.  
  16.   /// Gets/sets whether this camera will follow the player character automatically.
  17.   import attribute bool Auto;
  18. };
  19.  
  20. builtin managed struct Viewport
  21. {
  22.   /// Gets/sets the X position on the screen where this viewport is located.
  23.   import attribute int X;
  24.   /// Gets/sets the Y position on the screen where this viewport is located.
  25.   import attribute int Y;
  26.   /// Gets/sets the viewport's width in screen coordinates.
  27.   import attribute int Width;
  28.   /// Gets/sets the viewport's height in screen coordinates.
  29.   import attribute int Height;
  30.   /// Gets the room camera displayed in this viewport.
  31.   import readonly attribute Camera *Camera;
  32. };
  33.  

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:
Code: Adventure Game Studio
  1. Viewport *Game.RoomViewport;
  2. Camera *Room.Camera;
  3.  


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;



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:
Code: Adventure Game Studio
  1. Camera *cam = Room.Camera;
  2. cam.X = 10;
  3.  
   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.



Little demonstration:
https://www.dropbox.com/s/l9783w8t1i8qk3t/roomcameramadness.mp4?dl=0

At this point nothing of above is set in stone, and I'd very much appreciate any functionality tests and thoughts on script commands.
« Last Edit: 03 Dec 2018, 14:43 by Crimson Wizard »