Lock View is a Foundry VTT module that gives the GM control over the zoom and pan capabilities of players, such as locking the zoom or pan, moving the canvas, or setting the view to a specified setting.
The module was originally made as a companion app for my Material Plane module, and to make play using a digital playmat,
such as a horizontally mounted TV, easier.
Over time, however, the module's features have expanded greatly, including many functions that can be useful for digital play.
The module has 6 main functions:
- Autoscaling: Scales the scene in various ways (horizontal fit, vertical fit, automatic fit, or scaled to a physical gridsize)
- Zoom lock: Locks the zooming of the scene to prevent the user from (accidentally) messing up the autoscale
- Pan lock: Locks the panning of the scene. If you use physical minis you don't want to accidentally pan
- Bounding box: Limit zoom and pan to stay within a bounding box
- Force initial view: After loading a new scene, the view is forced to the initial view (as set in the scene configuration menu), regardless of the position of tokens
- Viewbox: Allows the GM to see what's shown on players screens, and allows the GM to control the pan and zoom of those players
'Zoom Lock', 'Pan Lock' and 'Bounding Box' can be enabled and disabled at any time using control buttons.
These functions can be applied to selected connected players (must be set in the GM's module settings).
Note: When 'Zoom Lock' or 'Pan Lock' are enabled, this module disables all zooming and/or panning functionality, regardless of who or what is requesting that zoom or pan. This means that, for example, modules that try to pan or zoom won't work.
When using a horizontally mounted screen, for the purpose of playing with physical minis, you should do the following:
GM's client, module settings:
-Enable the module and viewbox for the player that is connected to the TV in the User Configuration screen
GM's client, scene configuration menu (for each scene):
-Set 'Autoscale' to 'Physical Gridsize', which forces the TV's client to a specific zoom, ensuring the grid is always the same physical size
-Enable 'Lock Pan' and 'Lock Zoom', which prevents the TV's client from accidentally zooming or panning
TV's client, module settings:
-Set 'Gridsize' to the desired physical size of the grid. Usually 25 mm or 1 inch. Only fill in the number, not the units
-Set 'Screen Width' to the physical width of your screen (the actual screen, without bezel). Must be in the same units as 'Gridsize'
Refer to the 'Settings and Controls' section below to see how the GM can manipulate the view of the TV's client.
The module can also be used when playing digitally (every player has their own computer). When doing so, you can ignore the following settings:
-'Gridsize' and 'Screen Width' in the module settings
-'Physical Gridsize' in the scene configuration menu (Autoscale option) and in the 'Set View' dialog box
In the User Configuration screen, enable the module and viewbox for each player whose view you want to control/view.
Refer to the 'Settings and Controls' section below to see how the GM can manipulate the view of the player clients.
Example for a static landing page or full screen 'splashscreen':
Make sure the module is enabled for all players in the module settings.
In the Scene Configuration:
-Set 'Autoscale' to 'Automatic Fit'. You can choose either the inside (crops a part of the canvas to make it full screen) or outside option (shows the whole canvas,
but can show some padding)
-Enable 'Lock Pan' and 'Lock Zoom'
-Make sure 'Bounding Box' is disabled
-Optionally enable 'Exclude Sidebar' and 'Blacken Sidebar' to make sure the sidebar isn't blocking part of the scene
-Set the scene background color to black ('#000000')
In the module settings, as a GM you will find a button to open the player configuration screen, where you can enable the module and viewbox for each player. By default, both are enabled for non-GM users.
The module must be enabled for each player if you want to use any of the functions of this module, except for displaying the viewbox, which has its own enable setting.
All connected players will also see two more settings which are only relevant if 'Autoscaling' is set to 'Physical Gridsize' (see below), as these settings allow the module to calculate the correct grid scale.
The settings are:
- Screen Width - Fill in the physical screen width in mm or inch of the TV
- Gridsize - Fill in the desired gridsize in mm or inch (must be the same unit as 'Screen Width'). This is usually 25 mm or 1 inch
By pressing the 'Congigure Initial View Position' button to the right of the 'Force Initial View' checkbox, a dialog box opens and a red box is drawn on the canvas.
This red box corresponds with the 'Initial View Position' as set in the 'Ambience and Atmosphere' section of the 'Scene Configuration Screen'.
Pressing the 'move' icon at the top left of the red box moves the box around while pressing the 'scale' icon at the right bottom scales the box.
In the dialog box, you'll find the following values and buttons:
- Old initial view position - The old initial view position as it is currently set in the scene configuration
- New initial view position - The new initial view position as displayed by the red box. These values are user editable
- Size in grid spaces - The size of the view expressed in grid spaces. These values are user editable
- Set to physical gridsize - Scales the 'new initial view position' to correspond with the physical gridsize as set in the module settings
- Set to player view - By selecting the name of a player that's currently connected, you can set the initial view position to the view of that player by pressing 'Capture View'
- Snap to grid - Snaps the 'new initial view poisition' to the grid. With the dropdown menu you can select which corner of the box should be snapped to the grid
By pressing the 'Cancel', 'Save', or 'Close' button, you'll return to the scene configuration. Only when the 'Save' button is pressed the initial view position on the scene configuration will be updated.
Don't forget to save the scene configuration to have the new settings take effect.
In the scene configuration screen, you'll find a new Lock View section with the following settings:
- Pan Lock - Initial 'Pan Lock' setting
- Zoom Lock - Initial 'Zoom Lock' setting
- Bounding box: Initial 'Bounding Box' settings
- Autoscale - Automatically scales the screen
- Exclude Sidebar - Exclude the area behind the sidebar from the bounding box or autoscaling. This can be enabled because the sidebar can obscure parts of the map
- Blacken Sidebar - Blackens the background of the sidebar to prevent users from seeing outsie of the bounding box or canvas (only works if 'Exclude Sidebar' is enabled)
- Collapse Sidebar on Scene Load - Collapses the sidebar when the scene is loaded, mainly useful in combination with 'Hide UI on Sidebar Collapse'
- Hide UI Elements on Sidebar Collapse - Hides selected UI elements (such as the macro hotbar, scene navigation, etc) when the sidebar is collapsed, great for landing pages or splash screens. You can configure which elements to hide by pressing the 'cog' button next to the checkbox. By default all elements except for the sidebar are enabled
- Force Initial View - Forces the view to the 'Initial View Position' after loading the scene. Only works if 'Autoscale' is set to 'Off' or 'Physical Gridsize'
- Configure Initial View Position button - The button is located to the right of the 'Force Initial View' checkbox. Pressing it opens the 'Configure Initial View Position dialog screen (see below)
- Off - Autoscale disabled
- Horizontal Fit - Automatically scales the scene to fit the browser window. Horizontal fit, so it may cut off vertical parts of the scene
- Vertical Fit - Automatically scales the scene to fit the browser window. Vertical fit, so it may cut off horizontal parts of the scene
- Automatic Fit (inside) - Automatically chooses horizontal or vertical fit so no non-image background will ever be seen
- Automatic Fit (outside) - Automatically chooses horizontal or vertical fit so the full background can be seen, but can show the padding (area outside of the background image)
- Physical Gridsize - Scales the scene so the on-screen gridsize corresponds with a real world value (for example 25mm or 1"). The gridsize is determined by setting the 'Screen Width' and 'Gridsize' in the module settings. These settings are local, which means that they can be different for each connected client
Note 2: 'Horizontal Fit', 'Vertical Fit', 'Automatic Fit' and 'Physical Gridsize' are applied when a scene is loaded, or after closing the scene configuration screen. After that, the player can zoom and pan around (if Zoom Lock or Pan Lock are disabled)
On the left of the screen, there are new control buttons for the GM that display and toggle the current setting on the scene.
From the top to the bottom:
- Set View - Creates a dialog box with options to set the view, see below
- Pan Lock - Shows/switches the current state of 'Pan Lock'. If on, panning is disabled
- Zoom Lock - Shows/switches the current state of 'Zoom Lock'. If on, zooming is disabled
- Bounding Box - Shows/switches the current state of 'Bounding Box'. If on, zoom and pan are limited to the bounding box
- Viewbox - Draws a square on the canvas that shows what enabled players can see. The color of the square corresponds with the 'Player Color'
- Edit Viewbox - Allows the GM to edit the viewbox, and the players view. Right-click dragging drags the viewbox and pans all enabled players sceens, the scrollwheel increases or decreases the size of the viewbox and zooms the screen of all enabled players in or out. Additionally, two icons appear next to each viewbox which can be used to zoom or pan the view of individual players.
After clicking the 'Set View' control button, a dialog box appears that gives multiple options to control the view of players. There's 2 dropdown menu's, and 3 number boxes
Top dropdown menu (X & Y movement)
- Reset to initial view - Resets the view to the initial view position, as set in the scene configuration screen
- Horizontal fit - Scale and move the view so the scene fits horizontally
- Vertical fit - Scale and move the view so the scene fits vertically
- Automatic Fit (inside) - Automatically chooses horizontal or vertical fit so no non-image background will ever be seen
- Automatic Fit (outside) - Automatically chooses horizontal or vertical fit so the full background can be seen, but can show the padding (area outside of the background image)
- Move grid spaces - Moves the view in grid-units, relative to the current view. So setting X to 1 will move the view 1 gridspace to the right
- Move to coordinates - Moves the view to the absolute coordinates as set in the number boxes
Bottom dropdown menu (Zooming)
- Ignore scale - No zooming will occur
- Set scale - Zooms to the scale size set in the 'Scale' box
- Reset scale - Resets the zoom to the initial zoom factor, as set in the scene configuration screen
- Physical gridsize - Automatically scales the gridsize to make it correspond to a physical gridsize (in mm or inch), as set in the module settings
The bounding box function limits how much a user can zoom or pan. It needs to be enabled, either in the scene configuration screen, or using control buttons. This function ensures that they always stay within a defined box.
To enable the bounding box function on a scene load, you can enable the function in the scene configuration screen. The function can also be enabled on the fly by pressing the control button.
By default this box is the canvas size (size of your background image), so users will not see the background color and padding.
It is also possible to define a bounding box by drawing a rectangle (control buttons => drawing tools => draw rectangle). After drawing the rectangle, you can edit it (double clicking the rectangle) to set the rectangle as a bounding box. This can be done in the Lock View tab, where you have the following options:
- Disabled: The rectangle is not used as a bounding box
- Owned Tokens: Use the rectangle as bounding box if a token that's owned by the user is within the rectangle. You can set multiple rectangles to 'Owned Tokens'. Moving a token from one 'Owned Tokens' rectangle to another forces the view to the new rectangle. If you have multiple owned tokens in different 'Owned Tokens' rectangles, the bounding box will extend to fit all of these rectangles
- Always: The rectangle is always used as bounding box, also if no tokens are within the rectangle. This overrides all other rectangles. Only one rectangle should be set to 'Always'. If more rectangles are set to 'Always', only one is chosen
The viewbox is a function that allows the GM so see what users can see.
If enabled (enable for the user in the User Configuration screen in the module settings, and enable the 'Viewbox' control button),
a rectangle is drawn that corresponds with the view of the user. The color of the rectangle is the user color, and above the rectangle you can find the user name.
It is possible for the GM to control the view of the users by enabling the 'Edit Viewbox' control button.
If enabled, the GM can either control the view of all enabled users: pan by left-click dragging and zoom by using the scroll wheel.
Or control the view of individual users by dragging the icons next to each viewbox that appear when the 'Edit Viewbox' control button is pressed: Drag the upper-left icon to pan, drag the lower-right icon to zoom.
If you enjoy using my modules, please consider supporting me on Patreon.
Abandoned modules are a (potential) problem for Foundry, because users and/or other modules might rely on abandoned modules, which might break in future Foundry updates.
I consider this module abandoned if all of the below cases apply:
- This module/github page has not received any updates in at least 3 months
- I have not posted anything on "the Foundry" and "the League of Extraordinary Foundry VTT Developers" Discord servers in at least 3 months
- I have not responded to emails or PMs on Discord in at least 1 month
- I have not announced a temporary break from development, unless the announced end date of this break has been passed by at least 3 months
I require the "League of Extraordinary Foundry VTT Developers" admins to send me an email 2 weeks before the reassignment takes place, to give me one last chance to prevent the reassignment.
I require to be credited for my work in all future releases.