Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/subsoap/defos
Extra native OS functions for games written using the Defold game engine
https://github.com/subsoap/defos
defold defold-game-engine defold-library lua
Last synced: 5 days ago
JSON representation
Extra native OS functions for games written using the Defold game engine
- Host: GitHub
- URL: https://github.com/subsoap/defos
- Owner: subsoap
- License: cc0-1.0
- Created: 2017-05-03T18:40:16.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-10-05T11:05:27.000Z (4 months ago)
- Last Synced: 2025-01-25T23:11:43.778Z (12 days ago)
- Topics: defold, defold-game-engine, defold-library, lua
- Language: C++
- Homepage:
- Size: 1.39 MB
- Stars: 126
- Watchers: 13
- Forks: 18
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-defold - DefOS
README
# DefOS
Extra native OS functions for games written using the Defold game engine
Currently supports macOS, Windows, Linux and HTML5. Contribute!
## Installation
You can use DefOS in your own project by adding this project as a
[Defold library dependency](http://www.defold.com/manuals/libraries/).
Add the latest dependency URL from the
[releases page](https://github.com/subsoap/defos/releases) to your
dependencies field in `game.project`.
## game.project
> (From Defold 1.2.188)
You can change the initial view size and position of your game's window by editing the `game.project` file of your project in a plain text editor and adding the following lines:
```
[defos]
view_width = 640
view_height = 480
view_x = 20
view_y = 40
```
> :warning: It may show you `ERROR:ENGINE: Could not find '@render' socket.` error on start. But that means only that window change event can't send to the render_script because it's not created yet. More info is available here: https://github.com/subsoap/defos/issues/130
`view_width` and `view_height` can be used without `view_x` and `view_y` but not vice versa.
These initial values will be used at the launch of your project without needing to call any extension functions. Use these values to decrease the initial size of your game’s window view size if your game.project's [display] width / height values are large.
## Methods
**Customize title bar** accessories and title.
```lua
defos.disable_maximize_button() -- Not supported on HTML5
defos.disable_minimize_button() -- Not supported on HTML5
defos.disable_window_resize() -- Not supported on HTML5
defos.set_window_title("I set this title using Defos")
```
---
**Toggle window maximize** status.
```lua
defos.set_maximized(bool_value)
defos.toggle_maximized()
bool_value = defos.is_maximized()
```
---
**Toggle full screen**. On HTML5, this only works from `defos.on_click()` or `defos.on_interaction()`.
```lua
defos.set_fullscreen(bool_value)
defos.toggle_fullscreen()
bool_value = defos.is_fullscreen()
```
---
**Toggle borderless window**. Works and tested only on Windows platform.
```lua
defos.set_borderless(bool_value)
defos.toggle_borderless()
bool_value = defos.is_borderless()
```
---
**Keep window on top**. Not supported on HTML5.
```lua
defos.set_always_on_top(bool_value)
defos.toggle_always_on_top()
bool_value = defos.is_always_on_top()
```
---
**Minimize window**. Not supported on HTML5.
```lua
defos.minimize()
```
---
**Activate (focus) window**. Not supported on HTML5.
```lua
defos.activate()
```
---
**Get/set the window's size and position** in screen coordinates. The window area
includes the title bar, so the actual contained game view area might be smaller
than the given metrics.
Passing `nil` for `x` and `y` will center the window in the middle of the display.
Screen coordinates start at (0, 0) in the top-left corner of the main display.
X axis goes right. Y axis goes down.
```lua
x, y, w, h = defos.get_window_size()
defos.set_window_size(x, y, w, h)
```
---
**Get/set the game view size and position** in screen coordinates. This adjusts
the window so that its containing game view is at the desired size and position.
The window will be larger than the given metrics because it includes the title
bar.
Passing `nil` for `x` and `y` will center the window in the middle of the display.
```lua
x, y, w, h = defos.get_view_size()
defos.set_view_size(x, y, w, h)
```
---
**Query displays**.
`defos.get_displays()` returns a table which can be indexed with either number
indices (like an array), either with display `id`s.
Not supported on HTML5.
```lua
displays = defos.get_displays()
pprint(displays[1]) -- Print info about the main display
current_display_id = defos.get_current_display_id() -- Get the ID of the game's current display
pprint(displays[current_display_id]) -- Print info about the game's current display
```
A display info table has the following format:
```lua
{
id = ,
bounds = { -- This is the position and size in screen coordinates of the
x = 0, -- display (relative to the top-left corner of the main display)
y = 0,
width = 1440,
height = 900,
}
mode = { -- The current resolution mode of the display
width = 2880,
height = 1800,
scaling_factor = 2,
refresh_rate = 60,
bits_per_pixel = 32,
orientation = 0,
reflect_x = false,
reflect_y = false,
},
name = "Built-in Retina Display",
}
```
---
**Query resolution modes** for a display.
Returns a table with all the resolution modes a display supports.
Not supported on HTML5.
```lua
display_id = defos.get_current_display_id()
modes = defos.get_display_modes(display_id)
pprint(modes[1]) -- Print information about the first available resolution mode
```
A resolution mode has the following format:
```lua
{
width = 2880, -- Full width/height in pixels (not points)
height = 1800,
scaling_factor = 2, -- Hi-DPI scaling factor
refresh_rate = 60,
bits_per_pixel = 32,
orientation = 0, -- One of 0, 90, 180, 270 (degrees measured clockwise)
reflect_x = false, -- Linux supports reflecting either of the axes,
reflect_y = false, -- effectively flipping the image like a mirror
}
```
---
**Show/hide the mouse cursor.**
```lua
defos.set_cursor_visible(bool_value)
bool_value = defos.is_cursor_visible()
```
---
**Respond to the mouse entering and leaving** the game view area.
```lua
bool_value = defos.is_mouse_in_view()
defos.on_mouse_enter(function ()
print("Mouse entered view")
end)
defos.on_mouse_leave(function ()
print("Mouse left view")
end)
```
---
**Get the cursor position**.
```lua
x, y = defos.get_cursor_pos() -- In screen coordinates
x, y = defos.get_cursor_pos_view() -- In game view coordinates
```
---
**Move the cursor** programatically.
Not supported on HTML5.
```lua
defos.set_cursor_pos(x, y) -- In screen coordinates
defos.set_cursor_pos_view(x, y) -- In game view coordinates
```
---
**Clip cursor** to current game view area.
Not supported on Linux and HTML5.
```lua
defos.set_cursor_clipped(bool_value)
bool_value = defos.is_cursor_clipped()
```
---
**Lock cursor movement**.
On HTML5 this only works from `defos.on_click()` or `defos.on_interaction()`.
Not supported on Linux yet.
```lua
defos.set_cursor_locked(bool_value)
bool_value = defos.is_cursor_locked()
defos.on_cursor_lock_disabled(function ()
print("Called on HTML5 when the user presses ESC and the browser disables locking");
end)
```
---
**Load custom hardware cursors**. `cursor_data` must be:
* On HTML5, an URL to an image (data URLs work as well).
* On Windows, a path to an `.ani` or `.cur` file on the file system.
* On Linux, a path to an X11 cursor file on the file system.
* On macOS, a table of the form:
```lua
{
image = resource.load("cursor.tiff"),
hot_spot_x = 18,
hot_spot_y = 2,
}
```
On macOS, custom cursors can be any image file supported by `NSImage`, but it's
highly recommended to [create a TIFF][cursor-tiff] with two images, one at
72DPI (for low density displays) and another at 144DPI (for Retina displays).
The hotspot is an anchor point within the image that will overlap with the
functional position of the mouse pointer (eg. the tip of the arrow).
[cursor-tiff]: https://developer.apple.com/library/content/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Optimizing/Optimizing.html#//apple_ref/doc/uid/TP40012302-CH7-SW27
```lua
local cursor = defos.load_cursor(cursor_data)
```
---
**Set custom hardware cursors**. `cursor` can be one of the following:
* `nil`: Resets the cursor to default. Equivalent to `defos.reset_cursor()`.
* `defos.CURSOR_ARROW`
* `defos.CURSOR_HAND`
* `defos.CURSOR_CROSSHAIR`
* `defos.CURSOR_IBEAM`
* A `cursor` value obtained with `defos.load_cursor()`.
* A `cursor_data` value that will be used to create a single-use cursor. See `defos.load_cursor()` above for supported values.
```lua
defos.set_cursor(cursor)
defos.reset_cursor()
```
---
**Show/hide the console window** on Windows. Only works when not running
from the Editor.
```lua
defos.set_console_visible(bool_value)
bool_value = defos.is_console_visible()
```
---
On HTML5 only, **get a synchronous event on user interaction** with the canvas.
User interaction is either a mouse click, touch or key press.
This is necessary because some HTML5 functions only work when called
synchronously from an event handler.
This is currently needed for:
* `defos.toggle_fullscreen()`
* `defos.set_cursor_locked(true)`
```lua
defos.on_interaction(function ()
print("The user has interacted with the canvas. I have the chance to respond synchronously")
end)
defos.on_click(function ()
print("The user has clicked. I have the chance to respond synchronously")
end)
```
---
**Get the absolute path to the game's containing directory**. On macOS this
will be the path to the .app bundle. On HTML5 this will be the page URL up until
the last `/`.
```lua
path = defos.get_bundle_root()
```
---
**The system path separator.** `"\\"` on Windows, `"/"` everywhere else.
```lua
defos.PATH_SEP
```
---
**Change the game window's icon** at runtime. On Windows, this function accepts
`.ico` files. On macOS this accepts any image file supported by `NSImage`.
On Linux this function is not supported yet.
```lua
defos.set_window_icon(path_to_icon_file)
```
---
**Returns a table of command line arguments** used to run the app. On HTML5,
returns a table with a single string: the query string part of the URL
(eg. `{ "?param1=foo¶m2=bar" }`).
```lua
arguments = defos.get_arguments()
```
---
If you'd like to see any other features, open an issue.
## Example
An example is made using [DirtyLarry](https://github.com/andsve/dirtylarry)
