Appearance
screen
In CatScript, colors are represented in hexadecimal format (int type). For example:
| Name | Hex | CatScript Representation |
|---|---|---|
| Red | #FF0000 | 0xFF0000 |
| Green | #00FF00 | 0x00FF00 |
| Blue | #0000FF | 0x0000FF |
Color precision
precision=1.0 requires exact RGB equality. Lower values accept more color difference, and higher values are stricter.
screen.size()
Get the screen size.
python
screen.size() -> tuple[int, int]Arguments
None.
Return
| Type | Description |
|---|---|
| tuple[int, int] | The screen size in pixels. |
Example
python
from catscript import screen, sys
if __name__ == "__main__":
(w, h) = screen.size()
sys.log(f"Screen size: ({w}, {h}).")screen.snapshot()
Save a screenshot to a file.
python
screen.snapshot(path: str, region: tuple[int, int, int, int] = (0, 0, -1, -1), scale: float = 1.0) -> NoneArguments
| Name | Type | Default | Description |
|---|---|---|---|
| path | str | Path to save the screenshot. | |
| region | tuple[int, int, int, int] | (0, 0, -1, -1) | The capture region as (x1, y1, x2, y2). Use -1 for x2 or y2 to mean the screen edge. |
| scale | float | 1.0 | Screenshot scaling ratio, ranging from 0.1 to 1.0. |
Return
None.
Example
python
from catscript import screen
if __name__ == "__main__":
screen.snapshot("/tmp/snapshot.png", region=(0, 0, 500, 500), scale=0.5)screen.color()
Get the color at a screen coordinate.
python
screen.color(x: int, y: int) -> intArguments
| Name | Type | Default | Description |
|---|---|---|---|
| x | int | Coordinate x. | |
| y | int | Coordinate y. |
Return
| Type | Description |
|---|---|
| int | The color. |
Example
python
from catscript import screen, sys
if __name__ == "__main__":
color = screen.color(100, 100)
sys.log(f"The color is {color:#06x}.")screen.is_color()
Check whether the pixels at the given coordinates match the expected colors.
TIP
You can quickly generate the code for this function using the code template feature in CatScript's developer tools.
python
screen.is_color(colors: list[tuple[int, int, int]], precision: float = 1.0) -> boolArguments
| Name | Type | Default | Description |
|---|---|---|---|
| colors | list[tuple[int, int, int]] | The list of coordinate colors to compare. | |
| precision | float | 1.0 | Match strictness. 1.0 requires exact RGB equality; lower values are more tolerant. |
Return
| Type | Description |
|---|---|
| bool | Whether it meets the condition. |
Example
python
from catscript import screen, sys
if __name__ == "__main__":
if screen.is_color(
[
(378, 474, 0x4D92B1),
(191, 357, 0x96988B),
(397, 232, 0x21808A),
],
precision=0.9,
):
sys.log("Yes.")
else:
sys.log("No.")screen.find_color()
Find pixels that match a color.
TIP
You can quickly generate the code for this function using the code template feature in CatScript's developer tools.
python
screen.find_color(color: int, offset: list[tuple[int, int, int]] = [], precision: float = 1.0, region: tuple[int, int, int, int] = (0, 0, -1, -1), max_miss: int = 0, all: bool = False) -> list[tuple[int, int]]Arguments
| Name | Type | Default | Description |
|---|---|---|---|
| color | int | The color to find. | |
| offset | list[tuple[int, int, int]] | [] | Additional color checks relative to each candidate. |
| precision | float | 1.0 | Match strictness. 1.0 requires exact RGB equality; lower values are more tolerant. |
| region | tuple[int, int, int, int] | (0, 0, -1, -1) | The region as (x1, y1, x2, y2). Use -1 for x2 or y2 to mean the screen edge. |
| max_miss | int | 0 | The number of offset checks that may fail. |
| all | bool | False | Whether to return all matching coordinates. |
Return
| Type | Description |
|---|---|
| list[tuple[int, int]] | Matching coordinates. (-1, -1) means no match was found. |
Example
python
from catscript import screen, sys
if __name__ == "__main__":
# Find the red color on the screen.
(x, y) = screen.find_color(0xFF0000)[0]
if x != -1 and y != -1:
sys.log(f"Color is at ({x}, {y}).")
else:
sys.log("Not found.")python
from catscript import screen, sys
if __name__ == "__main__":
# Find red color on the screen, assuming its coordinates are (x, y), with the requirement:
# - the color at the position (x + 10, y - 10) is green
# - the color at the position (x + 20, y + 30) is blue.
(x, y) = screen.find_color(
0xFF0000, offset=[(10, -10, 0x00FF00), (20, 30, 0x0000FF)]
)[0]
if x != -1 and y != -1:
sys.log(f"Color is at ({x}, {y}).")
else:
sys.log("Not found.")python
from catscript import screen, sys
if __name__ == "__main__":
# Find red color on the screen region (0, 0, 500, 500), assuming its coordinates are (x, y), with the requirement:
# - the color at the position (x + 10, y - 10) is green.
# - the color at the position (x + 20, y + 30) is blue.
#
# Additionally:
# - Precision is 0.9 when comparing colors.
# - Allow one offset check to fail.
# - Return all matching coordinates.
coordinates = screen.find_color(
0xFF0000,
offset=[(10, -10, 0x00FF00), (20, 30, 0x0000FF)],
precision=0.9,
region=(0, 0, 500, 500),
max_miss=1,
all=True,
)
if coordinates[0][0] != -1 and coordinates[0][1] != -1:
for index, (x, y) in enumerate(coordinates):
sys.log(f"<{index}>: ({x}, {y}).")
else:
sys.log("Not found.")screen.find_image()
Find an image on the screen.
python
screen.find_image(path: str, ignore: list[int] = [], precision: float = 1.0, region: tuple[int, int, int, int] = (0, 0, -1, -1), max_miss: int = 0, all: bool = False) -> list[tuple[int, int]]Arguments
| Name | Type | Default | Description |
|---|---|---|---|
| path | str | Path to the image to find. | |
| ignore | list[int] | [] | Colors to ignore during comparison, treated as transparent. |
| precision | float | 1.0 | Match strictness. 1.0 requires exact RGB equality; lower values are more tolerant. |
| region | tuple[int, int, int, int] | (0, 0, -1, -1) | The region as (x1, y1, x2, y2). Use -1 for x2 or y2 to mean the screen edge. |
| max_miss | int | 0 | The number of pixel checks that may fail. |
| all | bool | False | Whether to return all matching coordinates. |
Return
| Type | Description |
|---|---|
| list[tuple[int, int]] | Matching coordinates. (-1, -1) means no match was found. |
Example
python
from catscript import screen, sys
if __name__ == "__main__":
# Find the image of the path /tmp/a.png on the screen region (0, 0, 500, 500).
#
# Additionally:
# - Ignore white and black pixels (treated as transparent).
# - Precision is 0.9 when comparing colors.
# - Allow one pixel check to fail.
# - Return all matching coordinates.
(x, y) = screen.find_image(
"/tmp/a.png",
ignore=[0xFFFFFF, 0x000000],
precision=0.9,
region=(0, 0, 500, 500),
max_miss=1,
all=False,
)[0]
if x != -1 and y != -1:
sys.log(f"Image is at ({x}, {y}).")
else:
sys.log("Not found.")