diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index daa97e5d726..de93034e07e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -2,7 +2,7 @@ name: Bug report about: Report incorrect or outdated documentation title: '' -labels: bug +labels: '' assignees: '' --- @@ -11,3 +11,9 @@ assignees: '' **Issue description:** **URL to the documentation page:** + +If you know how to fix the issue you are reporting please +consider opening a pull request. We provide a tutorial on +using git here: https://contributing.godotengine.org/en/latest/organization/pull_requests/creating_pull_requests.html, +writing documentation at https://contributing.godotengine.org/en/latest/documentation/guidelines/index.html +and contributing to the class reference here: https://contributing.godotengine.org/en/latest/documentation/class_reference.html diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index cefdbcb1922..9b01966e08a 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -4,3 +4,11 @@ contact_links: - name: Godot community channels url: https://godotengine.org/community about: Please ask for technical support on one of the other community channels, not here. + + - name: Godot proposals + url: https://github.com/godotengine/godot-proposals + about: Please submit engine feature proposals on the Godot proposals repository, not here. + + - name: Main Godot repository + url: https://github.com/godotengine/godot + about: Report engine bugs on the main Godot repository diff --git a/.github/ISSUE_TEMPLATE/enhancement_request.md b/.github/ISSUE_TEMPLATE/enhancement_request.md index d6b2f3caa93..e2794aecf62 100644 --- a/.github/ISSUE_TEMPLATE/enhancement_request.md +++ b/.github/ISSUE_TEMPLATE/enhancement_request.md @@ -2,7 +2,7 @@ name: Enhancement request about: Suggest new documentation or improving existing documentation title: '' -labels: enhancement +labels: '' assignees: '' --- diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index df9f65e1362..33ddb49b13f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,8 +1,8 @@ diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 37a2e10d175..2fadf9a9424 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -9,5 +9,7 @@ updates: schedule: interval: "daily" ignore: - # ReadTheDocs is staying on v1. + # We need to decide on when we upgrade Sphinx manually, + # as historically, this has been proven to often imply larger changes + # (RTD compat, upgrading extensions, other dependencies, our content, etc.). - dependency-name: "sphinx" diff --git a/.github/workflows/build_offline_docs.yml b/.github/workflows/build_offline_docs.yml index 309ca8b717f..14b0a3b56af 100644 --- a/.github/workflows/build_offline_docs.yml +++ b/.github/workflows/build_offline_docs.yml @@ -1,5 +1,6 @@ name: Build documentation for offline usage on: + workflow_dispatch: schedule: # Every week on Monday at midnight (UTC). # This keeps the generated HTML documentation fresh. @@ -7,25 +8,82 @@ on: jobs: build: - runs-on: ubuntu-20.04 + # Don't run scheduled runs on forks unless the CI_OFFLINE_DOCS_CRON variable is set to 'true'. + # Manual runs can still be triggered as normal. + if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_OFFLINE_DOCS_CRON == 'true' }} + runs-on: ubuntu-24.04 + timeout-minutes: 180 + strategy: + max-parallel: 1 + fail-fast: false + matrix: + branch: + - master + - stable + - 3.6 + permissions: + contents: write steps: - - name: Checkout - uses: actions/checkout@v2 + - uses: actions/checkout@v5 + with: + ref: ${{ matrix.branch }} - - name: Install dependencies + - name: Get Python version + id: pythonv run: | - sudo pip3 install -r requirements.txt - sudo pip3 install codespell + echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT - # Build the HTML to upload it. - - name: Sphinx build + - name: Restore cached virtualenv + uses: actions/cache/restore@v4 + with: + key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }} + path: .venv + + - name: Install dependencies run: | - sphinx-build --color -d _build/doctrees -W . _build/html + python -m venv .venv + source .venv/bin/activate + python -m pip install -r requirements.txt + echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH + echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV + sudo apt update + sudo apt install parallel libwebp7 imagemagick - - uses: actions/upload-artifact@v2 + - name: Save virtualenv cache + uses: actions/cache/save@v4 with: - name: godot-docs-html + key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }} + path: .venv + + - name: Sphinx - Build HTML + run: make SPHINXOPTS='--color -j 4' html + + - uses: actions/upload-artifact@v4 + with: + name: godot-docs-html-${{ matrix.branch }} path: _build/html # Keep the current build and the previous build (in case a scheduled build failed). # This makes it more likely to have at least one successful build available at all times. retention-days: 15 + + - name: Sphinx - Build ePub + run: | + # Convert WebP images to PNG and replace references, so that ePub readers can display those images. + # The ePub 3.0 specification has WebP support, but it's not widely supported by apps and e-readers yet. + shopt -s globstar nullglob + parallel --will-cite convert {} {.}.png ::: {about,community,contributing,getting_started,img,tutorials}/**/*.webp + parallel --will-cite sed -i "s/\\.webp$/\\.png/g" ::: {about,community,contributing,getting_started,tutorials}/**/*.rst + + # Remove banners at the top of each page when building `latest`. + sed -i 's/"godot_is_latest": True/"godot_is_latest": False/' conf.py + sed -i 's/"godot_show_article_status": True/"godot_show_article_status": False/' conf.py + + make SPHINXOPTS='--color -j 4' epub + + - uses: actions/upload-artifact@v4 + with: + name: godot-docs-epub-${{ matrix.branch }} + path: _build/epub/GodotEngine.epub + # Keep the current build and the previous build (in case a scheduled build failed). + # This makes it more likely to have at least one successful build available at all times. + retention-days: 15 diff --git a/.github/workflows/check_urls.yml b/.github/workflows/check_urls.yml new file mode 100644 index 00000000000..7359b526e34 --- /dev/null +++ b/.github/workflows/check_urls.yml @@ -0,0 +1,36 @@ +name: 🌐 Check URLs +on: + schedule: + # Every Friday at 16:27 UTC. + # URLs can decay over time. Setting up a schedule makes it possible to be warned + # about dead links as soon as possible. + - cron: "27 16 * * FRI" + +jobs: + check-urls: + runs-on: ubuntu-24.04 + steps: + + - uses: actions/checkout@v5 + + - name: Restore lychee cache + uses: actions/cache@v4 + with: + path: .lycheecache + key: cache-lychee-${{ github.sha }} + restore-keys: cache-lychee- + + - name: Run lychee + uses: lycheeverse/lychee-action@v2 + with: + args: > + --base . + --no-progress + --cache + --max-cache-age 1d + --exclude-path _templates/ + --exclude-path classes/ + "**/*.md" "**/*.html" "**/*.rst" + + - name: Fail if there were link errors + run: exit ${{ steps.lc.outputs.exit_code }} diff --git a/.github/workflows/cherrypick.yml b/.github/workflows/cherrypick.yml new file mode 100644 index 00000000000..cb3b0fca665 --- /dev/null +++ b/.github/workflows/cherrypick.yml @@ -0,0 +1,75 @@ +name: Create Cherrypick PR + +on: + pull_request: + types: + - closed + branches: + # TODO: Extract this to an env variable? + - 'master' + +env: + # TODO: Add a way to handle multiple potential cherrypick targets. + TARGET_BRANCH: '4.3' + USERNAME: 'Godot Organization' + EMAIL: 'noreply@godotengine.org' + +jobs: + Create-cherrypick-PR: + # The cherrypick label is hardcoded because `contains()` doesn't seem to be able to use an environment variable as a second argument. + if: ${{ github.event.pull_request.merged == true && contains( github.event.pull_request.labels.*.name, 'cherrypick:4.3' ) }} + runs-on: ubuntu-24.04 + timeout-minutes: 10 + env: + # "Ternary" hack featured in the official docs. + # When using "Squash and merge", the commit hash is the last merge commit of the pull request merge branch. + # When using "Merge", the commit hash is the last commit to the head branch of the pull request. + # This is mildly error-prone, since in theory we could merge multiple commits without squashing. + # We are relying on human review of the generated PRs to catch that. + COMMIT_HASH: ${{ github.event.pull_request.commits > 1 && github.sha || github.event.pull_request.head.sha }} + PR_NUMBER: ${{ github.event.number }} + + permissions: + contents: write + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v5 + with: + ref: ${{ env.TARGET_BRANCH }} + + - name: Cherrypick Commit + id: cherrypick_commit + continue-on-error: true + # TODO: Maybe only fetch some branches? + run: | + git config user.name "${{ env.USERNAME }}" + git config user.email "${{ env.EMAIL }}" + git fetch + git cherry-pick -m 1 ${{ env.COMMIT_HASH }} + + - name: Create Pull Request + if: steps.cherrypick_commit.outcome == 'success' + uses: peter-evans/create-pull-request@v7 + with: + commit-message: 'Cherrypick to ${{ env.TARGET_BRANCH }}' + branch: 'cherrypick-${{ env.PR_NUMBER }}-${{ env.TARGET_BRANCH }}' + delete-branch: true + + # Configure the commit author. + author: '${{ env.USERNAME }} <${{ env.EMAIL }}>' + committer: '${{ env.USERNAME }} <${{ env.EMAIL }}>' + + # Configure the pull request. + title: 'Cherrypick ${{ env.PR_NUMBER }} to ${{ env.TARGET_BRANCH }}' + body: 'Cherrypick #${{ env.PR_NUMBER }} to ${{ env.TARGET_BRANCH }}.' + # TODO: Only add the bug or enhancement label, depending on which the original PR uses. + labels: 'bug,enhancement' + + - name: Handle failure + if: steps.cherrypick_commit.outcome == 'failure' + run: | + echo "Can't automatically cherrypick. Potential causes:" + echo "- PR has multiple commits. Did you squash and merge?" + echo "- Cherrypick did not apply cleanly and can't be auto-merged." diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2817110d1a2..56d772aab55 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,29 +1,55 @@ name: Continuous integration + on: push: pull_request: +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref_name }} + cancel-in-progress: true + jobs: build: - runs-on: ubuntu-20.04 + runs-on: ubuntu-24.04 + timeout-minutes: 120 steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v5 - - name: Install dependencies + - name: Style checks via pre-commit + uses: pre-commit/action@v3.0.1 + + - name: Custom RST checks (check-rst.sh) run: | - # Install tools used by `_tools/format.sh`. - sudo apt-get -qq update - sudo apt-get -qq install dos2unix recode - sudo pip3 install -r requirements.txt - sudo pip3 install codespell + bash ./_tools/check-rst.sh - - name: Linter checks + - name: Get Python version + id: pythonv run: | - bash _tools/format.sh - codespell -I _tools/codespell-ignore.txt -x _tools/codespell-ignore-lines.txt {about,community,development,getting_started,tutorials}/**/*.rst + echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT + + - name: Restore cached virtualenv + uses: actions/cache/restore@v4 + with: + key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }} + path: .venv + + - name: Install dependencies + run: | + python -m venv .venv + source .venv/bin/activate + python -m pip install -r requirements.txt + echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH + echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV + + - name: Save virtualenv cache + uses: actions/cache/save@v4 + with: + key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }} + path: .venv # Use dummy builder to improve performance as we don't need the generated HTML in this workflow. - name: Sphinx build run: | - sphinx-build --color -b dummy -d _build/doctrees -W . _build/html + source .venv/bin/activate + make SPHINXOPTS='--color -j 4 -W' dummy diff --git a/.github/workflows/sync_class_ref.yml b/.github/workflows/sync_class_ref.yml new file mode 100644 index 00000000000..e864e74e2e6 --- /dev/null +++ b/.github/workflows/sync_class_ref.yml @@ -0,0 +1,76 @@ +name: Sync Class Reference + +on: + workflow_dispatch: + # Scheduled updates only run on the default/master branch. + # Other branches need to be run manually (usually after a new release for that branch). + schedule: + # Run it at (European) night time every Saturday. + # The offset is there to try and avoid high load times. + - cron: '15 3 * * 6' + +# Make sure jobs cannot overlap. +concurrency: + group: classref-sync-ci-${{ github.ref_name }} + cancel-in-progress: true + +jobs: + build: + # Don't run scheduled runs on forks unless the CI_SYNC_CLASS_REF_CRON variable is set to 'true'. + # Manual runs can still be triggered as normal. + if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_SYNC_CLASS_REF_CRON == 'true' }} + name: Update class reference files based on the engine revision + runs-on: ubuntu-24.04 + timeout-minutes: 10 + env: + engine_rev: 'master' + permissions: + contents: write + pull-requests: write + + steps: + - name: Checkout the documentation repository + uses: actions/checkout@v5 + + - name: Checkout the engine repository + uses: actions/checkout@v5 + with: + repository: 'godotengine/godot' + # Use the appropriate branch for the documentation version. + ref: ${{ env.engine_rev }} + path: './.engine-src' + + - name: Store the engine revision + id: 'engine' + run: | + cd ./.engine-src + hash=$(git rev-parse HEAD) + hash_short=$(git rev-parse --short HEAD) + echo "Checked out godotengine/godot at $hash" + echo "rev_hash=$hash" >> $GITHUB_OUTPUT + echo "rev_hash_short=$hash_short" >> $GITHUB_OUTPUT + + - name: Remove old documentation + run: | + rm ./classes/class_*.rst + + - name: Build new documentation + run: | + ./.engine-src/doc/tools/make_rst.py --color -o ./classes -l en ./.engine-src/doc/classes ./.engine-src/modules ./.engine-src/platform + + - name: Submit a pull-request + uses: peter-evans/create-pull-request@v7 + with: + commit-message: 'classref: Sync with current ${{ env.engine_rev }} branch (${{ steps.engine.outputs.rev_hash_short }})' + branch: 'classref/sync-${{ steps.engine.outputs.rev_hash_short }}' + add-paths: './classes' + delete-branch: true + + # Configure the commit author. + author: 'Godot Organization ' + committer: 'Godot Organization ' + + # Configure the pull-request. + title: 'classref: Sync with current ${{ env.engine_rev }} branch (${{ steps.engine.outputs.rev_hash_short }})' + body: 'Update Godot API online class reference to match the engine at https://github.com/godotengine/godot/commit/${{ steps.engine.outputs.rev_hash }} (`${{ env.engine_rev }}`).' + labels: 'area:class reference,bug,enhancement' diff --git a/.gitignore b/.gitignore index c732858eecb..939fcce3986 100644 --- a/.gitignore +++ b/.gitignore @@ -1,13 +1,31 @@ +*.csv +!redirects.csv +.env + _build/ -env/ -__pycache__ -*.pyc *~ .directory .vs/ .vscode/ *.mo +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# Common environment files +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# User created Python virtual environment as described in the docs +godot-docs-venv/ + # Vim temp files *.swo *.swp @@ -40,3 +58,6 @@ logo.h # Output of list-unused-images.sh tool tmp-unused-images tmp-unused-images-history + +# Jetbrains IDE files +/.idea/ diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 00000000000..3c5eca4a6c1 --- /dev/null +++ b/.lycheeignore @@ -0,0 +1,32 @@ +# Don't read Godot's own URL schemes as web URLs. +user:\/\/.* +res:\/\/.* +uid:\/\/.* + +# Don't read WebSockets or TCP URLs as web URLs. +ws(s?):\/\/.* +tcp:\/\/.* + +# Security checks prevent checking the URLs of these websites automatically, +# typically returning 403 errors. +.*asecuritysite\.com.* +.*intel\.com.* +.*reddit\.com.* +.*inkscape.org.* +.*computerhope.com* + +# Don't check URLs from these websites due to frequent rate limits (error 429) or timeouts. +.*adobe\.com.* +.*gamedevartisan\.com.* +.*github\.com.* +.*gnu\.org.* +.*loopit\.dk.* +.*meta\.com.* +.*sourceforge\.io.* + +# Not a valid URL with the GET method, which lychee always sends. +# Mentioned in the class reference. +.*httpbin\.org\/post + +# Class reference mentions `example.com/index.php` in an example, which is 404. +.*example\.com.* diff --git a/.mailmap b/.mailmap index 3ad8821532d..5f4dd94676e 100644 --- a/.mailmap +++ b/.mailmap @@ -1,3 +1,4 @@ +31 <31eee384@gmail.com> <331300+31@users.noreply.github.com> Andreas Haas Andrew Conrad Andrii Doroshenko @@ -6,11 +7,16 @@ Chris Bradfield clayjohn clayjohn corrigentia <20541985+corrigentia@users.noreply.github.com> +DeeJayLSP +DeeJayLSP <60024671+DeeJayLSP@users.noreply.github.com> Frido Frido <43795127+mega-bit@users.noreply.github.com> +Hana - Piralein <48352564+Piralein@users.noreply.github.com> +hpnrep6 <57055412+hpnrep6@users.noreply.github.com> Hugo Locurcio Hugo Locurcio Ignacio Etcheverry +jsjtxietian Julian Murgia Kelly Thomas Leon Krause @@ -19,12 +25,18 @@ Max Hilbrunner Max Hilbrunner Michael Alexsander Nathan Lovato +Patrick Exner +Patrick Exner Paul Joannon <437025+paulloz@users.noreply.github.com> +Poommetee Ketson Rémi Verschelde -skyace65 -skyace65 +skyace65 +skyace65 +skyace65 +TheYellowArchitect TwistedTwigleg Will Nations -Yuri Roubinsky -Yuri Sizov +Yuri Rubinsky +Yuri Sizov +Yuri Sizov <11782833+YuriSizov@users.noreply.github.com> ZX-WT diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000000..8712366a668 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,17 @@ +default_language_version: + python: python3 + +repos: + - repo: https://github.com/codespell-project/codespell + rev: v2.3.0 + hooks: + - id: codespell + files: ^(about|community|engine_details|getting_started|tutorials)/.*\.rst$ + additional_dependencies: [tomli] + + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: fix-byte-order-marker + - id: mixed-line-ending + args: ['--fix=lf'] diff --git a/.readthedocs.yml b/.readthedocs.yml index 2bb166066b6..1a544429c1b 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -5,7 +5,9 @@ version: 2 build: - image: latest + os: ubuntu-22.04 + tools: + python: "3.11" sphinx: configuration: conf.py diff --git a/404.rst b/404.rst new file mode 100644 index 00000000000..0cf80c065a4 --- /dev/null +++ b/404.rst @@ -0,0 +1,63 @@ +:github_url: hide +:allow_comments: False + +Page not found +============== + +.. https://github.com/readthedocs/sphinx-notfound-page + +.. raw:: html + +

+ Sorry, we couldn't find that page. It may have been renamed or removed + in the version of the documentation you're currently browsing. +

+

+ If you're currently browsing the + latest version of the documentation, try browsing the + stable version of the documentation. +

+

+ Alternatively, use the + Search docs + box on the left or go to the homepage. +

+ + diff --git a/AUTHORS.md b/AUTHORS.md index 4ad910c7a66..6743ea6a9a0 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -4,7 +4,7 @@ Godot Engine is developed by a community of voluntary contributors who contribute on all areas, including writing and maintaining the documentation. It is impossible to list them all; nevertheless, this file aims at listing -the writers who contributed significant patches to this CC-BY licensed +the writers who contributed significant patches to this CC BY licensed documentation on the `godot-docs` repository. GitHub usernames are indicated in parentheses, or as sole entry when no other @@ -14,40 +14,57 @@ name is available. (in alphabetical order, with over 10 commits excluding merges) -Aaron Franke (aaronfranke) -Andrew Conrad (her001) -Andrii Doroshenko (Xrayez) -Arman (puchik) -Bastiaan Olij (BastiaanOlij) -bitbutter -Camille Mohr-Daurat (pouleyKetchoupp) -Chris Bradfield (cbscribe) -Clay John (clayjohn) -corrigentia -Fabio Alessandrelli (Faless) -FeralBytes -Frido (mega-bit) -George Marques (vnen) -Gerrit Großkopf (Grosskopf) -Griatch -Haoyu Qiu (timothyqiu) -Hugo Locurcio (Calinou) -Ignacio Roldán Etcheverry (neikeq) -Jérôme Gully (Nutriz) -Juan Linietsky (reduz) -Julian Murgia (StraToN) -Kelly Thomas (KellyThomas) -Leon Krause (leonkrause) -Matthew (skyace65) -Max Hilbrunner (mhilbrunner) -Michael Alexsander (YeldhamDev) -Nathan Lovato (NathanLovato) -Paul Joannon (paulloz) -Poommetee Ketson (Naryosha) -Rémi Verschelde (akien-mga) -Tomasz Chabora (KoBeWi) -TwistedTwigleg -Will Nations (willnationsdev) -Yuri Roubinsky (Chaosus) -Yuri Sizov (pycbouh) -ZX-WT + 31 + Aaron Franke (aaronfranke) + Adam Scott (adamscott) + Andrew Conrad (her001) + Andrii Doroshenko (Xrayez) + Arman (puchik) + AThousandShips + Bastiaan Olij (BastiaanOlij) + bitbutter + bruvzg + Camille Mohr-Daurat (pouleyKetchoupp) + Chris Bradfield (cbscribe) + Clay John (clayjohn) + corrigentia + Danil Alexeev (dalexeev) + Douglas Leão (DeeJayLSP) + Fabio Alessandrelli (Faless) + FeralBytes + Fredia Huya-Kouadio (m4gr3d) + Frido (mega-bit) + George Marques (vnen) + Gerrit Großkopf (Grosskopf) + Griatch + Hana - Piralein (Piralein) + Haoyu Qiu (timothyqiu) + hpnrep6 + Hugo Locurcio (Calinou) + Ignacio Roldán Etcheverry (neikeq) + Jérôme Gully (Nutriz) + Juan Linietsky (reduz) + Julian Murgia (StraToN) + Kelly Thomas (KellyThomas) + Leon Krause (leonkrause) + Marcel Admiraal (madmiraal) + Markus Sauermann (Sauermann) + Matthew (skyace65) + Max Hilbrunner (mhilbrunner) + Michael Alexsander (YeldhamDev) + Nathalie Galla (MurderVeggie) + Nathan Lovato (NathanLovato) + Patrick Exner (FlameLizard) + Paul Joannon (paulloz) + Poommetee Ketson (Noshyaar) + Raul Santos (raulsntos) + Rémi Verschelde (akien-mga) + smix8 + TheYellowArchitect + Tomasz Chabora (KoBeWi) + TwistedTwigleg + Will Nations (willnationsdev) + Yuri Rubinsky (Chaosus) + Yuri Sizov (YuriSizov) + ZX-WT + 谢天 (jsjtxietian) diff --git a/Makefile b/Makefile index f1fa052cfa9..200ce1c84e1 100644 --- a/Makefile +++ b/Makefile @@ -1,199 +1,37 @@ # Makefile for Sphinx documentation -# -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build -LATEXDEPS = latex dvipng +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SPHINXSOURCEDIR ?= . +SPHINXBUILDDIR ?= _build +SPHINXPAPER ?= +FILELIST ?= # User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +ifneq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 0) +define ERROR_MESSAGE +The '$(SPHINXBUILD)' command was not found! +Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to the full path of the '$(SPHINXBUILD)' executable. +Alternatively you can add the executable's directory to your PATH. +If you don't have Sphinx installed, grab it from http://sphinx-doc.org/ +endef +$(error ${ERROR_MESSAGE}) endif -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -t i18n . +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +COMMONSPHINXOPTS = $(PAPEROPT_$(SPHINXPAPER)) $(SPHINXOPTS) '$(SPHINXSOURCEDIR)' +DEFAULTSPHINXOPTS = -d $(SPHINXBUILDDIR)/doctrees $(COMMONSPHINXOPTS) -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext +.PHONY: help clean help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - @echo " dummy to run only the parse steps without generating output" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GodotEngine.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GodotEngine.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/GodotEngine" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GodotEngine" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + @$(SPHINXBUILD) -M help $(DEFAULTSPHINXOPTS) $(O) "$(SPHINXBUILDDIR)" +# This is used by https://github.com/godotengine/godot-docs-l10n +# See https://github.com/godotengine/godot-docs-l10n/blob/f157c0cacc8a6e542e06e96b983b27de91637f8b/update.sh#L92 gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) ../sphinx/templates - @echo - @echo "Build finished. The message catalogs are in ../sphinx/templates." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + $(SPHINXBUILD) -b gettext -t i18n $(COMMONSPHINXOPTS) ../sphinx/templates $(FILELIST) -dummy: - $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. No output." +%: + $(SPHINXBUILD) -M $@ $(DEFAULTSPHINXOPTS) $(O) "$(SPHINXBUILDDIR)"/$@ $(FILELIST) diff --git a/README.md b/README.md index 52ffec80c32..8684a8ba9ab 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,21 @@ They are meant to be parsed with the [Sphinx](https://www.sphinx-doc.org/) docum ## Download for offline use -You can [download an HTML copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html.zip) -for offline reading (updated every Monday). Extract the ZIP archive then open -the top-level `index.html` in a web browser. +To browse the documentation offline, you can download an HTML copy (updated every Monday): +[stable](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-stable.zip), +[latest](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-master.zip), +[3.6](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-3.6.zip). Extract +the ZIP archive then open the top-level `index.html` in a web browser. + +For mobile devices or e-readers, you can also download an ePub copy (updated every Monday): +[stable](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-stable.zip), +[latest](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-master.zip), +[3.6](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-3.6.zip). Extract +the ZIP archive then open the `GodotEngine.epub` file in an e-book reader application. ## Theming -The Godot documentation uses the default ``sphinx_rtd_theme`` with many +The Godot documentation uses the default `sphinx_rtd_theme` with many [customizations](_static/) applied on top. It will automatically switch between the light and dark theme depending on your browser/OS' theming preference. @@ -25,19 +33,20 @@ add-on. All contributors are welcome to help on the Godot documentation. -To get started, head to the [Contributing section](https://docs.godotengine.org/en/latest/community/contributing/index.html) of the online manual. There, you will find all the information you need to write and submit changes. +To get started, head to the [Contributing documentation](https://contributing.godotengine.org/en/latest/organization/how_to_contribute.html). There, you will find all the information you need to write and submit changes. Here are some quick links to the areas you might be interested in: -1. [Contributing to the online manual](https://docs.godotengine.org/en/latest/community/contributing/contributing_to_the_documentation.html) -2. [Contributing to the class reference](https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html) -3. [Content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html) -4. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html) -5. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html) +1. [Contributing to the online manual](https://contributing.godotengine.org/en/latest/documentation/manual/index.html) +2. [Contributing to the class reference](https://contributing.godotengine.org/en/latest/documentation/class_reference.html) +3. [Content guidelines](https://contributing.godotengine.org/en/latest/documentation/guidelines/content_guidelines.html) +4. [Writing guidelines](https://contributing.godotengine.org/en/latest/documentation/guidelines/docs_writing_guidelines.html) +5. [Building the manual](https://contributing.godotengine.org/en/latest/documentation/manual/building_the_manual.html) +6. [Translating the documentation](https://contributing.godotengine.org/en/latest/documentation/translation/index.html) ## License -At the exception of the `classes/` folder, all the content of this repository is licensed under the Creative Commons Attribution 3.0 Unported license ([CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)) and is to be attributed to "Juan Linietsky, Ariel Manzur and the Godot community". +With the exception of the `classes/` folder, all the content of this repository is licensed under the Creative Commons Attribution 3.0 Unported license ([CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)) and is to be attributed to "Juan Linietsky, Ariel Manzur and the Godot community". See [LICENSE.txt](/LICENSE.txt) for details. The files in the `classes/` folder are derived from [Godot's main source repository](https://github.com/godotengine/godot) and are distributed under the MIT license, with the same authors as above. diff --git a/_extensions/gdscript.py b/_extensions/gdscript.py index 77aefc17c2a..1dac79fd0e7 100644 --- a/_extensions/gdscript.py +++ b/_extensions/gdscript.py @@ -9,45 +9,39 @@ :license: MIT. modified by Daniel J. Ramirez based on the original python.py pygment + further expanded and consolidated with the godot-docs lexer by Zackery R. Smith and Ste. """ -import re - -from pygments.lexer import ( - RegexLexer, - include, - bygroups, - default, - words, - combined, -) +from pygments.lexer import RegexLexer, include, bygroups, words, combined from pygments.token import ( - Text, - Comment, - Operator, Keyword, + Literal, Name, + Comment, String, Number, + Operator, + Whitespace, Punctuation, ) __all__ = ["GDScriptLexer"] -line_re = re.compile(".*?\n") - class GDScriptLexer(RegexLexer): """ - For `GDScript source code `_. + For GDScript source code. """ name = "GDScript" + url = "https://www.godotengine.org" aliases = ["gdscript", "gd"] filenames = ["*.gd"] mimetypes = ["text/x-gdscript", "application/x-gdscript"] - def innerstring_rules(ttype): + # taken from pygments/gdscript.py + @staticmethod + def inner_string_rules(ttype): return [ # the old style '%s' % (...) string formatting ( @@ -55,7 +49,7 @@ def innerstring_rules(ttype): "[hlL]?[E-GXc-giorsux%]", String.Interpol, ), - # backslashes, quotes and formatting signs must be parsed one at a time + # backslashes, quotes, and formatting signs must be parsed one at a time (r'[^\\\'"%\n]+', ttype), (r'[\'"\\]', ttype), # unhandled string formatting sign @@ -64,221 +58,259 @@ def innerstring_rules(ttype): ] tokens = { - "root": [ - (r"\n", Text), - ( - r'^(\s*)([rRuUbB]{,2})("""(?:.|\n)*?""")', - bygroups(Text, String.Affix, String.Doc), - ), - ( - r"^(\s*)([rRuUbB]{,2})('''(?:.|\n)*?''')", - bygroups(Text, String.Affix, String.Doc), - ), - (r"[^\S\n]+", Text), + "whitespace": [(r"\s+", Whitespace)], + "comment": [ + (r"##.*$", Comment.Doc), + (r"#(?:end)?region.*$", Comment.Region), (r"#.*$", Comment.Single), - (r"[]{}:(),;[]", Punctuation), - (r"\\\n", Text), - (r"\\", Text), - (r"(in|and|or|not)\b", Operator.Word), - ( - r"!=|==|<<|>>|&&|\+=|-=|\*=|/=|%=|&=|\|=|\|\||[-~+/*%=<>&^.!|$]", - Operator, - ), - include("keywords"), - (r"(func)((?:\s|\\\s)+)", bygroups(Keyword, Text), "funcname"), - (r"(class)((?:\s|\\\s)+)", bygroups(Keyword, Text), "classname"), - include("builtins"), - ( - '([rR]|[uUbB][rR]|[rR][uUbB])(""")', - bygroups(String.Affix, String.Double), - "tdqs", - ), - ( - "([rR]|[uUbB][rR]|[rR][uUbB])(''')", - bygroups(String.Affix, String.Single), - "tsqs", - ), - ( - '([rR]|[uUbB][rR]|[rR][uUbB])(")', - bygroups(String.Affix, String.Double), - "dqs", - ), - ( - "([rR]|[uUbB][rR]|[rR][uUbB])(')", - bygroups(String.Affix, String.Single), - "sqs", - ), - ( - '([uUbB]?)(""")', - bygroups(String.Affix, String.Double), - combined("stringescape", "tdqs"), - ), - ( - "([uUbB]?)(''')", - bygroups(String.Affix, String.Single), - combined("stringescape", "tsqs"), - ), - ( - '([uUbB]?)(")', - bygroups(String.Affix, String.Double), - combined("stringescape", "dqs"), - ), - ( - "([uUbB]?)(')", - bygroups(String.Affix, String.Single), - combined("stringescape", "sqs"), - ), - include("name"), - include("numbers"), ], - "keywords": [ + "punctuation": [ + (r"[]{}(),:;[]", Punctuation), + (r":\n", Punctuation), + (r"\\", Punctuation), + ], + # NOTE: from github.com/godotengine/godot-docs + "keyword": [ ( words( ( - "and", - "in", - "not", - "or", - "as", - "breakpoint", + # modules/gdscript/gdscript.cpp - GDScriptLanguage::get_reserved_words() + # Declarations. "class", "class_name", + "const", + "enum", "extends", - "is", "func", - "setget", + "namespace", # Reserved for potential future use. "signal", - "tool", - "const", - "enum", - "export", - "onready", "static", + "trait", # Reserved for potential future use. "var", + # Other keywords. + "await", + "breakpoint", + "self", + "super", + "yield", # Reserved for potential future use. + # Not really keywords, but used in property syntax. + # also colored like functions, not keywords + #"set", + #"get", + ), + suffix=r"\b", + ), + Keyword, + ), + ( + words( + ( + # modules/gdscript/gdscript.cpp - GDScriptLanguage::get_reserved_words() + # Control flow. "break", "continue", - "if", "elif", "else", "for", + "if", + "match", "pass", "return", - "match", + "when", "while", - "remote", - "master", - "puppet", - "remotesync", - "mastersync", - "puppetsync", + "yield", ), suffix=r"\b", ), - Keyword, + # Custom control flow class used to give control flow keywords a different color, + # like in the Godot editor. + Keyword.ControlFlow, ), ], - "builtins": [ + "builtin": [ + ( + words( + ("true", "false", "PI", "TAU", "NAN", "INF", "null"), + prefix=r"(?>|&&|\+=|-=|\*=|/=|%=|&=|\|=|\|\||[-~+/*%=<>&^.!|$]", + Operator, + ), + (r"(in|is|and|as|or|not)\b", Operator.Word), + ], + "number": [ + (r"([\d_]+\.[\d_]*|[\d_]*\.[\d_]+)([eE][+-]?[\d_]+)?", Number.Float), + (r"[\d_]+[eE][+-]?[\d_]+", Number.Float), + (r"0[xX][a-fA-F\d_]+", Number.Hex), + (r"(-)?0[bB]([01]|(?<=[01])_)+", Number.Bin), + (r"[\d_]+", Number.Integer), ], "name": [(r"[a-zA-Z_]\w*", Name)], - "funcname": [(r"[a-zA-Z_]\w*", Name.Function, "#pop"), default("#pop")], - "classname": [(r"[a-zA-Z_]\w*", Name.Class, "#pop")], - "stringescape": [ + "typehint": [ + (r"[a-zA-Z_]\w*", Name.Class, "#pop"), + ], + "string_escape": [ ( r'\\([\\abfnrtv"\']|\n|N\{.*?\}|u[a-fA-F0-9]{4}|' - r"U[a-fA-F0-9]{8}|x[a-fA-F0-9]{2}|[0-7]{1,3})", + r"U[a-fA-F0-9]{6}|x[a-fA-F0-9]{2}|[0-7]{1,3})", String.Escape, ) ], - "strings-single": innerstring_rules(String.Single), - "strings-double": innerstring_rules(String.Double), - "dqs": [ + "string_single": inner_string_rules(String.Single), + "string_double": inner_string_rules(String.Double), + "string_other": inner_string_rules(String.Other), + "string_stringname": inner_string_rules(String.StringName), + "string_nodepath": inner_string_rules(String.NodePath), + "double_quotes": [ (r'"', String.Double, "#pop"), (r'\\\\|\\"|\\\n', String.Escape), # included here for raw strings - include("strings-double"), + include("string_double"), ], - "sqs": [ + "single_quotes": [ (r"'", String.Single, "#pop"), (r"\\\\|\\'|\\\n", String.Escape), # included here for raw strings - include("strings-single"), + include("string_single"), ], - "tdqs": [ + "triple_double_quotes": [ (r'"""', String.Double, "#pop"), - include("strings-double"), - (r"\n", String.Double), + include("string_double"), + include("whitespace"), ], - "tsqs": [ + "triple_single_quotes": [ (r"'''", String.Single, "#pop"), - include("strings-single"), - (r"\n", String.Single), + include("string_single"), + include("whitespace"), + ], + "node_reference": [ + (r'[\$%]"', String.Other, include("node_reference_double")), + (r"[\$%]'", String.Other, include("node_reference_single")), + (r"[\$%][A-Za-z_][\w/]*/?", String.Other), + ], + "node_reference_double": [ + (r'"', String.Other, "#pop"), + include("string_other"), + ], + "node_reference_single": [ + (r"'", String.Other, "#pop"), + include("string_other"), + ], + "stringname": [ + (r'[&]"', String.StringName, include("stringname_double")), + (r"[&]'", String.StringName, include("stringname_single")), + ], + "stringname_double": [ + (r'"', String.StringName, "#pop"), + include("string_stringname"), + ], + "stringname_single": [ + (r"'", String.StringName, "#pop"), + include("string_stringname"), + ], + "nodepath": [ + (r'[\^]"', String.NodePath, include("nodepath_double")), + (r"[\^]'", String.NodePath, include("nodepath_single")), + ], + "nodepath_double": [ + (r'"', String.NodePath, "#pop"), + include("string_nodepath"), + ], + "nodepath_single": [ + (r"'", String.NodePath, "#pop"), + include("string_nodepath"), + ], + "function_name": [(r"[a-zA-Z_]\w*", Name.Function.Declaration, "#pop")], + "enum_name": [(r"[a-zA-Z_]\w*", Name, "#pop")], + "function": [ + (r"\b([a-zA-Z_]\w*)\s*(?=\()", Name.Function), + ( + # colored like functions, even without braces + words(("set", "get",), suffix=r"\b", ), + Name.Function, + ), + ], + + ####################################################################### + # LEXER ENTRY POINT + ####################################################################### + "root": [ + include("whitespace"), + include("comment"), + include("punctuation"), + include("builtin"), + # strings + include("stringname"), + include("nodepath"), + include("node_reference"), + ( + '(r)(""")', + bygroups(String.Affix, String.Double), + "triple_double_quotes", + ), + ( + "(r)(''')", + bygroups(String.Affix, String.Single), + "triple_single_quotes", + ), + ( + '(r)(")', + bygroups(String.Affix, String.Double), + "double_quotes", + ), + ( + "(r)(')", + bygroups(String.Affix, String.Single), + "single_quotes", + ), + ( + '(r?)(""")', + bygroups(String.Affix, String.Double), + combined("string_escape", "triple_double_quotes"), + ), + ( + "(r?)(''')", + bygroups(String.Affix, String.Single), + combined("string_escape", "triple_single_quotes"), + ), + ( + '(r?)(")', + bygroups(String.Affix, String.Double), + combined("string_escape", "double_quotes"), + ), + ( + "(r?)(')", + bygroups(String.Affix, String.Single), + combined("string_escape", "single_quotes"), + ), + # consider Name after a . as instance/members variables + (r"(?\n' + '\n' ) - context["metatags"] += description + if not ' for context. */ +.rst-content .align-right, +.rst-content .align-left { + clear: both; } .rst-content div.figure p.caption { @@ -232,15 +364,29 @@ article ol, .wy-plain-list-disc, .wy-plain-list-decimal, .rst-content ol.arabic, +.rst-content .toctree-wrapper ul { + /* Increase the line height slightly to account for the different font */ + line-height: 25px; +} + +/* Depending on the environment, it can be a section tag or a div with the section class. */ +.rst-content section ul, +.rst-content section ol, .rst-content .section ul, -.rst-content .toctree-wrapper ul, .rst-content .section ol { /* Increase the line height slightly to account for the different font */ line-height: 25px; } +.rst-content section ul li, +.rst-content .section ul li { + /* Increase spacing between list items. */ + margin-top: 8px; + margin-bottom: 8px; +} body, -.rst-content table.docutils thead { +.rst-content table.docutils thead, +.rst-content table.docutils caption { color: var(--body-color); } @@ -248,11 +394,6 @@ a { color: var(--link-color); } -.sphinx-tabs .sphinx-menu a.item { - /* Original definition has `!important` */ - color: var(--link-color) !important; -} - a:hover { color: var(--link-color-hover); text-decoration: underline; @@ -279,110 +420,207 @@ a.btn:hover { padding-right: 13px; } -/* Distinguish class reference page links from "user manual" page links with a "ref" badge. */ -a[href*="classes/"]::before { - content: "ref"; - color: var(--classref-badge-text-color); - background-color: hsla(0, 0%, 50%, 0.3); - font-weight: 700; - font-size: 80%; - border-radius: 9999px; +/* Style self-links to make them appear only on hover. */ +.classref-method > a[href*="-method-"].reference, +.classref-method > a[href*="-func-"].reference, +.classref-property > a[href*="-property-"].reference, +.classref-signal > a[href*="-signal-"].reference, +.classref-annotation > a[href*="-annotation-"].reference, +.classref-themeproperty > a[href*="-theme-"].reference, +.classref-method > a[href*="-method-"].reference, +.classref-constructor > a[href*="-constructor-"].reference, +.classref-operator > a[href*="-operator-"].reference, +.classref-constant > a[href*="-constant-"].reference, +.classref-enumeration > a[href^="#enum-"].reference { + visibility: hidden; + padding-left: 20px; + padding-right: 20px; +} +.classref-method:hover > a[href*="-method-"].reference, +.classref-method:hover > a[href*="-func-"].reference, +.classref-property:hover > a[href*="-property-"].reference, +.classref-signal:hover > a[href*="-signal-"].reference, +.classref-annotation:hover > a[href*="-annotation-"].reference, +.classref-themeproperty:hover > a[href*="-theme-"].reference, +.classref-method:hover > a[href*="-method-"].reference, +.classref-constructor:hover > a[href*="-constructor-"].reference, +.classref-operator:hover > a[href*="-operator-"].reference, +.classref-constant:hover > a[href*="-constant-"].reference, +.classref-enumeration:hover > a[href^="#enum-"].reference { + visibility: visible; + padding-left: 20px; + padding-right: 20px; +} + +/* Distinguish class reference page links from "user manual" page links with a class reference badge. */ + +/* Remove text wrapping so that the badge is always on the same line as the anchor's text. */ +.rst-content a[href*="classes/"] { + white-space: nowrap; +} +/* Add an icon as a badge, after the anchor's text. */ +.rst-content a[href*="classes/"]::after { + content: ""; + background-image: var(--class-reference-icon); + display: inline-block; + height: 16px; + width: 16px; padding: 0.125rem 0.375rem; - margin-right: 0.25rem; + margin-left: 0.25rem; } -/* Prevent the "ref" badge from appearing twice in the instant search results (not testable locally). */ -.wy-body-for-nav .search__result__single a[href*="classes/"]::before { +/* Prevent the class reference badge from appearing twice in the instant search results (not testable locally). */ +.wy-body-for-nav .search__result__single a[href*="classes/"]::after { display: none; } - -.wy-body-for-nav .search__result__single a[href*="classes/"]:first-child::before { - display: inline; +.wy-body-for-nav .search__result__single a[href*="classes/"]:first-child::after { + display: inline-block; } - -/* Prevent the "ref" badge from appearing several times per item in the dedicated search results page. */ -#search-results .context a[href*="classes/"]::before { +/* Prevent the class reference badge from appearing several times per item in the dedicated search results page. */ +#search-results .context a[href*="classes/"]::after { display: none; } +/* Stylize horizontal separator, mainly for the search results page. */ hr, #search-results .search li:first-child, #search-results .search li { border-color: var(--hr-color); } +/* Stylize the search results page. */ +#search-results .search-summary { + color: var(--footer-color); +} + +#search-results .context { + color: var(--search-context-color); + padding-left: 14px; + position: relative; +} + +#search-results .context:before { + content: "•"; + display: block; + position: absolute; + left: 0; + font-size: 120%; +} + +#search-results .search li { + background-color: var(--search-odd-color); + padding: 16px 14px; + border-radius: 6px; + border: none; + margin-bottom: 18px; +} + +#search-results .search li:first-child { + border: none; + padding: 16px 14px; + margin-top: 20px; +} + +#search-results .search li:nth-child(2n) { + background-color: var(--search-even-color); +} + +/* Add more visual separation for the title of a search result island. */ +#search-results .search li > a:first-child { + font-weight: 600; + font-size: 140%; +} + /* JavaScript documentation directives */ -.rst-content dl:not(.docutils) dt { +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dt, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl:not(.field-list) > dt { background-color: var(--admonition-note-background-color); border-color: var(--admonition-note-title-background-color); color: var(--admonition-note-color); } -.rst-content dl:not(.docutils) dl dt { - background-color: var(--admonition-attention-background-color); - border-color: var(--admonition-attention-title-background-color); - color: var(--admonition-attention-color); +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl dt { + background-color: transparent; + border-color: transparent; + color: var(--footer-color); } -.rst-content dl:not(.docutils).class dt, -.rst-content dl:not(.docutils).function dt, -.rst-content dl:not(.docutils).method dt, -.rst-content dl:not(.docutils).attribute dt { +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function dt, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).method dt, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).attribute dt { + font-weight: 600; + padding: 0 8px; + margin-bottom: 1px; width: 100%; } -.rst-content dl:not(.docutils).class > dt, -.rst-content dl:not(.docutils).function > dt, -.rst-content dl:not(.docutils).method > dt, -.rst-content dl:not(.docutils).attribute > dt { - font-size: 100%; +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class > dt, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function > dt, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).method > dt, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).attribute > dt { + font-family: var(--monospace-font-family); + font-variant-ligatures: none; + font-size: 90%; font-weight: normal; margin-bottom: 16px; padding: 6px 8px; } -.rst-content dl:not(.docutils) tt.descclassname, -.rst-content dl:not(.docutils) code.descclassname { - color: var(--highlight-type2-color); +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-prename.descclassname { + color: var(--highlight-engine-type-color); font-weight: normal; } -.rst-content dl:not(.docutils) tt.descname, -.rst-content dl:not(.docutils) code.descname { +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-name.descname { color: var(--highlight-function-color); - font-weight: normal; + font-weight: 700; } -.rst-content dl:not(.docutils) .sig-paren, -.rst-content dl:not(.docutils) .optional { - color: var(--highlight-operator-color); +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-paren, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .optional { + color: var(--highlight-operator-color) !important; font-weight: normal; padding: 0 2px; } -.rst-content dl:not(.docutils) .optional { +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .optional { font-style: italic; } -.rst-content dl:not(.docutils) .sig-param, -.rst-content dl:not(.docutils).class dt > em, -.rst-content dl:not(.docutils).function dt > em, -.rst-content dl:not(.docutils).method dt > em { +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-param, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt > em, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function dt > em, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).method dt > em { color: var(--code-literal-color); font-style: normal; padding: 0 4px; } -.rst-content dl:not(.docutils) .sig-param, -.rst-content dl:not(.docutils).class dt > .optional ~ em, -.rst-content dl:not(.docutils).function dt > .optional ~ em, -.rst-content dl:not(.docutils).method dt > .optional ~ em { +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .k { + font-style: normal; +} +html.writer-html5 .rst-content dl:not(.docutils) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { + border-top-color: var(--highlight-background-emph-color); + background: var(--highlight-background-color); +} +html.writer-html5 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { + border-left-color: var(--highlight-background-emph-color); + background: var(--highlight-background-color); +} +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-param, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt > .optional ~ em, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function dt > .optional ~ em, +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).method dt > .optional ~ em { color: var(--highlight-number-color); font-style: italic; } -.rst-content dl:not(.docutils).class dt > em.property { +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt > em.property { color: var(--highlight-keyword-color); } -.rst-content dl:not(.docutils) dt a.headerlink { - color: var(--link-color); +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dt a.headerlink { + color: var(--link-color) !important; } -.rst-content dl:not(.docutils) dt a.headerlink:visited { +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dt a.headerlink:visited { color: var(--link-color-visited); } +html.writer-html5 .rst-content dl.field-list > dd strong { + font-family: var(--monospace-font-family); + font-variant-ligatures: none; +} -footer, -#search-results .context { +footer { color: var(--footer-color); } @@ -493,29 +731,92 @@ footer, .wy-nav-content { background-color: var(--content-background-color); + max-width: 900px; } .wy-body-for-nav { + position: relative; background-color: var(--content-wrap-background-color); + overflow: visible; } @media only screen and (min-width: 769px) { .wy-body-for-nav { /* Center the page on wide displays for better readability */ - max-width: 1100px; + max-width: 1200px; margin: 0 auto; } } +/* Customize the look of tabbed panels, including code tabs. */ + +.rst-content [role="tablist"] { + border-bottom: none; +} + +.rst-content .sphinx-tabs-tab { + border-top: 4px solid transparent; + color: var(--link-color); + padding: 0.5rem 1.25rem; +} + +.rst-content .sphinx-tabs-tab[aria-selected="true"] { + background-color: var(--tabs-background-color); + border: none; + border-radius: 0; + border-top: 4px solid var(--tabs-selected-color); +} +.rst-content .sphinx-tabs-tab.code-tab[aria-selected="true"] { + background-color: var(--code-tabs-background-color); + border-top: 4px solid var(--code-tabs-selected-color); +} + +.rst-content .sphinx-tabs-tab:focus { + z-index: inherit; +} + +.rst-content .sphinx-tabs-panel { + background-color: var(--tabs-background-color); + border: none; + border-radius: 0; +} +.rst-content .sphinx-tabs-panel.code-tab { + background-color: var(--code-tabs-background-color); +} + +.rst-content .sphinx-tabs-panel div[class^="highlight"] { + border: none; + box-shadow: none; + margin-bottom: 2px; +} + +.rst-content div[class^="highlight"] pre { + font-variant-ligatures: none; + padding: 18px 16px; +} + /* Table display tweaks */ .rst-content table.docutils, +.wy-table-bordered-all { + border: 4px solid var(--code-border-color); +} + .wy-table-bordered-all td, -.rst-content table.docutils td, .wy-table thead th, +.rst-content table.docutils td, .rst-content table.docutils thead th, .rst-content table.field-list thead th { - border-color: var(--code-border-color); + border-bottom: 2px solid var(--code-border-color); + border-left: 2px solid var(--code-border-color); + padding: 4px 16px; +} + +html.writer-html5 .rst-content table.docutils th { + border-bottom: 4px solid var(--code-border-color); + border-left: 2px solid var(--code-border-color); + padding: 8px 16px; + vertical-align: middle; } .wy-table-odd td, @@ -530,29 +831,91 @@ footer, .wy-table-responsive table th:not(:nth-child(1)) { white-space: normal; } +/* Allow to control wrapping behavior per table */ +.wy-table-responsive table.wrap-normal td, +.wy-table-responsive table.wrap-normal th { + white-space: normal; +} +/* Turn nowrap on per-column */ +.wy-table-responsive table.nowrap-col1 td:nth-child(1), +.wy-table-responsive table.nowrap-col1 th:nth-child(1) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col2 td:nth-child(2), +.wy-table-responsive table.nowrap-col2 th:nth-child(2) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col3 td:nth-child(3), +.wy-table-responsive table.nowrap-col3 th:nth-child(3) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col4 td:nth-child(4), +.wy-table-responsive table.nowrap-col4 th:nth-child(4) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col5 td:nth-child(5), +.wy-table-responsive table.nowrap-col5 th:nth-child(5) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col6 td:nth-child(6), +.wy-table-responsive table.nowrap-col6 th:nth-child(6) { + white-space: nowrap; +} + +/* Make sure line blocks don't stretch tables */ +.wy-table-responsive table .line-block { + margin-bottom: 0; +} + /* Make sure not to wrap keyboard shortcuts */ .wy-table-responsive table td kbd { white-space: nowrap; } +/* Artificially increasing specificity to make it override theme.css. */ +html.writer-html5 .rst-content .wy-table-responsive > table td > p { + line-height: 1.425rem; +} +html.writer-html5 .rst-content .wy-table-responsive > table th > p { + line-height: 1.425rem; + font-size: .95rem; + font-weight: 600; +} + +html.writer-html5 .rst-content .wy-table-responsive > table td > p tt.literal, +html.writer-html5 .rst-content .wy-table-responsive > table td > p code.literal { + font-size: .85rem; + padding: 2px 5px; +} + /* Code display tweaks */ code, .rst-content tt, .rst-content code { - font-size: 14px; + font-size: .875em; + font-family: var(--monospace-font-family); + font-variant-ligatures: none; background-color: var(--code-background-color); - border: 1px solid var(--code-border-color); + border: none; + border-radius: 4px; } .rst-content tt.literal, .rst-content code.literal { color: var(--code-literal-color); + font-weight: 600; + font-variant-ligatures: none; + padding: 3px 5px; } .rst-content div[class^="highlight"] { - border-color: var(--code-border-color); + border: 3px solid var(--code-tabs-background-color); +} + +.rst-content div[class^="highlight"] div[class^="highlight"] { + box-shadow: none; } .rst-content pre.literal-block, @@ -561,6 +924,8 @@ code, /* Increase the font size and line height in code blocks */ font-size: 14px; line-height: 1.5; + font-family: var(--monospace-font-family); + font-variant-ligatures: none; } /* Code tab display tweaks */ @@ -574,6 +939,34 @@ code, .highlight { background-color: var(--highlight-background-color); + tab-size: 4; +} + +/* Remove default red boxes around Pygments errors */ +.highlight .err { + border: none; +} + +/* Default Pygments styles make all of these bold */ +.highlight .k /* Keyword */, +.highlight .ges /* Generic.EmphStrong */, +.highlight .gh /* Generic.Heading */, +.highlight .gp /* Generic.Prompt */, +.highlight .gs /* Generic.Strong */, +.highlight .gu /* Generic.Subheading */, +.highlight .kc /* Keyword.Constant */, +.highlight .kd /* Keyword.Declaration */, +.highlight .kn /* Keyword.Namespace */, +.highlight .kr /* Keyword.Reserved */, +.highlight .nc /* Name.Class */, +.highlight .nd /* Name.Decorator */, +.highlight .ni /* Name.Entity */, +.highlight .nl /* Name.Label */, +.highlight .nn /* Name.Namespace */, +.highlight .nt /* Name.Tag */, +.highlight .ow /* Operator.Word */, +.highlight .se /* Literal.String.Escape */ { + font-weight: revert; } /* Emphasized lines */ @@ -581,6 +974,10 @@ code, background-color: var(--highlight-background-emph-color); } +.highlight .n /* Name */ { + color: var(--body-color); +} + .highlight .gh /* Generic.Heading */, .highlight .gu /* Generic.Subheading */, .highlight .go /* Generic.Output */, @@ -607,11 +1004,19 @@ code, color: var(--highlight-keyword-color); } +.highlight .k-ControlFlow /* Keyword.ControlFlow */ { + color: var(--highlight-control-flow-keyword-color); +} + .highlight .ch /* Comment.Hashbang */, .highlight .cp /* Comment.Preproc */ { color: var(--highlight-keyword2-color); } +.highlight .l /* Literal */ { + color: var(--highlight-literal-color) +} + .highlight .m /* Literal.Number */, .highlight .mf /* Literal.Number.Float */, .highlight .mi /* Literal.Number.Integer */, @@ -631,7 +1036,7 @@ code, .highlight .nb /* Name.Builtin */, .highlight .ne /* Name.Exception */ { - color: var(--highlight-type-color); + color: var(--highlight-engine-type-color); } .highlight .nc /* Name.Class */, @@ -640,9 +1045,12 @@ code, .highlight .nv /* Name.Variable */, .highlight .vc /* Name.Variable.Class */, .highlight .vg /* Name.Variable.Global */, -.highlight .vi /* Name.Variable.Instance */, .highlight .vm /* Name.Variable.Magic */ { - color: var(--highlight-type2-color); + color: var(--highlight-user-type-color); +} + +.highlight .vi /* Name.Variable.Instance */ { + color: var(--highlight-member-variable-color); } .highlight .nf /* Name.Function */, @@ -652,6 +1060,7 @@ code, } .highlight .o /* Operator */, +.highlight .p /* Punctuation */, .highlight .si /* Literal.String.Interpol */, .highlight .sx /* Literal.String.Other */, .highlight .sr /* Literal.String.Regex */, @@ -673,18 +1082,92 @@ code, color: var(--highlight-string-color); } +.highlight .nf.nf-Declaration /* Name.Function.Declaration */ { + color: var(--highlight-function-declaration-color); +} + +.highlight .nb.nb-Type /* Name.Builtin.Type */ { + color: var(--highlight-base-type-color); +} + +.highlight .c.c-Doc /* Comment.Doc */ { + color: var(--highlight-doc-comment-color); +} + +.highlight .c.c-Region /* Comment.Region */ { + color: var(--highlight-region-comment-color); +} + +.highlight .nb.nb-Function /* Name.Builtin.Function */ { + color: var(--highlight-global-function-color); +} + +.highlight .sx /* String.Other */ { + color: var(--highlight-get-node-shorthand-color); +} + +.highlight .s.s-NodePath /* String.NodePath */ { + color: var(--highlight-node-path-color); +} + +.highlight .s.s-StringName /* String.StringName */ { + color: var(--highlight-string-name-color); +} + + +/* Call to action for missing documentation */ +.rst-content .contribute { + background-color: var(--contribute-background-color); + color: var(--contribute-text-color); + padding: 12px; + margin-bottom: 12px; +} + +.rst-content .contribute > p { + margin-bottom: 0; +} + /* Admonition tweaks */ +.rst-content .admonition-grid { + display: grid; + grid-template-columns: 1fr; + gap: 20px; +} +.rst-content .admonition-grid-2x { + grid-template-columns: 4fr 5fr; +} +@media screen and (max-width: 1020px) { + .rst-content .admonition-grid { + gap: 12px; + } + .rst-content .admonition-grid-2x { + grid-template-columns: 1fr; + } +} +.rst-content .admonition, .rst-content .admonition.note, .rst-content .admonition.seealso { background-color: var(--admonition-note-background-color); + border-radius: 4px; + box-shadow: 0px 3px 9px 0px rgb(0 0 0 / 29%); color: var(--admonition-note-color); } +.rst-content .admonition .admonition-title, .rst-content .admonition.note .admonition-title, .rst-content .admonition.seealso .admonition-title { background-color: var(--admonition-note-title-background-color); + border-radius: 4px 4px 0 0; color: var(--admonition-note-title-color); + font-weight: 600; + font-size: 105%; + line-height: 120%; + padding: 6px 16px; +} + +.rst-content .admonition .admonition-title:before { + margin-right: 9px; } .rst-content .admonition.attention, @@ -723,8 +1206,14 @@ code, color: var(--admonition-tip-title-color); } +.article-status strong { + color: var(--body-color); +} + /* Keyboard shortcuts tweaks */ -kbd, .kbd { +kbd, .kbd, +.rst-content :not(dl.option-list) > :not(dt):not(kbd):not(.kbd) > kbd, +.rst-content :not(dl.option-list) > :not(dt):not(kbd):not(.kbd) > .kbd { background-color: var(--kbd-background-color); border: 1px solid var(--kbd-outline-color); border-radius: 3px; @@ -737,6 +1226,206 @@ kbd, .kbd { vertical-align: middle; } +/* Unset excessive styles for nested kbd tags. */ +kbd.compound > kbd, +kbd.compound > .kbd, +.kbd.compound > kbd, +.kbd.compound > .kbd { + border: none; + box-shadow: none; + padding: 0; +} + +/* Class reference tweaks. */ + +.classref-section-separator { + border-color: var(--navbar-heading-color); + border-top-width: 3px; + margin: 36px 0; +} + +.classref-item-separator { + border-top-width: 2px; + margin: 26px 0; +} + +.classref-descriptions-group > p.classref-property, +.classref-descriptions-group > p.classref-signal, +.classref-descriptions-group > p.classref-annotation, +.classref-descriptions-group > p.classref-themeproperty, +.classref-descriptions-group > p.classref-method, +.classref-descriptions-group > div.classref-method.line-block, +.classref-descriptions-group > p.classref-constructor, +.classref-descriptions-group > p.classref-operator, +.classref-descriptions-group > p.classref-constant, +.classref-descriptions-group > p.classref-enumeration, +.classref-descriptions-group > p.classref-enumeration-constant { + color: var(--classref-secondary-color); + font-family: var(--monospace-font-family); + font-variant-ligatures: none; + font-size: 110%; + font-weight: 600; + margin-bottom: 18px; +} + +.classref-property { + margin-bottom: 12px; +} + +p + .classref-constant { + margin-top: 22px; +} + +.classref-descriptions-group > p.classref-enumeration-constant { + font-size: 100%; + margin-top: 18px; + margin-bottom: 14px; +} + +.classref-property > a, +.classref-signal > a, +.classref-annotation > a, +.classref-themeproperty > a, +.classref-method > a, +.classref-constructor > a, +.classref-operator > a, +.classref-constant > a, +.classref-enumeration > a { + opacity: 0.85; +} +.classref-enumeration-constant > a { + opacity: 0.75; +} + +.classref-property > a:hover, +.classref-signal > a:hover, +.classref-annotation > a:hover, +.classref-themeproperty > a:hover, +.classref-method > a:hover, +.classref-constructor > a:hover, +.classref-operator > a:hover, +.classref-constant > a:hover, +.classref-enumeration > a:hover, +.classref-enumeration-constant > a:hover { + opacity: 1; +} + +.classref-property > strong, +.classref-signal > strong, +.classref-annotation > strong, +.classref-themeproperty > strong, +.classref-method > strong, +.classref-constructor > strong, +.classref-operator > strong, +.classref-constant > strong, +.classref-enumeration > strong, +.classref-enumeration-constant > strong { + color: var(--classref-primary-color); +} + +.classref-property > code.literal, +.classref-signal > code.literal, +.classref-annotation > code.literal, +.classref-themeproperty > code.literal, +.classref-method > code.literal, +.classref-constructor > code.literal, +.classref-operator > code.literal, +.classref-constant > code.literal, +.classref-enumeration > code.literal, +.classref-enumeration-constant > code.literal { + background-color: transparent; + border: none; + padding: 0; + font-weight: 600; + font-size: 90% +} + +.classref-constant > code.literal, +.classref-enumeration-constant > code.literal { + color: var(--classref-setget-color); + font-weight: 400; +} + +/* Artificially increasing specificity to make it override theme.css. */ +.classref-descriptions-group ul.classref-property-setget { + color: var(--classref-setget-color); + font-size: 90%; + margin-bottom: 22px; +} + +.classref-property-setget > li { + line-height: 22px; +} + +.classref-property-setget p { + font-family: var(--monospace-font-family); + font-variant-ligatures: none; + font-size: 100%; + line-height: 22px; +} + +.classref-property-setget p > a { + opacity: 0.75; +} +.classref-property-setget p > a:hover { + opacity: 1; +} + +.classref-property-setget p > strong { + color: var(--classref-setget-color); +} + +.classref-property-setget p > code { + background-color: transparent; + border: none; + padding: 0; + font-weight: 600; +} + +.classref-descriptions-group { + margin-left: 24px; +} +#enumerations.classref-descriptions-group { + margin-left: 48px; +} + +.classref-descriptions-group > h2, +.classref-descriptions-group > hr { + margin-left: -24px; +} +#enumerations.classref-descriptions-group > h2, +#enumerations.classref-descriptions-group > hr { + margin-left: -48px; +} + +.classref-descriptions-group > p { + margin-bottom: 12px; +} + +.classref-descriptions-group .classref-property, +.classref-descriptions-group .classref-signal, +.classref-descriptions-group .classref-annotation, +.classref-descriptions-group .classref-themeproperty, +.classref-descriptions-group .classref-method, +.classref-descriptions-group .classref-constructor, +.classref-descriptions-group .classref-operator, +.classref-descriptions-group .classref-constant, +.classref-descriptions-group .classref-enumeration-constant { + margin-left: -24px; +} + +.classref-descriptions-group .classref-enumeration { + margin-left: -48px; +} + +.classref-reftable-group .wy-table-responsive { + margin-bottom: 36px; +} + +.classref-reftable-group .wy-table-responsive > table { + width: 100%; +} + /* Buttons */ .btn-neutral { @@ -758,15 +1447,23 @@ kbd, .kbd { opacity: var(--logo-opacity); } +.wy-side-nav-search > a { + padding: 0; + margin-bottom: 0.404em; + margin-top: 0.404em; +} + .wy-side-nav-search > a img.logo { /* Fixed size to prevent reflows and support hiDPI displays */ /* A 5 pixel margin is added on each side. The logo itself displays at 200×200 at 100% scaling. */ - width: 210px; - height: 210px; + width: 270px; + height: 70px; } .wy-side-nav-search { background-color: var(--navbar-background-color); + color: var(--navbar-level-1-color); + margin-right: 8px; } .wy-side-nav-search.fixed { @@ -818,7 +1515,22 @@ kbd, .kbd { opacity: 0.55; } -/* Navigation bar */ +/* Version branch label below the logo */ +.wy-side-nav-search > div.version { + color: var(--navbar-dimmed-color); + font-size: 14px; + opacity: 0.9; +} + +/* Navigational top bar (mobile only) */ + +.wy-nav-top, +.wy-nav-top a { + background-color: var(--navbar-background-color); + color: var(--navbar-level-1-color); +} + +/* Navigational sidebar */ .wy-nav-side { background-color: var(--navbar-background-color); @@ -839,92 +1551,132 @@ kbd, .kbd { letter-spacing: 0.75px; } -/* Mobile navigation */ +/* Default styling of navigation items */ -.wy-nav-top, -.wy-nav-top a { +.wy-menu-vertical li { background-color: var(--navbar-background-color); - color: var(--navbar-level-1-color); } - -/* Version branch label below the logo */ -.wy-side-nav-search > div.version { - color: var(--navbar-level-3-color); - opacity: 0.9; +.wy-menu-vertical li.current { + background-color: var(--navbar-current-background-color); } -/* First level of navigation items */ - -.wy-menu-vertical a { +.wy-menu-vertical li > a { color: var(--navbar-level-1-color); + font-size: 92%; + line-height: 20px; + padding: .4045em 1.618em; } - -.wy-menu-vertical a:hover { +.wy-menu-vertical li > a:hover { background-color: var(--navbar-background-color-hover); color: var(--navbar-level-1-color); } - -.wy-menu-vertical a:active { +.wy-menu-vertical li > a:active { background-color: var(--navbar-background-color-active); } -.wy-menu-vertical li.toctree-l1.current > a { - border: none; -} - -.wy-side-nav-search, .wy-menu-vertical a, .wy-menu-vertical a span.toctree-expand, -.wy-menu-vertical li.toctree-l2 a span.toctree-expand { - color: var(--navbar-level-3-color); +.wy-menu-vertical li > a button.toctree-expand { + color: var(--navbar-expand-base-color) !important; opacity: 0.9; margin-right: 8px; -} -.wy-side-nav-search, .wy-menu-vertical a, .wy-menu-vertical a:hover span.toctree-expand, -.wy-menu-vertical li.toctree-l2 a:hover span.toctree-expand { - color: var(--navbar-level-2-color); + /* Make the expand icon a bit easier to hit. */ + position: relative; + width: 12px; + min-width: 12px; /* Forces the size to stay this way in the flexbox model. */ + height: 18px; +} +.wy-menu-vertical li.current > a button.toctree-expand { + color: var(--navbar-current-color) !important; +} +.wy-menu-vertical li > a:hover button.toctree-expand { + color: var(--navbar-expand-hover-color) !important; opacity: 1; } - -.wy-side-nav-search, .wy-menu-vertical a, .wy-menu-vertical a:active span.toctree-expand, -.wy-menu-vertical li.toctree-l2 a:active span.toctree-expand { - color: var(--navbar-level-1-color); +.wy-menu-vertical li > a:active button.toctree-expand { + color: var(--navbar-expand-active-color) !important; opacity: 1; } -/* Second (and higher) levels of navigation items */ +/* Make the expand icon a bit easier to hit. */ +.wy-menu-vertical li > a button.toctree-expand:before { + position: absolute; + top: -2px; + left: -6px; + width: 24px; + height: 24px; + padding: 6px; +} + +.wy-menu-vertical li.current > a, +.wy-menu-vertical li.toctree-l2.current > a { + background-color: var(--navbar-current-background-color-hover); + border-bottom: 2px solid var(--navbar-current-background-color); + color: var(--navbar-current-color); + font-weight: 600; -.wy-menu-vertical li.current a { /* Make long words always display on a single line, keep wrapping for multiple words */ /* This fixes the class reference titles' display with very long class names */ display: flex; } +.wy-menu-vertical li.current > a:hover, +.wy-menu-vertical li.toctree-l2.current > a:hover { + background-color: var(--navbar-current-background-color-hover); +} +.wy-menu-vertical li.current > a:active, +.wy-menu-vertical li.toctree-l2.current > a:active { + background-color: var(--navbar-current-background-color-active); +} -.wy-menu-vertical li.current a, -.wy-menu-vertical li.toctree-l2.current > a, +/* Slightly adjust first level items. */ +.wy-menu-vertical li.toctree-l1 > a, +.wy-menu-vertical li.toctree-l1.current > a { + border: none; + padding: .4045em 1.918em; +} +.wy-menu-vertical li.toctree-l1.current > a { + border-bottom: 2px solid var(--navbar-current-background-color); +} + +/* Override styling for children of the current item. */ +.wy-menu-vertical li.current li > a, +.wy-menu-vertical li.toctree-l2.current li > a, .wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a, .wy-menu-vertical li.toctree-l2.current li.toctree-l4 > a { background-color: var(--navbar-current-background-color); + border: none; + border-bottom: 2px solid var(--navbar-current-background-color); color: var(--navbar-level-2-color); - border-color: var(--navbar-current-background-color); } - -.wy-menu-vertical li.current a:hover, -.wy-menu-vertical li.toctree-l2.current > a:hover, +.wy-menu-vertical li.current li > a:hover, +.wy-menu-vertical li.toctree-l2.current li > a:hover, .wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover, -.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a:hover { +.wy-menu-vertical li.toctree-l2.current li.toctree-l4 > a:hover { background-color: var(--navbar-current-background-color-hover); } - -.wy-menu-vertical li.current a:active, -.wy-menu-vertical li.toctree-l2.current > a:active, +.wy-menu-vertical li.current li > a:active, +.wy-menu-vertical li.toctree-l2.current li > a:active, .wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:active, -.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a:active { +.wy-menu-vertical li.toctree-l2.current li.toctree-l4 > a:active { background-color: var(--navbar-current-background-color-active); } -.wy-menu-vertical a { - /* This overrides 8px margin added in other multi-selector rules */ - margin-right: 0; +.wy-menu-vertical li.toctree-l2.current li > a, +.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a, +.wy-menu-vertical li.toctree-l2.current li.toctree-l4 > a { + color: var(--navbar-level-3-color); +} +.wy-menu-vertical li.toctree-l2.current li > a:hover, +.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover, +.wy-menu-vertical li.toctree-l2.current li.toctree-l4 > a:hover { + color: var(--navbar-level-1-color); +} + +.wy-menu-vertical li.current li.current > a, +.wy-menu-vertical li.toctree-l2.current li.current > a, +.wy-menu-vertical li.toctree-l2.current li.toctree-l3.current > a, +.wy-menu-vertical li.toctree-l2.current li.toctree-l4.current > a { + color: var(--navbar-current-color); + font-weight: 600; } /* Banner panel in sidebar */ @@ -932,12 +1684,27 @@ kbd, .kbd { position: fixed; } -/* Version selector (only visible on Read the Docs) */ +/* Read the Docs flyout panel, with language and version selectors. */ .rst-versions { background-color: var(--navbar-current-background-color); } +.rst-versions.shift-up { + overflow: visible; +} + +.rst-versions.shift-up:before { + content: ''; + position: absolute; + left: 0; + top: -8px; + width: 100%; + height: 8px; + pointer-events: none; + background: linear-gradient(transparent, hsla(0, 0%, 0%, 0.2)); +} + @media only screen and (min-width: 769px) { .rst-versions { /* Required to center the page on wide displays */ @@ -952,36 +1719,67 @@ kbd, .kbd { color: var(--navbar-level-1-color); } +.rst-versions .rst-current-version, +.rst-versions .rst-other-versions { + padding: 12px 14px; +} + +.rst-versions .rst-other-versions { + color: var(--navbar-heading-color); +} + +.rst-versions .rst-other-versions dl + dl { + margin-top: 4px; +} + +.rst-versions .rst-other-versions hr { + border-color: var(--hr-color); + margin: 12px 0; +} + .rst-versions .rst-other-versions small { - color: var(--navbar-level-3-color); + color: var(--navbar-dimmed-color); } .rst-versions .rst-other-versions dd a:hover { text-decoration: underline; } -.rst-versions .rst-other-versions { - color: var(--navbar-heading-color); +/* This will hide every segment of the panel, starting with the 4th. */ +.rst-versions .rst-other-versions .injected dl:nth-child(n+4) { + display: none; } .rst-versions .rst-current-version { background-color: var(--navbar-current-background-color); + border-bottom: 1px solid var(--hr-color); } - .rst-versions .rst-current-version:hover { background-color: var(--navbar-current-background-color-hover); } - .rst-versions .rst-current-version:active { background-color: var(--navbar-current-background-color-active); } -/* Hide the obnoxious automatic highlight in search results */ +.rst-versions .rst-current-version .fa { + line-height: 20px; +} + +/* Hide the obnoxious automatic highlight from the search context. */ .rst-content .highlighted { background-color: transparent; + box-shadow: none; font-weight: inherit; padding: 0; } +/* Still slightly highlight matched parts on the dedicated search results page. */ +.rst-content #search-results .highlighted { + background-color: var(--search-highlighted-color); + border-radius: 2px; + color: var(--body-color); + font-weight: 600; + padding: 0 3px; +} /* Allows the scrollbar to be shown in the sidebar */ @media only screen and (min-width: 769px) { @@ -998,6 +1796,7 @@ kbd, .kbd { overflow-y: auto; overflow-x: hidden; max-height: calc(100% - 348px); + padding-bottom: 24px; } @media screen and (max-width: 768px) { .wy-nav-side { @@ -1029,3 +1828,125 @@ kbd, .kbd { .wy-menu.wy-menu-vertical::-webkit-scrollbar-thumb:active { background-color: var(--navbar-scrollbar-active-color); } + +/* Allows to add a green or red bar to code blocks for "good"/"bad" code examples. */ +.code-example-good div.highlight { + border-left-color: var(--code-example-good-color); + border-left-width: 8px; +} +.code-example-bad div.highlight { + border-left-color: var(--code-example-bad-color); + border-left-width: 8px; +} + +/* Togglable sidebar sections. */ +.wy-menu-vertical p.caption { + cursor: pointer; +} +.wy-menu-vertical p.caption.active { + background-color: var(--navbar-category-active-color); +} +.wy-menu-vertical p.caption:hover { + background-color: var(--navbar-background-color-hover); +} + +.wy-menu-vertical p.caption.active .caption-text:before { + transform: rotate(90deg); +} +.wy-menu-vertical p.caption .caption-text:before { + content: "❯"; + display: inline-block; + margin-left: -4px; + transition: transform 0.2s; + width: 16px; + height: 32px; + transform-origin: 2px 16px; +} + +.wy-menu-vertical p.caption + ul { + display: none; +} +.wy-menu-vertical p.caption + ul.active { + display: block; +} + +.highlight button.copybtn { + background-color: var(--copybtn-background-color); + border-color: var(--copybtn-border-color); + box-shadow: var(--copybtn-box-shadow); + width: 32px; + height: 32px; + right: 0; + top: 0; + margin: 12.25px; +} +.highlight button.copybtn:hover { + background-color: var(--copybtn-background-color-hover); + border-color: var(--copybtn-border-color-hover); +} +.highlight button.copybtn svg { + position: absolute; + left: 3.5px; + top: 3.5px; + color: var(--copybtn-icon-color); + pointer-events: none; +} +.highlight button.copybtn.success { + border-color: var(--copybtn-border-color-success); + box-shadow: 0 0 0 0.2em rgb(52 208 88 / 40%); +} +.highlight button.copybtn.success svg { + color: var(--copybtn-icon-color-success); +} +.o-tooltip--left:after { + background-color: var(--copybtn-tooltip-background-color); + color: #ffffff; + border-radius: 6px; + padding: 0.5em 0.75em; +} + +/* Allow :abbr: tags' content to be displayed on mobile platforms by tapping the word */ +@media (hover: none), (hover: on-demand), (-moz-touch-enabled: 1), (pointer:coarse) { + /* Do not enable on desktop platforms to avoid doubling the tooltip */ + abbr[title] { + position: relative; + } + + abbr[title]:hover::after, + abbr[title]:focus::after { + content: attr(title); + + position: absolute; + left: 0; + bottom: -32px; + width: auto; + white-space: nowrap; + + background-color: #1e1e1e; + color: #fff; + border-radius: 3px; + box-shadow: 1px 1px 5px 0 rgba(0, 0, 0, 0.4); + font-size: 14px; + padding: 3px 5px; + } +} + +/* Giscus */ +#godot-giscus { + margin-bottom: 1em; +} + +/* Custom Sphinx roles for editor UI */ +/* The :ui: and :inspector: roles just render as bold. */ +.role-ui { + font-weight: 700; +} + +.role-button, .role-menu { + font-size: 80%; + border-radius: 4px; + padding: 2.4px 6px; + margin: auto 2px; + border: 0px solid #7fbbe3; + background: var(--role-button-background-color); +} diff --git a/_static/css/dev.css b/_static/css/dev.css new file mode 100644 index 00000000000..87ad1d310e3 --- /dev/null +++ b/_static/css/dev.css @@ -0,0 +1,8 @@ +/** + * CSS tweaks that are only added outside ReadTheDocs (i.e. when built locally). + */ + +/* Re-add default red boxes around Pygments errors */ +.highlight .err { + border: 1px solid #FF0000; +} diff --git a/_static/css/fonts/JetBrainsMono-Bold.woff2 b/_static/css/fonts/JetBrainsMono-Bold.woff2 new file mode 100644 index 00000000000..023512c051e Binary files /dev/null and b/_static/css/fonts/JetBrainsMono-Bold.woff2 differ diff --git a/_static/css/fonts/JetBrainsMono-Medium.woff2 b/_static/css/fonts/JetBrainsMono-Medium.woff2 new file mode 100644 index 00000000000..484c9e64152 Binary files /dev/null and b/_static/css/fonts/JetBrainsMono-Medium.woff2 differ diff --git a/_static/css/fonts/JetBrainsMono-Regular.woff2 b/_static/css/fonts/JetBrainsMono-Regular.woff2 new file mode 100644 index 00000000000..8c862e334da Binary files /dev/null and b/_static/css/fonts/JetBrainsMono-Regular.woff2 differ diff --git a/_static/css/fonts/Montserrat-Bold.woff2 b/_static/css/fonts/Montserrat-Bold.woff2 new file mode 100644 index 00000000000..49cceae9d2a Binary files /dev/null and b/_static/css/fonts/Montserrat-Bold.woff2 differ diff --git a/_static/js/custom.js b/_static/js/custom.js index 7bef3875144..49cd5fc2618 100644 --- a/_static/js/custom.js +++ b/_static/js/custom.js @@ -1,9 +1,3 @@ - -// Set this to `true` when the `latest` branch is significantly incompatible with the -// current `stable` branch, which can lead to confusion for users that land on -// `latest` instead of `stable`. -const inDev = true; - // Handle page scroll and adjust sidebar accordingly. // Each page has two scrolls: the main scroll, which is moving the content of the page; @@ -16,13 +10,13 @@ const registerOnScrollEvent = (function(){ // Configuration. // The number of pixels the user must scroll by before the logo is completely hidden. - const scrollTopPixels = 234; + const scrollTopPixels = 84; // The target margin to be applied to the navigation bar when the logo is hidden. - const menuTopMargin = 90; + const menuTopMargin = 70; // The max-height offset when the logo is completely visible. - const menuHeightOffset_default = 338; + const menuHeightOffset_default = 162; // The max-height offset when the logo is completely hidden. - const menuHeightOffset_fixed = 102; + const menuHeightOffset_fixed = 80; // The distance between the two max-height offset values above; used for intermediate values. const menuHeightOffset_diff = (menuHeightOffset_default - menuHeightOffset_fixed); @@ -54,7 +48,7 @@ const registerOnScrollEvent = (function(){ // Entering the "desktop" state. // The main scroll event handler. - // Executed as the page is scrolled and once immediatelly as the page enters this state. + // Executed as the page is scrolled and once immediately as the page enters this state. const handleMainScroll = (currentScroll) => { if (currentScroll >= scrollTopPixels) { // After the page is scrolled below the threshold, we fix everything in place. @@ -195,10 +189,133 @@ const registerSidebarObserver = (function(){ const observer = new MutationObserver(observerCallback); observer.observe(sidebarContainer, observerConfig); + + // Default TOC tree has links that immediately navigate to the selected page. Our + // theme adds an extra button to fold and unfold the tree without navigating away. + // But that means that the buttons are added after the initial load, so we need to + // improvise to detect clicks on these buttons. + const scrollElement = document.querySelector('.wy-menu-vertical'); + const registerLinkHandler = (linkChildren) => { + linkChildren.forEach(it => { + if (it.nodeType === Node.ELEMENT_NODE && it.classList.contains('toctree-expand')) { + it.addEventListener('click', () => { + // Toggling a different item will close the currently opened one, + // which may shift the clicked item out of the view. We correct for that. + const menuItem = it.parentNode; + const baseScrollOffset = scrollElement.scrollTop + scrollElement.offsetTop; + const maxScrollOffset = baseScrollOffset + scrollElement.offsetHeight; + + if (menuItem.offsetTop < baseScrollOffset || menuItem.offsetTop > maxScrollOffset) { + menuItem.scrollIntoView(); + } + + callback(); + }); + } + }); + } + + const navigationSections = document.querySelectorAll('.wy-menu-vertical ul'); + navigationSections.forEach(it => { + if (it.previousSibling == null || typeof it.previousSibling === 'undefined' || it.previousSibling.tagName != 'A') { + return; + } + + const navigationLink = it.previousSibling; + registerLinkHandler(navigationLink.childNodes); + + const linkObserverConfig = { childList: true }; + const linkObserverCallback = (mutationsList, observer) => { + for (let mutation of mutationsList) { + registerLinkHandler(mutation.addedNodes); + } + }; + + const linkObserver = new MutationObserver(linkObserverCallback); + linkObserver.observe(navigationLink, linkObserverConfig); + }); }; })(); +/** + * Registers Giscus if there's an #godot-giscus container. + * @returns {void} Nothing. + */ +const registerGiscus = function () { + const giscusContainer = document.getElementById("godot-giscus"); + if (giscusContainer == null) { + return; + } + + const removeGiscusContainer = function() { + giscusContainer.remove(); + }; + + const pageNameMetaElement = Array.from(document.head.querySelectorAll("meta")).find((meta) => meta.name === "doc_pagename"); + if (pageNameMetaElement == null) { + removeGiscusContainer(); + return; + } + + const pageNameDenyList = [ + "search" + ]; + if (pageNameDenyList.includes(pageNameMetaElement.content)) { + removeGiscusContainer(); + return; + } + + // Use https://giscus.app/ to regenerate the script tag if needed. + // data-term is set to be language-independent and version-independent, so that comments can be centralized for each page. + // This increases the likelihood that users will encounter comments on less frequently visited pages. + const scriptElement = document.createElement("script"); + scriptElement.src = "https://giscus.app/client.js"; + scriptElement.crossOrigin = "anonymous"; + scriptElement.async = true; + + const dataset = { + repo: "godotengine/godot-docs-user-notes", + repoId: "R_kgDOKuNx0w", + category: "User-contributed notes", + categoryId: "DIC_kwDOKuNx084CbANb", + mapping: "specific", + term: pageNameMetaElement.content, + strict: "1", + reactionsEnabled: "0", + emitMetadata: "0", + inputPosition: "bottom", + theme: "preferred_color_scheme", + lang: "en", + loading: "lazy", + }; + + for (const [key, value] of Object.entries(dataset)) { + scriptElement.dataset[key] = value; + } + + giscusContainer.append(scriptElement); +}; + $(document).ready(() => { + // Remove the search match highlights from the page, and adjust the URL in the + // navigation history. + const url = new URL(location.href); + if (url.searchParams.has('highlight')) { + Documentation.hideSearchWords(); + } + + window.addEventListener('keydown', function(event) { + if (event.key === '/') { + var searchField = document.querySelector('#rtd-search-form input[type=text]'); + if (document.activeElement !== searchField) { + searchField.focus(); + searchField.select(); + event.preventDefault(); + } + } + }); + + // Initialize handlers for page scrolling and our custom sidebar. const mediaQuery = window.matchMedia('only screen and (min-width: 769px)'); registerOnScrollEvent(mediaQuery); @@ -208,25 +325,110 @@ $(document).ready(() => { registerOnScrollEvent(mediaQuery); }); - if (inDev) { + // Add line-break suggestions to the sidebar navigation items in the class reference section. + // + // Some class reference pages have very long PascalCase names, such as + // VisualShaderNodeCurveXYZTexture + // Those create issues for our layout, as we can neither make them wrap with CSS without + // breaking normal article titles, nor is it good to have them overflow their containers. + // So we use a tag to insert mid-word suggestions for appropriate splits, so the browser + // knows that it's okay to split it like + // Visual Shader Node Curve XYZTexture + // and add a new line at an opportune moment. + const classReferenceLinks = document.querySelectorAll('.wy-menu-vertical > ul:last-of-type .reference.internal'); + for (const linkItem of classReferenceLinks) { + let textNode = null; + linkItem.childNodes.forEach(it => { + if (it.nodeType === Node.TEXT_NODE) { + // If this is a text node and if it needs to be updated, store a reference. + let text = it.textContent; + if (!(text.includes(" ") || text.length < 10)) { + textNode = it; + } + } + }); + + if (textNode != null) { + let text = textNode.textContent; + // Add suggested line-breaks and replace the original text. + // The regex looks for a lowercase letter followed by a number or an uppercase + // letter. We avoid splitting at the last character in the name, though. + text = text.replace(/([a-z])([A-Z0-9](?!$))/gm, '$1$2'); + + linkItem.removeChild(textNode); + linkItem.insertAdjacentHTML('beforeend', text); + } + } + + // Change indentation from spaces to tabs for codeblocks. + const codeBlocks = document.querySelectorAll('.rst-content div[class^="highlight"] pre'); + for (const codeBlock of codeBlocks) { + const classList = codeBlock.parentNode.parentNode.classList; + if (!classList.contains('highlight-gdscript') && !classList.contains('highlight-cpp')) { + // Only change indentation for GDScript and C++. + continue; + } + let html = codeBlock.innerHTML.replace(/^()?( {4})/gm, '\t'); + let html_old = ""; + while (html != html_old) { + html_old = html; + html = html.replace(/\t( {4})/gm, '\t\t') + } + codeBlock.innerHTML = html; + } + + // See `godot_is_latest` in conf.py + const isLatest = document.querySelector('meta[name=doc_is_latest]').content.toLowerCase() === 'true'; + if (isLatest) { // Add a compatibility notice using JavaScript so it doesn't end up in the // automatically generated `meta description` tag. - const strippedUrl = [location.protocol, '//', location.host, location.pathname].join(''); - const updatedUrl = strippedUrl.replace('/latest/', '/stable/'); - document.querySelector('div[itemprop="articleBody"]').insertAdjacentHTML('afterbegin', ` -
-

Attention

-

- You are reading the latest - (unstable) version of this documentation, which may document features not available - or compatible with Godot 3.2.x. -

-

- See this page - for the stable version of this documentation. -

-
- `); + + const baseUrl = [location.protocol, '//', location.host, location.pathname].join(''); + // These lines only work as expected in the production environment, can't test this locally. + const fallbackUrl = baseUrl.replace('/latest/', '/stable/'); + const homeUrl = baseUrl.split('/latest/')[0] + '/stable/'; + const searchUrl = homeUrl + 'search.html?q='; + + const noticeLink = document.querySelector('.latest-notice-link'); + + // Insert a placeholder to display as we're making a request. + noticeLink.innerHTML = ` + Checking the stable version + of the documentation... + `; + + // Make a HEAD request to the possible stable URL to check if the page exists. + fetch(fallbackUrl, { method: 'HEAD' }) + .then((res) => { + // We only check the HTTP status, which should tell us if the link is valid or not. + if (res.status === 200) { + noticeLink.innerHTML = ` + See the stable version + of this documentation page instead. + `; + } else { + // Err, just to fallthrough to catch. + throw Error('Bad request'); + } + }) + .catch((err) => { + let message = ` + This page does not exist in the stable version + of the documentation. + `; + + // Also suggest a search query using the page's title. It should work with translations as well. + // Note that we can't use the title tag as it has a permanent suffix. OG title doesn't, though. + const titleMeta = document.querySelector('meta[property="og:title"]'); + if (typeof titleMeta !== 'undefined') { + const pageTitle = titleMeta.getAttribute('content'); + message += ` + You can try searching for "${pageTitle}" instead. + `; + } + + noticeLink.innerHTML = message; + }); } // Load instant.page to prefetch pages upon hovering. This makes navigation feel @@ -237,4 +439,56 @@ $(document).ready(() => { /*! instant.page v5.1.0 - (C) 2019-2020 Alexandre Dieulot - https://instant.page/license */ instantPageScript.innerText = 'let t,e;const n=new Set,o=document.createElement("link"),i=o.relList&&o.relList.supports&&o.relList.supports("prefetch")&&window.IntersectionObserver&&"isIntersecting"in IntersectionObserverEntry.prototype,s="instantAllowQueryString"in document.body.dataset,a="instantAllowExternalLinks"in document.body.dataset,r="instantWhitelist"in document.body.dataset,c="instantMousedownShortcut"in document.body.dataset,d=1111;let l=65,u=!1,f=!1,m=!1;if("instantIntensity"in document.body.dataset){const t=document.body.dataset.instantIntensity;if("mousedown"==t.substr(0,"mousedown".length))u=!0,"mousedown-only"==t&&(f=!0);else if("viewport"==t.substr(0,"viewport".length))navigator.connection&&(navigator.connection.saveData||navigator.connection.effectiveType&&navigator.connection.effectiveType.includes("2g"))||("viewport"==t?document.documentElement.clientWidth*document.documentElement.clientHeight<45e4&&(m=!0):"viewport-all"==t&&(m=!0));else{const e=parseInt(t);isNaN(e)||(l=e)}}if(i){const n={capture:!0,passive:!0};if(f||document.addEventListener("touchstart",function(t){e=performance.now();const n=t.target.closest("a");if(!h(n))return;v(n.href)},n),u?c||document.addEventListener("mousedown",function(t){const e=t.target.closest("a");if(!h(e))return;v(e.href)},n):document.addEventListener("mouseover",function(n){if(performance.now()-e{v(o.href),t=void 0},l)},n),c&&document.addEventListener("mousedown",function(t){if(performance.now()-e1||t.metaKey||t.ctrlKey)return;if(!n)return;n.addEventListener("click",function(t){1337!=t.detail&&t.preventDefault()},{capture:!0,passive:!1,once:!0});const o=new MouseEvent("click",{view:window,bubbles:!0,cancelable:!1,detail:1337});n.dispatchEvent(o)},n),m){let t;(t=window.requestIdleCallback?t=>{requestIdleCallback(t,{timeout:1500})}:t=>{t()})(()=>{const t=new IntersectionObserver(e=>{e.forEach(e=>{if(e.isIntersecting){const n=e.target;t.unobserve(n),v(n.href)}})});document.querySelectorAll("a").forEach(e=>{h(e)&&t.observe(e)})})}}function p(e){e.relatedTarget&&e.target.closest("a")==e.relatedTarget.closest("a")||t&&(clearTimeout(t),t=void 0)}function h(t){if(t&&t.href&&(!r||"instant"in t.dataset)&&(a||t.origin==location.origin||"instant"in t.dataset)&&["http:","https:"].includes(t.protocol)&&("http:"!=t.protocol||"https:"!=location.protocol)&&(s||!t.search||"instant"in t.dataset)&&!(t.hash&&t.pathname+t.search==location.pathname+location.search||"noInstant"in t.dataset))return!0}function v(t){if(n.has(t))return;const e=document.createElement("link");e.rel="prefetch",e.href=t,document.head.appendChild(e),n.add(t)}'; document.head.appendChild(instantPageScript); + + // Make sections in the sidebar togglable. + let hasCurrent = false; + let menuHeaders = document.querySelectorAll('.wy-menu-vertical .caption[role=heading]'); + menuHeaders.forEach(it => { + let connectedMenu = it.nextElementSibling; + + // Enable toggling. + it.addEventListener('click', () => { + if (connectedMenu.classList.contains('active')) { + connectedMenu.classList.remove('active'); + it.classList.remove('active'); + } else { + connectedMenu.classList.add('active'); + it.classList.add('active'); + } + + // Hide other sections. + menuHeaders.forEach(ot => { + if (ot !== it && ot.classList.contains('active')) { + ot.nextElementSibling.classList.remove('active'); + ot.classList.remove('active'); + } + }); + + registerOnScrollEvent(mediaQuery); + }, true); + + // Set the default state, expand our current section. + if (connectedMenu.classList.contains('current')) { + connectedMenu.classList.add('active'); + it.classList.add('active'); + + hasCurrent = true; + } + }); + + // Unfold the first (general information) section on the home page. + if (!hasCurrent && menuHeaders.length > 0) { + menuHeaders[0].classList.add('active'); + menuHeaders[0].nextElementSibling.classList.add('active'); + + registerOnScrollEvent(mediaQuery); + } + + // Giscus + registerGiscus(); }); + +// Override the default implementation from doctools.js to avoid this behavior. +Documentation.highlightSearchWords = function() { + // Nope. +} diff --git a/_static/redirects.csv b/_static/redirects.csv new file mode 100644 index 00000000000..664ab8ce08b --- /dev/null +++ b/_static/redirects.csv @@ -0,0 +1,484 @@ +source,destination +/about/index.html,/index.html +/about/troubleshooting.html,/tutorials/troubleshooting.html +/classes/_classes.html,/classes/ +/community/tutorials/3d/mesh_generation_with_heightmap_and_shaders.html,/tutorials/3d/mesh_generation_with_heightmap_and_shaders.html +/community/tutorials/gdnative/gdnative-c-example.html,/tutorials/plugins/gdnative/gdnative-c-example.html +/community/tutorials/gdnative/index.html,/tutorials/plugins/gdnative/index.html +/community/tutorials/vr/index.html,/tutorials/vr/index.html +/community/tutorials/vr/vr_primer.html,/tutorials/vr/vr_primer.html +/content/3d/making_trees.html,/tutorials/content/making_trees.html +/development/compiling/compiling_for_android.html,/engine_details/development/compiling/compiling_for_android.html +/development/compiling/compiling_for_ios.html,/engine_details/development/compiling/compiling_for_ios.html +/development/compiling/compiling_for_linuxbsd.html,/engine_details/development/compiling/compiling_for_linuxbsd.html +/development/compiling/compiling_for_macos.html,/engine_details/development/compiling/compiling_for_macos.html +/development/compiling/compiling_for_uwp.html,/engine_details/development/compiling/compiling_for_uwp.html +/development/compiling/compiling_for_web.html,/engine_details/development/compiling/compiling_for_web.html +/development/compiling/compiling_for_windows.html,/engine_details/development/compiling/compiling_for_windows.html +/development/compiling/compiling_for_x11.html,/engine_details/development/compiling/compiling_for_linuxbsd.html +/development/compiling/compiling_with_mono.html,/engine_details/development/compiling/compiling_with_mono.html +/development/compiling/compiling_with_script_encryption_key.html,/engine_details/development/compiling/compiling_with_script_encryption_key.html +/development/compiling/cross-compiling_for_ios_on_linux.html,/engine_details/development/compiling/cross-compiling_for_ios_on_linux.html +/development/compiling/getting_source.html,/engine_details/development/compiling/getting_source.html +/development/compiling/index.html,/engine_details/development/compiling/index.html +/development/compiling/introduction_to_the_buildsystem.html,/engine_details/development/compiling/introduction_to_the_buildsystem.html +/development/compiling/optimizing_for_size.html,/engine_details/development/compiling/optimizing_for_size.html +/development/consoles/consoles.html,/tutorials/platform/consoles.html +/development/cpp/binding_to_external_libraries.html,/engine_details/architecture/binding_to_external_libraries.html +/development/cpp/common_engine_methods_and_macros.html,/engine_details/architecture/common_engine_methods_and_macros.html +/development/cpp/configuring_an_ide/android_studio.html,/engine_details/development/configuring_an_ide/android_studio.html +/development/cpp/configuring_an_ide/clion.html,/engine_details/development/configuring_an_ide/clion.html +/development/cpp/configuring_an_ide/code_blocks.html,/engine_details/development/configuring_an_ide/code_blocks.html +/development/cpp/configuring_an_ide/index.html,/engine_details/development/configuring_an_ide/index.html +/development/cpp/configuring_an_ide/kdevelop.html,/engine_details/development/configuring_an_ide/kdevelop.html +/development/cpp/configuring_an_ide/qt_creator.html,/engine_details/development/configuring_an_ide/qt_creator.html +/development/cpp/configuring_an_ide/visual_studio.html,/engine_details/development/configuring_an_ide/visual_studio.html +/development/cpp/configuring_an_ide/visual_studio_code.html,/engine_details/development/configuring_an_ide/visual_studio_code.html +/development/cpp/configuring_an_ide/xcode.html,/engine_details/development/configuring_an_ide/xcode.html +/development/cpp/core_types.html,/engine_details/architecture/core_types.html +/development/cpp/custom_audiostreams.html,/engine_details/architecture/custom_audiostreams.html +/development/cpp/custom_godot_servers.html,/engine_details/architecture/custom_godot_servers.html +/development/cpp/custom_modules_in_cpp.html,/engine_details/architecture/custom_modules_in_cpp.html +/development/cpp/custom_resource_format_loaders.html,/engine_details/architecture/custom_resource_format_loaders.html +/development/cpp/index.html,/engine_details/architecture/index.html +/development/cpp/inheritance_class_tree.html,/engine_details/architecture/inheritance_class_tree.html +/development/cpp/introduction_to_godot_development.html,https://contributing.godotengine.org/en/latest/engine/introduction.html +/development/cpp/macos_debug.html,/engine_details/development/debugging/macos_debug.html +/development/cpp/object_class.html,/engine_details/architecture/object_class.html +/development/cpp/unit_testing.html,/engine_details/architecture/unit_testing.html +/development/cpp/using_cpp_profilers.html,/engine_details/development/debugging/using_cpp_profilers.html +/development/cpp/variant_class.html,/engine_details/architecture/variant_class.html +/development/cpp/vulkan/index.html,/engine_details/development/debugging/vulkan/index.html +/development/cpp/vulkan/vulkan_validation_layers.html,/engine_details/development/debugging/vulkan/vulkan_validation_layers.html +/development/editor/creating_icons.html,/engine_details/editor/creating_icons.html +/development/editor/index.html,/engine_details/editor/index.html +/development/editor/introduction_to_editor_development.html,/engine_details/editor/introduction_to_editor_development.html +/development/file_formats/gdscript_grammar.html,/engine_details/development/file_formats/gdscript_grammar.html +/development/file_formats/index.html,/engine_details/development/file_formats/index.html +/development/file_formats/tscn.html,/engine_details/development/file_formats/tscn.html +/development/plugins/import_plugins.html,/tutorials/plugins/editor/import_plugins.html +/development/plugins/index.html,/tutorials/plugins/editor/index.html +/development/plugins/making_plugins.html,/tutorials/plugins/editor/making_plugins.html +/getting_started/editor/command_line_tutorial.html,/tutorials/editor/command_line_tutorial.html +/getting_started/editor/default_key_mapping.html,/tutorials/editor/default_key_mapping.html +/getting_started/editor/external_editor.html,/tutorials/editor/external_editor.html +/getting_started/editor/using_the_web_editor.html,/tutorials/editor/using_the_web_editor.html +/getting_started/scripting/c_sharp/c_sharp_basics.html,/tutorials/scripting/c_sharp/c_sharp_basics.html +/getting_started/scripting/c_sharp/c_sharp_differences.html,/tutorials/scripting/c_sharp/c_sharp_differences.html +/getting_started/scripting/c_sharp/c_sharp_features.html,/tutorials/scripting/c_sharp/c_sharp_features.html +/getting_started/scripting/c_sharp/c_sharp_style_guide.html,/tutorials/scripting/c_sharp/c_sharp_style_guide.html +/getting_started/scripting/c_sharp/index.html,/tutorials/scripting/c_sharp/index.html +/getting_started/scripting/creating_script_templates.html,/tutorials/scripting/creating_script_templates.html +/getting_started/scripting/cross_language_scripting.html,/tutorials/scripting/cross_language_scripting.html +/getting_started/scripting/gdscript/gdscript_advanced.html,/tutorials/scripting/gdscript/gdscript_advanced.html +/getting_started/scripting/gdscript/gdscript_basics.html,/tutorials/scripting/gdscript/gdscript_basics.html +/getting_started/scripting/gdscript/gdscript_exports.html,/tutorials/scripting/gdscript/gdscript_exports.html +/getting_started/scripting/gdscript/gdscript_format_string.html,/tutorials/scripting/gdscript/gdscript_format_string.html +/getting_started/scripting/gdscript/gdscript_styleguide.html,/tutorials/scripting/gdscript/gdscript_styleguide.html +/getting_started/scripting/gdscript/index.html,/tutorials/scripting/gdscript/index.html +/getting_started/scripting/gdscript/static_typing.html,/tutorials/scripting/gdscript/static_typing.html +/getting_started/scripting/gdscript/warning_system.html,/tutorials/scripting/gdscript/warning_system.html +/getting_started/step_by_step/exporting.html,/tutorials/export/exporting_basics.html +/getting_started/step_by_step/filesystem.html,/tutorials/scripting/filesystem.html +/getting_started/step_by_step/godot_design_philosophy.html,/getting_started/introduction/godot_design_philosophy.html +/getting_started/step_by_step/resources.html,/tutorials/scripting/resources.html +/getting_started/step_by_step/scene_tree.html,/tutorials/scripting/scene_tree.html +/getting_started/step_by_step/singletons_autoload.html,/tutorials/scripting/singletons_autoload.html +/getting_started/workflow/assets/escn_exporter/animation.html,/tutorials/assets_pipeline/escn_exporter/index.html +/getting_started/workflow/assets/escn_exporter/index.html,/tutorials/assets_pipeline/escn_exporter/index.html +/getting_started/workflow/assets/escn_exporter/lights.html,/tutorials/assets_pipeline/escn_exporter/index.html +/getting_started/workflow/assets/escn_exporter/material.html,/tutorials/assets_pipeline/escn_exporter/index.html +/getting_started/workflow/assets/escn_exporter/mesh.html,/tutorials/assets_pipeline/escn_exporter/index.html +/getting_started/workflow/assets/escn_exporter/physics.html,/tutorials/assets_pipeline/escn_exporter/index.html +/getting_started/workflow/assets/escn_exporter/skeleton.html,/tutorials/assets_pipeline/escn_exporter/index.html +/getting_started/workflow/assets/import_process.html,/tutorials/assets_pipeline/import_process.html +/getting_started/workflow/assets/importing_audio_samples.html,/tutorials/assets_pipeline/importing_audio_samples.html +/getting_started/workflow/assets/importing_images.html,/tutorials/assets_pipeline/importing_images.html +/getting_started/workflow/assets/importing_scenes.html,/tutorials/assets_pipeline/importing_scenes.html +/getting_started/workflow/assets/importing_translations.html,/tutorials/assets_pipeline/importing_translations.html +/getting_started/workflow/assets/index.html,/tutorials/assets_pipeline/index.html +/getting_started/workflow/best_practices/autoloads_versus_internal_nodes.html,/tutorials/best_practices/autoloads_versus_internal_nodes.html +/getting_started/workflow/best_practices/data_preferences.html,/tutorials/best_practices/data_preferences.html +/getting_started/workflow/best_practices/godot_interfaces.html,/tutorials/best_practices/godot_interfaces.html +/getting_started/workflow/best_practices/godot_notifications.html,/tutorials/best_practices/godot_notifications.html +/getting_started/workflow/best_practices/index.html,/tutorials/best_practices/index.html +/getting_started/workflow/best_practices/introduction_best_practices.html,/tutorials/best_practices/introduction_best_practices.html +/getting_started/workflow/best_practices/logic_preferences.html,/tutorials/best_practices/logic_preferences.html +/getting_started/workflow/best_practices/node_alternatives.html,/tutorials/best_practices/node_alternatives.html +/getting_started/workflow/best_practices/scene_organization.html,/tutorials/best_practices/scene_organization.html +/getting_started/workflow/best_practices/scenes_versus_scripts.html,/tutorials/best_practices/scenes_versus_scripts.html +/getting_started/workflow/best_practices/what_are_godot_classes.html,/tutorials/best_practices/what_are_godot_classes.html +/getting_started/workflow/export/android_custom_build.html,/tutorials/export/android_gradle_build.html +/getting_started/workflow/export/changing_application_icon_for_windows.html,/tutorials/export/changing_application_icon_for_windows.html +/getting_started/workflow/export/exporting_for_android.html,/tutorials/export/exporting_for_android.html +/getting_started/workflow/export/exporting_for_dedicated_servers.html,/tutorials/export/exporting_for_dedicated_servers.html +/getting_started/workflow/export/exporting_for_ios.html,/tutorials/export/exporting_for_ios.html +/getting_started/workflow/export/exporting_for_uwp.html,/tutorials/export/exporting_for_uwp.html +/getting_started/workflow/export/exporting_for_web.html,/tutorials/export/exporting_for_web.html +/getting_started/workflow/export/exporting_pcks.html,/tutorials/export/exporting_pcks.html +/getting_started/workflow/export/exporting_projects.html,/tutorials/export/exporting_projects.html +/getting_started/workflow/export/feature_tags.html,/tutorials/export/feature_tags.html +/getting_started/workflow/export/index.html,/tutorials/export/index.html +/getting_started/workflow/export/one-click_deploy.html,/tutorials/export/one-click_deploy.html +/getting_started/workflow/project_setup/project_organization.html,/tutorials/best_practices/project_organization.html +/getting_started/workflow/project_setup/version_control_systems.html,/tutorials/best_practices/version_control_systems.html +/learning/editor/2d_and_3d_keybindings.html,/getting_started/editor/2d_and_3d_keybindings.html +/learning/editor/command_line_tutorial.html,/getting_started/editor/command_line_tutorial.html +/learning/editor/index.html,/getting_started/editor/index.html +/learning/editor/unity_to_godot.html,/getting_started/editor/unity_to_godot.html +/learning/features/2d/,/tutorials/2d/_2d.html +/learning/features/2d/2d_transforms.html,/tutorials/2d/2d_transforms.html +/learning/features/2d/canvas_layers.html,/tutorials/2d/canvas_layers.html +/learning/features/2d/custom_drawing_in_2d.html,/tutorials/2d/custom_drawing_in_2d.html +/learning/features/2d/index.html,/tutorials/2d/index.html +/learning/features/2d/particle_systems_2d.html,/tutorials/2d/particle_systems_2d.html +/learning/features/2d/using_tilemaps.html,/tutorials/2d/using_tilemaps.html +/learning/features/3d/,/tutorials/3d/_3d.html +/learning/features/3d/3d_performance_and_limitations.html,/tutorials/3d/3d_performance_and_limitations.html +/learning/features/3d/baked_lightmaps.html,/tutorials/3d/baked_lightmaps.html +/learning/features/3d/environment_and_post_processing.html,/tutorials/3d/environment_and_post_processing.html +/learning/features/3d/fixed_materials.html,/tutorials/3d/fixed_materials.html +/learning/features/3d/gi_probes.html,/tutorials/3d/gi_probes.html +/learning/features/3d/high_dynamic_range.html,/tutorials/3d/high_dynamic_range.html +/learning/features/3d/importing_3d_meshes.html,/tutorials/3d/importing_3d_meshes.html +/learning/features/3d/importing_3d_scenes.html,/tutorials/3d/importing_3d_scenes.html +/learning/features/3d/index.html,/tutorials/3d/index.html +/learning/features/3d/introduction_to_3d.html,/tutorials/3d/introduction_to_3d.html +/learning/features/3d/lights_and_shadows.html,/tutorials/3d/lights_and_shadows.html +/learning/features/3d/materials.html,/tutorials/3d/materials.html +/learning/features/3d/reflection_probes.html,/tutorials/3d/reflection_probes.html +/learning/features/3d/spatial_material.html,/tutorials/3d/spatial_material.html +/learning/features/3d/using_gridmaps.html,/tutorials/3d/using_gridmaps.html +/learning/features/animation/cutout_animation.html,/tutorials/animation/cutout_animation.html +/learning/features/animation/index.html,/tutorials/animation/index.html +/learning/features/animation/introduction_2d.html,/tutorials/animation/introduction_2d.html +/learning/features/assetlib/index.html,/tutorials/assetlib/index.html +/learning/features/assetlib/uploading_to_assetlib.html,/tutorials/assetlib/uploading_to_assetlib.html +/learning/features/assetlib/using_assetlib.html,/tutorials/assetlib/using_assetlib.html +/learning/features/assetlib/what_is_assetlib.html,/tutorials/assetlib/what_is_assetlib.html +/learning/features/audio/audio_buses.html,/tutorials/audio/audio_buses.html +/learning/features/audio/audio_streams.html,/tutorials/audio/audio_streams.html +/learning/features/audio/index.html,/tutorials/audio/index.html +/learning/features/gui/,/tutorials/2d/_2d_gui.html +/learning/features/gui/bbcode_in_richtextlabel.html,/tutorials/gui/bbcode_in_richtextlabel.html +/learning/features/gui/custom_gui_controls.html,/tutorials/gui/custom_gui_controls.html +/learning/features/gui/gui_skinning.html,/tutorials/gui/gui_skinning.html +/learning/features/gui/index.html,/tutorials/gui/index.html +/learning/features/gui/size_and_anchors.html,/tutorials/gui/size_and_anchors.html +/learning/features/inputs/index.html,/tutorials/inputs/index.html +/learning/features/inputs/inputevent.html,/tutorials/inputs/inputevent.html +/learning/features/inputs/mouse_and_input_coordinates.html,/tutorials/inputs/mouse_and_input_coordinates.html +/learning/features/lighting/lighting.html,/tutorials/3d/lighting.html +/learning/features/lighting/shadow_mapping.html,/tutorials/3d/shadow_mapping.html +/learning/features/math/,/tutorials/_math.html +/learning/features/math/index.html,/tutorials/math/index.html +/learning/features/math/matrices_and_transforms.html,/tutorials/math/matrices_and_transforms.html +/learning/features/math/vector_math.html,/tutorials/math/vector_math.html +/learning/features/math/vectors_advanced.html,/tutorials/math/vectors_advanced.html +/learning/features/misc/,/tutorials/_misc_tutorials.html +/learning/features/misc/background_loading.html,/tutorials/misc/background_loading.html +/learning/features/misc/binary_serialization_api.html,/tutorials/misc/binary_serialization_api.html +/learning/features/misc/data_paths.html,/tutorials/misc/data_paths.html +/learning/features/misc/encrypting_save_games.html,/tutorials/misc/encrypting_save_games.html +/learning/features/misc/handling_quit_requests.html,/tutorials/misc/handling_quit_requests.html +/learning/features/misc/index.html,/tutorials/misc/index.html +/learning/features/misc/internationalizing_games.html,/tutorials/misc/internationalizing_games.html +/learning/features/misc/locales.html,/tutorials/misc/locales.html +/learning/features/misc/pausing_games.html,/tutorials/misc/pausing_games.html +/learning/features/misc/saving_games.html,/tutorials/misc/saving_games.html +/learning/features/networking/,/tutorials/_networking.html +/learning/features/networking/high_level_multiplayer.html,/tutorials/networking/high_level_multiplayer.html +/learning/features/networking/http_client_class.html,/tutorials/networking/http_client_class.html +/learning/features/networking/index.html,/tutorials/networking/index.html +/learning/features/networking/ssl_certificates.html,/tutorials/networking/ssl_certificates.html +/learning/features/physics/,/tutorials/2d/_2d_physics.html +/learning/features/physics/index.html,/tutorials/physics/index.html +/learning/features/physics/kinematic_character_2d.html,/tutorials/physics/kinematic_character_2d.html +/learning/features/physics/physics_introduction.html,/tutorials/physics/physics_introduction.html +/learning/features/physics/ray-casting.html,/tutorials/physics/ray-casting.html +/learning/features/platform/android_in_app_purchases.html,/tutorials/platform/android_in_app_purchases.html +/learning/features/platform/index.html,/tutorials/platform/index.html +/learning/features/platform/services_for_ios.html,/tutorials/platform/services_for_ios.html +/learning/features/shading/,/tutorials/_shaders.html +/learning/features/shading/index.html,/tutorials/shading/index.html +/learning/features/shading/screen-reading_shaders.html,/tutorials/shading/screen-reading_shaders.html +/learning/features/shading/shader_materials.html,/tutorials/shading/shader_materials.html +/learning/features/shading/shading_language.html,/tutorials/shading/shading_language.html +/learning/features/viewports/index.html,/tutorials/viewports/index.html +/learning/features/viewports/multiple_resolutions.html,/tutorials/viewports/multiple_resolutions.html +/learning/features/viewports/viewports.html,/tutorials/viewports/viewports.html +/learning/scripting/c_sharp/c_sharp_basics.html,/getting_started/scripting/c_sharp/c_sharp_basics.html +/learning/scripting/c_sharp/c_sharp_differences.html,/getting_started/scripting/c_sharp/c_sharp_differences.html +/learning/scripting/c_sharp/c_sharp_features.html,/getting_started/scripting/c_sharp/c_sharp_features.html +/learning/scripting/c_sharp/index.html,/getting_started/scripting/c_sharp/index.html +/learning/scripting/gdscript/gdscript_advanced.html,/getting_started/scripting/gdscript/gdscript_advanced.html +/learning/scripting/gdscript/gdscript_basics.html,/getting_started/scripting/gdscript/gdscript_basics.html +/learning/scripting/gdscript/gdscript_format_string.html,/getting_started/scripting/gdscript/gdscript_format_string.html +/learning/scripting/gdscript/gdscript_styleguide.html,/getting_started/scripting/gdscript/gdscript_styleguide.html +/learning/scripting/gdscript/index.html,/getting_started/scripting/gdscript/index.html +/learning/scripting/index.html,/getting_started/scripting/index.html +/learning/scripting/visual_script/getting_started.html,/getting_started/scripting/visual_script/getting_started.html +/learning/scripting/visual_script/index.html,/getting_started/scripting/visual_script/index.html +/learning/scripting/visual_script/nodes_purposes.html,/getting_started/scripting/visual_script/nodes_purposes.html +/learning/scripting/visual_script/what_is_visual_scripting.html,/getting_started/scripting/visual_script/what_is_visual_scripting.html +/learning/step_by_step/,/tutorials/step_by_step/_step_by_step.html +/learning/step_by_step/animations.html,/getting_started/step_by_step/animations.html +/learning/step_by_step/filesystem.html,/getting_started/step_by_step/filesystem.html +/learning/step_by_step/godot_design_philosophy.html,/getting_started/step_by_step/godot_design_philosophy.html +/learning/step_by_step/gui_tutorial.html,/tutorials/step_by_step/gui_tutorial.html +/learning/step_by_step/index.html,/getting_started/step_by_step/index.html +/learning/step_by_step/instancing.html,/getting_started/step_by_step/instancing.html +/learning/step_by_step/instancing_continued.html,/getting_started/step_by_step/instancing_continued.html +/learning/step_by_step/intro_to_the_editor_interface.html,/getting_started/step_by_step/intro_to_the_editor_interface.html +/learning/step_by_step/resources.html,/getting_started/step_by_step/resources.html +/learning/step_by_step/scene_tree.html,/getting_started/step_by_step/scene_tree.html +/learning/step_by_step/scenes_and_nodes.html,/getting_started/step_by_step/scenes_and_nodes.html +/learning/step_by_step/scripting.html,/getting_started/step_by_step/scripting.html +/learning/step_by_step/scripting_continued.html,/getting_started/step_by_step/scripting_continued.html +/learning/step_by_step/simple_2d_game.html,/tutorials/step_by_step/simple_2d_game.html +/learning/step_by_step/singletons_autoload.html,/getting_started/step_by_step/singletons_autoload.html +/learning/step_by_step/splash_screen.html,/getting_started/step_by_step/splash_screen.html +/learning/step_by_step/ui_code_a_life_bar.html,/getting_started/step_by_step/ui_code_a_life_bar.html +/learning/step_by_step/ui_game_user_interface.html,/getting_started/step_by_step/ui_game_user_interface.html +/learning/step_by_step/ui_introduction_to_the_ui_system.html,/getting_started/step_by_step/ui_introduction_to_the_ui_system.html +/learning/step_by_step/ui_main_menu.html,/getting_started/step_by_step/ui_main_menu.html +/learning/step_by_step/your_first_game.html,/getting_started/step_by_step/your_first_game.html +/learning/workflow/,/tutorials/asset_pipeline/_asset_pipeline.html +/learning/workflow/assets/,/tutorials/asset_pipeline/_import.html +/learning/workflow/assets/exporting_images.html,/tutorials/asset_pipeline/exporting_images.html +/learning/workflow/assets/import_process.html,/getting_started/workflow/assets/import_process.html +/learning/workflow/assets/importing_audio_samples.html,/getting_started/workflow/assets/importing_audio_samples.html +/learning/workflow/assets/importing_fonts.html,/tutorials/asset_pipeline/importing_fonts.html +/learning/workflow/assets/importing_images.html,/getting_started/workflow/assets/importing_images.html +/learning/workflow/assets/importing_scenes.html,/getting_started/workflow/assets/importing_scenes.html +/learning/workflow/assets/importing_textures.html,/tutorials/asset_pipeline/importing_textures.html +/learning/workflow/assets/importing_translations.html,/getting_started/workflow/assets/importing_translations.html +/learning/workflow/assets/index.html,/getting_started/workflow/assets/index.html +/learning/workflow/assets/managing_image_files.html,/tutorials/asset_pipeline/managing_image_files.html +/learning/workflow/export/,/tutorials/asset_pipeline/_export.html +/learning/workflow/export/customizing_html5_shell.html,/getting_started/workflow/export/customizing_html5_shell.html +/learning/workflow/export/exporting_for_android.html,/getting_started/workflow/export/exporting_for_android.html +/learning/workflow/export/exporting_for_ios.html,/getting_started/workflow/export/exporting_for_ios.html +/learning/workflow/export/exporting_for_pc.html,/getting_started/workflow/export/exporting_for_pc.html +/learning/workflow/export/exporting_for_uwp.html,/getting_started/workflow/export/exporting_for_uwp.html +/learning/workflow/export/exporting_for_web.html,/getting_started/workflow/export/exporting_for_web.html +/learning/workflow/export/exporting_projects.html,/getting_started/workflow/export/exporting_projects.html +/learning/workflow/export/feature_tags.html,/getting_started/workflow/export/feature_tags.html +/learning/workflow/export/index.html,/getting_started/workflow/export/index.html +/learning/workflow/export/one-click_deploy.html,/getting_started/workflow/export/one-click_deploy.html +/learning/workflow/index.html,/getting_started/workflow/index.html +/learning/workflow/project_setup/index.html,/getting_started/workflow/project_setup/index.html +/learning/workflow/project_setup/project_organization.html,/getting_started/workflow/project_setup/project_organization.html +/reference/2d_and_3d_keybindings.html,/learning/editor/2d_and_3d_keybindings.html +/reference/_compiling.html,/development/compiling/ +/reference/_developing.html,/development/cpp/ +/reference/android_in_app_purchases.html,/learning/features/platform/android_in_app_purchases.html +/reference/batch_building_templates.html,/development/compiling/batch_building_templates.html +/reference/bbcode_in_richtextlabel.html,/learning/features/gui/bbcode_in_richtextlabel.html +/reference/binary_serialization_api.html,/learning/features/misc/binary_serialization_api.html +/reference/command_line_tutorial.html,/learning/editor/command_line_tutorial.html +/reference/compiling_for_android.html,/development/compiling/compiling_for_android.html +/reference/compiling_for_ios.html,/development/compiling/compiling_for_ios.html +/reference/compiling_for_osx.html,/development/compiling/compiling_for_osx.html +/reference/compiling_for_uwp.html,/development/compiling/compiling_for_uwp.html +/reference/compiling_for_web.html,/development/compiling/compiling_for_web.html +/reference/compiling_for_windows.html,/development/compiling/compiling_for_windows.html +/reference/compiling_for_x11.html,/development/compiling/compiling_for_x11.html +/reference/configuring_an_ide.html,/development/cpp/configuring_an_ide.html +/reference/core_types.html,/development/cpp/core_types.html +/reference/creating_android_modules.html,/development/cpp/creating_android_modules.html +/reference/cross-compiling_for_ios_on_linux.html,/development/compiling/cross-compiling_for_ios_on_linux.html +/reference/custom_modules_in_c++.html,/development/cpp/custom_modules_in_cpp.html +/reference/faq.html,/about/faq.html +/reference/gdscript.html,/learning/scripting/gdscript/gdscript_basics.html +/reference/gdscript_more_efficiently.html,/learning/scripting/gdscript/gdscript_advanced.html +/reference/gdscript_printf.html,/learning/scripting/gdscript/gdscript_format_string.html +/reference/inheritance_class_tree.html,/development/cpp/inheritance_class_tree.html +/reference/introduction_to_godot_development.html,https://contributing.godotengine.org/en/latest/engine/introduction.html +/reference/introduction_to_the_buildsystem.html,/development/compiling/introduction_to_the_buildsystem.html +/reference/locales.html,/learning/features/misc/locales.html +/reference/object_class.html,/development/cpp/object_class.html +/reference/packaging_godot.html,/development/compiling/packaging_godot.html +/reference/services_for_ios.html,/learning/features/platform/services_for_ios.html +/reference/shading_language.html,/learning/features/shading/shading_language.html +/reference/unity_to_godot.html,/learning/editor/unity_to_godot.html +/reference/variant_class.html,/development/cpp/variant_class.html +/tutorials/3d/faking_global_illumination.html,/tutorials/3d/global_illumination/faking_global_illumination.html +/tutorials/3d/introduction_to_global_illumination.html,/tutorials/3d/global_illumination/introduction_to_global_illumination.html +/tutorials/3d/inverse_kinematics.html,/community/tutorials/3d/inverse_kinematics.html +/tutorials/3d/procedural_geometry/immediategeometry.html,/tutorials/3d/procedural_geometry/immediatemesh.html +/tutorials/3d/reflection_probes.html,/tutorials/3d/global_illumination/reflection_probes.html +/tutorials/3d/sdfgi.html,/tutorials/3d/global_illumination/using_sdfgi.html +/tutorials/3d/spatial_material.html,/tutorials/3d/standard_material_3d.html +/tutorials/3d/using_lightmap_gi.html,/tutorials/3d/global_illumination/using_lightmap_gi.html +/tutorials/3d/using_voxel_gi.html,/tutorials/3d/global_illumination/using_voxel_gi.html +/tutorials/3d/vertex_animation/animating_thousands_of_fish.html,/tutorials/performance/vertex_animation/animating_thousands_of_fish.html +/tutorials/3d/vertex_animation/controlling_thousands_of_fish.html,/tutorials/performance/vertex_animation/controlling_thousands_of_fish.html +/tutorials/3d/vertex_animation/index.html,/tutorials/performance/vertex_animation/index.html +/tutorials/3d/working_with_3d_skeletons.html,/community/tutorials/3d/working_with_3d_skeletons.html +/tutorials/_plugins.html,/development/plugins/ +/tutorials/assetlib/index.html,/community/asset_library/index.html +/tutorials/assetlib/uploading_to_assetlib.html,/community/asset_library/uploading_to_assetlib.html +/tutorials/assetlib/using_assetlib.html,/community/asset_library/using_assetlib.html +/tutorials/assetlib/what_is_assetlib.html,/community/asset_library/what_is_assetlib.html +/tutorials/assets_pipeline/importing_scenes.html,/tutorials/assets_pipeline/importing_3d_scenes/index.html +/tutorials/content/making_trees.html,/tutorials/shaders/making_trees.html +/tutorials/content/procedural_geometry/arraymesh.html,/tutorials/3d/procedural_geometry/arraymesh.html +/tutorials/content/procedural_geometry/immediategeometry.html,/tutorials/3d/procedural_geometry/immediategeometry.html +/tutorials/content/procedural_geometry/index.html,/tutorials/3d/procedural_geometry/index.html +/tutorials/content/procedural_geometry/meshdatatool.html,/tutorials/3d/procedural_geometry/meshdatatool.html +/tutorials/content/procedural_geometry/surfacetool.html,/tutorials/3d/procedural_geometry/surfacetool.html +/tutorials/debug/debugger_panel.html,/tutorials/scripting/debug/debugger_panel.html +/tutorials/debug/index.html,/tutorials/scripting/debug/index.html +/tutorials/debug/overview_of_debugging_tools.html,/tutorials/scripting/debug/overview_of_debugging_tools.html +/tutorials/editor/upgrading_to_godot_4.html,/tutorials/migrating/upgrading_to_godot_4.html +/tutorials/gui/bbcode_in_richtextlabel.html,/tutorials/ui/bbcode_in_richtextlabel.html +/tutorials/gui/control_node_gallery.html,/tutorials/ui/control_node_gallery.html +/tutorials/gui/custom_gui_controls.html,/tutorials/ui/custom_gui_controls.html +/tutorials/gui/gui_containers.html,/tutorials/ui/gui_containers.html +/tutorials/gui/size_and_anchors.html,/tutorials/ui/size_and_anchors.html +/tutorials/legal/complying_with_licenses.html,/about/complying_with_licenses.html +/tutorials/making_plugins.html,/development/plugins/making_plugins.html +/tutorials/mesh_generation_with_heightmap_and_shaders.html,/community/tutorials/3d/mesh_generation_with_heightmap_and_shaders.html +/tutorials/misc/background_loading.html,/tutorials/io/background_loading.html +/tutorials/misc/binary_serialization_api.html,/tutorials/io/binary_serialization_api.html +/tutorials/misc/change_scenes_manually.html,/tutorials/scripting/change_scenes_manually.html +/tutorials/misc/data_paths.html,/tutorials/io/data_paths.html +/tutorials/misc/encrypting_save_games.html,/tutorials/io/encrypting_save_games.html +/tutorials/misc/gles2_gles3_differences.html,/tutorials/rendering/gles2_gles3_differences.html +/tutorials/misc/handling_quit_requests.html,/tutorials/inputs/handling_quit_requests.html +/tutorials/misc/instancing_with_signals.html,/tutorials/scripting/instancing_with_signals.html +/tutorials/misc/internationalizing_games.html,/tutorials/i18n/internationalizing_games.html +/tutorials/misc/jitter_stutter.html,/tutorials/rendering/jitter_stutter.html +/tutorials/misc/locales.html,/tutorials/i18n/locales.html +/tutorials/misc/pausing_games.html,/tutorials/scripting/pausing_games.html +/tutorials/misc/running_code_in_the_editor.html,/tutorials/plugins/running_code_in_the_editor.html +/tutorials/misc/saving_games.html,/tutorials/io/saving_games.html +/tutorials/navigation/navigation_using_navigationobstacles.html#static-obstacles,/tutorials/navigation/navigation_using_navigationobstacles.html#static-avoidance-obstacles +/tutorials/navigation/navigation_using_navigationobstacles.html#static-obstacles,/tutorials/navigation/navigation_using_navigationobstacles.html#dynamic-avoidance-obstacles +/tutorials/optimization/batching.html,/tutorials/performance/batching.html +/tutorials/optimization/cpu_optimization.html,/tutorials/performance/cpu_optimization.html +/tutorials/optimization/general_optimization.html,/tutorials/performance/general_optimization.html +/tutorials/optimization/gpu_optimization.html,/tutorials/performance/gpu_optimization.html +/tutorials/optimization/index.html,/tutorials/performance/index.html +/tutorials/optimization/optimizing_3d_performance.html,/tutorials/performance/optimizing_3d_performance.html +/tutorials/optimization/using_multimesh.html,/tutorials/performance/using_multimesh.html +/tutorials/optimization/using_servers.html,/tutorials/performance/using_servers.html +/tutorials/physics/using_kinematic_body_2d.html,/tutorials/physics/using_character_body_2d.html +/tutorials/platform/android_in_app_purchases.html,/tutorials/platform/android/android_in_app_purchases.html +/tutorials/platform/customizing_html5_shell.html,/tutorials/platform/web/customizing_html5_shell.html +/tutorials/platform/html5_shell_classref.html,/tutorials/platform/web/html5_shell_classref.html +/tutorials/platform/platform_html5.html,/tutorials/platform/web/index.html +/tutorials/plugins/android/android_plugin.html,/tutorials/platform/android/android_plugin.html +/tutorials/plugins/android/index.html,/tutorials/platform/android/index.html +/tutorials/plugins/editor/spatial_gizmos.html,/tutorials/plugins/editor/3d_gizmos.html +/tutorials/plugins/gdnative/gdnative-c-example.html,/tutorials/scripting/gdnative/gdnative_c_example.html +/tutorials/plugins/gdnative/gdnative-cpp-example.html,/tutorials/scripting/gdnative/gdnative_cpp_example.html +/tutorials/plugins/gdnative/index.html,/tutorials/scripting/gdnative/index.html +/tutorials/plugins/gdextension/gdextension_cpp_example.html,/tutorials/plugins/cpp/gdextension_cpp_example.html +/tutorials/scripting/gdnative/gdnative_c_example.html,/tutorials/plugins/cpp/gdextension_cpp_example.html +/tutorials/scripting/gdnative/gdnative_cpp_example.html,/tutorials/plugins/cpp/gdextension_cpp_example.html +/tutorials/scripting/gdnative/index.html,/tutorials/scripting/gdextension/index.html +/tutorials/scripting/gdnative/what_is_gdnative.html,/tutorials/scripting/gdnative/what_is_gdextension.html +/tutorials/shading/advanced_postprocessing.html,/tutorials/shaders/advanced_postprocessing.html +/tutorials/shading/godot_shader_language_style_guide.html,/tutorials/shaders/shaders_style_guide.html +/tutorials/shading/index.html,/tutorials/shaders/index.html +/tutorials/shading/migrating_to_godot_shader_language.html,/tutorials/shaders/converting_glsl_to_godot_shaders.html +/tutorials/shading/screen-reading_shaders.html,/tutorials/shaders/screen-reading_shaders.html +/tutorials/shading/shader_materials.html,/tutorials/shaders/shader_materials.html +/tutorials/shading/shading_reference/canvas_item_shader.html,/tutorials/shaders/shader_reference/canvas_item_shader.html +/tutorials/shading/shading_reference/index.html,/tutorials/shaders/shader_reference/index.html +/tutorials/shading/shading_reference/particle_shader.html,/tutorials/shaders/shader_reference/particle_shader.html +/tutorials/shading/shading_reference/shading_language.html,/tutorials/shaders/shader_reference/shading_language.html +/tutorials/shading/shading_reference/spatial_shader.html,/tutorials/shaders/shader_reference/spatial_shader.html +/tutorials/shading/visual_shaders.html,/tutorials/shaders/visual_shaders.html +/tutorials/shading/your_first_shader/index.html,/tutorials/shaders/your_first_shader/index.html +/tutorials/shading/your_first_shader/your_second_spatial_shader.html,/tutorials/shaders/your_first_shader/your_second_3d_shader.html +/tutorials/threads/thread_safe_apis.html,/tutorials/performance/threads/thread_safe_apis.html +/tutorials/threads/using_multiple_threads.html,/tutorials/performance/threads/using_multiple_threads.html +/tutorials/viewports/custom_postprocessing.html,/tutorials/shaders/custom_postprocessing.html +/tutorials/viewports/multiple_resolutions.html,/tutorials/rendering/multiple_resolutions.html +/tutorials/viewports/using_viewport_as_texture.html,/tutorials/shaders/using_viewport_as_texture.html +/tutorials/viewports/viewports.html,/tutorials/rendering/viewports.html +/tutorials/export/exporting_for_uwp.html,/about/faq.html#which-platforms-are-supported-by-godot +/tutorials/xr/openxr_passthrough.html,/tutorials/xr/ar_passthrough.html +/contributing/development/compiling/compiling_for_uwp.html,/about/faq.html#which-platforms-are-supported-by-godot +/contributing/_contributing.html,https://contributing.godotengine.org +/contributing/development/compiling/compiling_with_mono.html,/engine_details/development/compiling/compiling_with_dotnet.html +/contributing/architecture/introduction_to_godot_development.html,/engine_details/architecture/index.html +/contributing/development/best_practices_for_engine_contributors.html,https://contributing.godotengine.org/en/latest/engine/guidelines/best_practices.html +/contributing/development/code_style_guidelines.html,https://contributing.godotengine.org/en/latest/engine/guidelines/code_style.html +/contributing/development/cpp_usage_guidelines.html,https://contributing.godotengine.org/en/latest/engine/guidelines/cpp_usage_guidelines.html +/contributing/development/editor/editor_style_guide.html,https://contributing.godotengine.org/en/latest/engine/guidelines/editor_style_guide.html +/contributing/development/editor/index.html,/engine_details/editor/index.html +/contributing/development/index.html,/engine_details/development/index.html +/contributing/documentation/building_the_manual.html,https://contributing.godotengine.org/en/latest/documentation/manual/building_the_manual.html +/contributing/documentation/content_guidelines.html,https://contributing.godotengine.org/en/latest/documentation/guidelines/content_guidelines.html +/contributing/documentation/contributing_to_the_documentation.html,https://contributing.godotengine.org/en/latest/documentation/manual/index.html +/contributing/documentation/docs_contribution_checklist.html,https://contributing.godotengine.org/en/latest/documentation/guidelines/docs_contribution_checklist.html +/contributing/documentation/docs_image_guidelines.html,https://contributing.godotengine.org/en/latest/documentation/guidelines/docs_image_guidelines.html +/contributing/documentation/docs_writing_guidelines.html,https://contributing.godotengine.org/en/latest/documentation/guidelines/docs_writing_guidelines.html +/contributing/documentation/editor_and_docs_localization.html,https://contributing.godotengine.org/en/latest/documentation/translation/index.html +/contributing/documentation/index.html,https://contributing.godotengine.org/en/latest/documentation/overview.html +/contributing/documentation/updating_the_class_reference.html,https://contributing.godotengine.org/en/latest/documentation/class_reference.html +/contributing/how_to_contribute.html,https://contributing.godotengine.org/en/latest/organization/how_to_contribute.html +/contributing/workflow/bisecting_regressions.html,https://contributing.godotengine.org/en/latest/reporting_issues/bisecting.html +/contributing/workflow/bug_triage_guidelines.html,https://contributing.godotengine.org/en/latest/triage/guidelines.html +/contributing/workflow/first_steps.html,https://contributing.godotengine.org/en/latest/engine/introduction.html +/contributing/workflow/index.html,https://contributing.godotengine.org/en/latest/engine/introduction.html +/contributing/workflow/pr_review_guidelines.html,https://contributing.godotengine.org/en/latest/organization/pull_requests/review_guidelines.html +/contributing/workflow/pr_workflow.html,https://contributing.godotengine.org/en/latest/organization/pull_requests/creating_pull_requests.html +/contributing/workflow/testing_pull_requests.html,https://contributing.godotengine.org/en/latest/organization/pull_requests/testing.html +/contributing/development/core_and_modules/2d_coordinate_systems.html,/engine_details/architecture/2d_coordinate_systems.html +/contributing/development/core_and_modules/common_engine_methods_and_macros.html,/engine_details/architecture/common_engine_methods_and_macros.html +/contributing/development/core_and_modules/core_types.html,/engine_details/architecture/core_types.html +/contributing/development/core_and_modules/custom_audiostreams.html,/engine_details/architecture/custom_audiostreams.html +/contributing/development/core_and_modules/custom_godot_servers.html,/engine_details/architecture/custom_godot_servers.html +/contributing/development/core_and_modules/custom_modules_in_cpp.html,/engine_details/architecture/custom_modules_in_cpp.html +/contributing/development/core_and_modules/custom_platform_ports.html,/engine_details/architecture/custom_platform_ports.html +/contributing/development/core_and_modules/custom_resource_format_loaders.html,/engine_details/architecture/custom_resource_format_loaders.html +/contributing/development/core_and_modules/godot_architecture_diagram.html,/engine_details/architecture/godot_architecture_diagram.html +/contributing/development/core_and_modules/index.html,/engine_details/architecture/index.html +/contributing/development/core_and_modules/inheritance_class_tree.html,/engine_details/architecture/inheritance_class_tree.html +/contributing/development/core_and_modules/internal_rendering_architecture.html,/engine_details/architecture/internal_rendering_architecture.html +/contributing/development/core_and_modules/object_class.html,/engine_details/architecture/object_class.html +/contributing/development/core_and_modules/scripting_development.html,/engine_details/architecture/scripting_development.html +/contributing/development/core_and_modules/unit_testing.html,/engine_details/architecture/unit_testing.html +/contributing/development/core_and_modules/variant_class.html,/engine_details/architecture/variant_class.html +/contributing/documentation/class_reference_primer.html,engine_details/class_reference/index.html +/contributing/development/compiling/compiling_for_android.html,/engine_details/development/compiling/compiling_for_android.html, +/contributing/development/compiling/compiling_for_ios.html,/engine_details/development/compiling/compiling_for_ios.html +/contributing/development/compiling/compiling_for_linuxbsd.html,/engine_details/development/compiling/compiling_for_linuxbsd.html +/contributing/development/compiling/compiling_for_macos.html,/engine_details/development/compiling/compiling_for_macos.html +/contributing/development/compiling/compiling_for_visionos.html,/engine_details/development/compiling/compiling_for_visionos.html +/contributing/development/compiling/compiling_for_web.html,/engine_details/development/compiling/compiling_for_web.html +/contributing/development/compiling/compiling_for_windows.html,/engine_details/development/compiling/compiling_for_windows.html +/contributing/development/compiling/compiling_with_dotnet.html,/engine_details/development/compiling/compiling_with_dotnet.html +/contributing/development/compiling/compiling_with_script_encryption_key.html,/engine_details/development/compiling/compiling_with_script_encryption_key.html +/contributing/development/compiling/cross-compiling_for_ios_on_linux.html,/engine_details/development/compiling/cross-compiling_for_ios_on_linux.html +/contributing/development/compiling/getting_source.html,/engine_details/development/compiling/getting_source.html +/contributing/development/compiling/index.html,/engine_details/development/compiling/index.html +/contributing/development/compiling/introduction_to_the_buildsystem.html,/engine_details/development/compiling/introduction_to_the_buildsystem.html +/contributing/development/compiling/optimizing_for_size.html,/engine_details/development/compiling/optimizing_for_size.html +/contributing/development/configuring_an_ide/android_studio.html,/engine_details/development/configuring_an_ide/android_studio.html +/contributing/development/configuring_an_ide/clion.html,/engine_details/development/configuring_an_ide/clion.html +/contributing/development/configuring_an_ide/code_blocks.html,/engine_details/development/configuring_an_ide/code_blocks.html +/contributing/development/configuring_an_ide/index.html,/engine_details/development/configuring_an_ide/index.html +/contributing/development/configuring_an_ide/kdevelop.html,/engine_details/development/configuring_an_ide/kdevelop.html +/contributing/development/configuring_an_ide/qt_creator.html,/engine_details/development/configuring_an_ide/qt_creator.html +/contributing/development/configuring_an_ide/rider.html,/engine_details/development/configuring_an_ide/rider.html +/contributing/development/configuring_an_ide/rider.html,/engine_details/development/configuring_an_ide/rider.html +/contributing/development/configuring_an_ide/visual_studio.html,/engine_details/development/configuring_an_ide/visual_studio.html +/contributing/development/configuring_an_ide/visual_studio_code.html,/engine_details/development/configuring_an_ide/visual_studio_code.html +/contributing/development/configuring_an_ide/xcode.html,/engine_details/development/configuring_an_ide/xcode.html +/contributing/development/debugging/index.html,/engine_details/development/debugging/index.html +/contributing/development/debugging/macos_debug.html,/engine_details/development/debugging/macos_debug.html +/contributing/development/debugging/using_cpp_profilers.html,/engine_details/development/debugging/using_cpp_profilers.html +/contributing/development/debugging/using_sanitizers.html,/engine_details/development/debugging/using_sanitizers.html +/contributing/development/debugging/vulkan/index.html,/engine_details/development/debugging/vulkan/index.html +/contributing/development/debugging/vulkan/vulkan_validation_layers.html,/engine_details/development/debugging/vulkan/vulkan_validation_layers.html +/contributing/development/handling_compatibility_breakages.html,/engine_details/development/handling_compatibility_breakages.html +/contributing/development/editor/creating_icons.html,/engine_details/editor/creating_icons.html +/contributing/development/editor/index.html,/engine_details/editor/index.html +/contributing/development/editor/introduction_to_editor_development.html,/engine_details/editor/introduction_to_editor_development.html +/contributing/development/file_formats/gdscript_grammar.html,/engine_details/file_formats/gdscript_grammar.html diff --git a/_styleguides/de.md b/_styleguides/de.md new file mode 100644 index 00000000000..a75364c660a --- /dev/null +++ b/_styleguides/de.md @@ -0,0 +1,555 @@ +# Stilregeln für die Übersetzung von Godot ins Deutsche + +## Einleitung + +Dieses Dokument soll dabei helfen, die deutsche Übersetzung von Godot, sowie +der Godot-Dokumentation, stilistisch zu vereinheitlichen. Dabei sollen +Lesbarkeit, Klarheit und Benutzbarkeit besonders im Vordergrund stehen. + +Für die Übersetzung selbst ist das Tool +[Weblate](https://hosted.weblate.org/projects/godot-engine/) im Einsatz, das in der +[offiziellen Dokumentation](https://contributing.godotengine.org/en/latest/documentation/translation/index.html) näher +erläutert wird. Die Bedienung von Weblate ist nicht Bestandteil dieses +Dokuments. + +Weblate verfügt über ein Glossar, in dem häufig verwendete Begriffe gelistet +werden, damit sie einheitlich übersetzt werden können. In diesem Dokument +wird daher darauf verzichtet, die Übersetzung einzelner Begriffe zu +klären. Sollte es bei der Übersetzung eines Begriffs Uneinigkeit geben, +so sollte dies zunächst im [Chatraum für die deutsche +Godot-Übersetzung](https://chat.godotengine.org/channel/translation-de) diskutiert und dann ins Glossar eingetragen werden. + +## Technische Hilfsmittel + +### Automatische Übersetzungen und Workflow + +Die Erfahrung zeigt, dass eine Übersetzung von längeren Texten, z.B. aus der +Anleitung oder der Klassenreferenz oft zu schnelleren und besseren Ergebnissen +führt, wenn man den Originaltext von einer KI vorübersetzen lässt. + +Ein sehr zu empfehlender Übersetzungsdienst ist hier die Website +https://www.deepl.com, die hervorragende Erstübersetzungen zur Verfügung stellt +und selbst Formatierungszeichen, wie Fettdruck oder Links in vielen Fällen +korrekt in die Übersetzung übernimmt. + +Ein weiterer Vorteil dieser Art zu übersetzen ist, dass ein und derselbe Text +mit hoher Wahrscheinlichkeit strukturell wiederholt gleich übersetzt wird, was +sehr hilfreich sein kann, wenn sich die Originaltexte leicht ändern und dann +die vorgenerierte Übersetzung immer noch dicht an der vorigen Übersetzung ist. + +Hier ist ein empfohlener Workflow für die Übersetzung eines Textblocks: + +* Originaltext kopieren +* In DeepL übersetzen lassen +* In Übersetzungsfeld einfügen +* Text auf Abweichungen zum Glossar prüfen und ggf. korrigieren +* Eigene Änderungen vornehmen, wo sinnvoll + +Es ist zudem ratsam, Korrekturen direkt auf der rechten Seite von DeepL vorzunehmen, +da das Tool bei wiederholten Korrekturen dazulernen kann. Begriffe, die +hartnäckig falsch übersetzt werden, kann man zudem ins DeepL-Glossar eintragen +und damit eine bestimmte Übersetzung erzwingen. + +## Stilregeln + +### Du oder Sie + +Die aktuelle Übersetzung von Godot verwendet „Sie” statt „Du” bei direkter +Ansprache. Zwar wäre die freundlichere „Du”-Form im Gaming-Bereich ebenfalls +eine gute Wahl, jedoch ist eine Umstellung mit sehr viel Arbeit verbunden. +Die Diskussion einer Umstellung auf „Du” hängt daher in erster Linie an +der Frage, ob sich eine hinreichend große Menge an Freiwilligen finden, +um die *gesamte* Anleitung umzustellen. Bis dahin sollte aus +praktischen Gründen die Übersetzung beim formelleren „Sie” bleiben. + +> :arrow_forward: You can also use the search function in the top-left corner. +> +> :x: Du kannst auch die Suchfunktion in der oberen linken Ecke verwenden. +> +> :heavy_check_mark: Sie können auch die Suchfunktion in der oberen linken Ecke verwenden. + +### Grammatikalische Prinzipien + +Die Godot-Übersetzung lässt sich in vier grobe Blöcke einteilen: *Editor*, +*Properties*, *Anleitung* und *Klassenreferenz*. + +Jeder dieser Blöcke hat eigene Ansprüche +an eine Übersetzung. Während die Anleitung in erster Linie auf Verständlichkeit +ausgelegt ist und sich angenehm lesen soll, ist im Editor und den Properties +häufig eine etwas knappere Sprache erforderlich, weil oft nur begrenzt +Platz für die Texte zur Verfügung steht. + +Es ist daher sinnvoll, einige Grundregeln für die Übersetzung +aufzustellen. Beachte, dass diese Regeln nicht absolut sind und im Zweifel +mit Augenmaß übersetzt werden sollte. Trotzdem helfen solche Regeln, +einen einheitlichen Sprachstil über die gesamte Dokumentation hinweg zu fördern. + +Folgende Grundregeln werden aktuell in der Übersetzung angewendet: + +#### Anleitung/Klassenreferenz + +In der *Anleitung* sollte die grammatikalische Form des Originaltexts beibehalten +werden, es sei denn, die Lesbarkeit leidet darunter. Es sollte generell darauf +verzichtet werden, an dieser Stelle bestimmte Sprachkonstrukte grundsätzlich +zu vermeiden oder zu bevorzugen. Oft ist eine Anlehnung an den Originaltext +die bessere Wahl. Insbesondere die direkte Ansprache mit +„Sie” ist in diesem Teil der Dokumentation weit verbreitet und sollte +so beibehalten werden. + +Beispiele: + +> :arrow_forward: The table of contents in the sidebar should let you easily +> access the documentation for your topic of interest. +> +> :heavy_check_mark: Mithilfe des Inhaltsverzeichnisses in der Seitenleiste +> können Sie leicht auf die Dokumentation zu Ihrem gewünschten Thema zugreifen. + +
+ +> :arrow_forward: To move our icon, we need to update its position and rotation +> every frame in the game loop. +> +> :heavy_check_mark: Um unser Icon zu bewegen, müssen wir seine Position und +> Drehung in jedem Frame der Spielschleife aktualisieren. + +
+ +> :arrow_forward: This build can be manually triggered by clicking the "Build" +> button at the top right of the editor. +> +> :heavy_check_mark: Dieser Build kann manuell ausgelöst werden, indem man auf den +> „Build”-Button oben rechts im Editor klickt. + + +Bei manchen Abschnitten der Anleitung, wie bestimmten Überschriften oder Aufzählungen, +bietet sich der [Infinitiv-Imperativ](https://de.wikipedia.org/wiki/Imperativ_(Modus)#Infinitiv) an: + +Beispiele: + +> :arrow_forward: Setting up the project +> +> :heavy_check_mark: Das Projekt einrichten + +
+ +> :arrow_forward: For the player, we need to do the following: +> * Check for input. +> * Move in the given direction. +> * Play the appropriate animation. +> +> :heavy_check_mark: Für den Spieler müssen wir Folgendes tun: +> * Auf Eingaben prüfen. +> * Sich in die angegebene Richtung bewegen. +> * Die entsprechende Animation abspielen. + +#### Properties + +Die *Properties* sind sehr knapp beschriebene Eigenschaften von Godot-Features, +die im Editor oft nur wenig Platz zur Verfügung haben. Hier handelt es sich häufig +um einzelne Begriffe, bei denen die Schwierigkeit eher im Finden der korrekten +Vokabel besteht (dazu mehr unten), als in der grammatikalischen Form. + +Manchmal sind es jedoch kurze Sätze, die in den meisten Fällen am besten +im Infinitiv-Imperativ (siehe Beispiele oben) zu übersetzen sind, da diese Form +hier sprachlich gut passt und wenig Platz einnimmt. Auch sollten hier, wo möglich, +Artikel weggelassen werden, genauso wie es im Original meist schon gemacht wird. + + +> :arrow_forward: Keep Screen On +> +> :x: Der Bildschirm wird eingeschaltet gelassen +> +> :heavy_check_mark: Bildschirm eingeschaltet lassen + +#### Editor + +Die Texte des *Editors* bestehen sowohl aus kleinen Textblöcken, wenn z.B. ein Tooltip +eine Einstellung näher beschreibt, als auch aus kurzen Begriffen, die oft wenig +Platz zur Verfügung haben. + +Bei der Übersetzung des Editors gelten somit sowohl die Regeln für die Anleitung, als auch +die für die Properties, je nachdem, ob der zu übersetzende Text eher in Langform +oder in Kurzform geschrieben ist. + +### Keine Angst vor englischen Begriffen + +Manche Begriffe lassen sich nur schwer ins Deutsche übersetzen. Das sind zum +Beispiel technische Begriffe, die bereits in ihrer englischen +Form in den Sprachgebrauch Einzug gefunden haben (*Thread*, *Debuggen*, +*Spawn-Punkt*). + +Andere Begriffe haben gängige deutsche Übersetzungen, wie z.B. *Knoten* für *node*. +Da es in der Godot-Welt aber Objekte gibt, die feststehende Namen haben, +etwa `Node2D`, wollen wir davon abgeleitete Vokabeln ebenfalls englisch lassen. + +> :arrow_forward: This feature is only available when connecting nodes in the editor. +> +> :x: Dieses Feature ist nur verfügbar, wenn Knoten im Editor verbunden werden. +> +> :heavy_check_mark: Dieses Feature ist nur verfügbar, wenn Nodes im Editor verbunden werden. + +Du wirst beim Lesen der Anleitung viele dieser absichtlich eingedeutschten +Begriffe finden. Dies mag an der einen oder anderen Stelle etwas ungewohnt wirken, +aber es gibt viele Situationen, in denen damit Übersetzungsprobleme vermieden werden können. + +Sollte es vorkommen, dass eine Regel unsinnig erscheint, sollte das im +[Chat](https://chat.godotengine.org/channel/translation-de) diskutiert werden. Um einen Überblick über die dokumentierten Begriffe +zu bekommen, die englisch bleiben sollen, lohnt sich ein +Blick ins [Glossar](https://hosted.weblate.org/browse/godot-engine/glossary/de/). +Sollte ein Begriff dort nicht hinterlegt sein, kann man die Suchfunktion +von Weblate verwenden, um Beispiele in den vorhandenen Übersetzungen zu finden. + +Manchmal ist es auch notwendig, nach eigenem Empfinden eine Entscheidung zu +treffen oder von einer der Glossar-Regeln abzuweichen. +Das ist vollkommen okay, denn Sprache ist komplex, und man kann nicht für +jeden Sonderfall eine vordefinierte Lösung festlegen. + +Beispiel 1: + +> :arrow_forward: Stereo Panning +> +> :x: Stereoverschiebung +> +> :heavy_check_mark: Stereo-Panning + +Beispiel 2: + +> :arrow_forward: Drag to pan the view +> +> :x: Ziehen, um den View zu pannen. +> +> :heavy_check_mark: Ziehen um den View zu verschieben + + +Das erste Beispiel stammt aus dem Audio-Bereich, wo Stereo-Panning ein gängiger +Begriff ist. Das zweite Beispiel verwendet das Wort „panning” als +allgemeine Vokabel. Hier ist kein besonderer technischer Jargon +gemeint, somit kann das Wort auch normal auf Deutsch übersetzt werden. + +Diese Unterscheidung wird im Glossar oft mit zwei Einträge desselben Wortes +abgebildet. Dabei soll ein Beschreibungstext dabei helfen, zu erklären, +in welchem Kontext welche Übersetzung passend ist. + +Weiter unten findest Du Recherchetipps, die dabei helfen können, +eine passende Übersetzung zu finden, sollte ein Begriff weder im Glossar +noch in der bestehenden Dokumentation auffindbar sein. + +### Kompositionswörter + +Das im Deutschen übliche Aneinanderreihen von Wörtern (Komposition) wird +im Englischen durch das Hintereinandersetzen von Wörtern mit +Leerzeichen erreicht. Bei sehr langen Wortfolgen ergeben sich dabei +logische Untergruppen aus dem Zusammenhang, auch wenn das in Extremfällen +manchmal wenig intuitiv erscheint: + +> Default Font Multichannel Signed Distance Field + +Im Deutschen sollte dagegen vermieden werden, lange Kompositionen zu bilden, +da die Lesbarkeit extrem leidet, wenn die Wörter sehr lang werden. Eine +einfache Lösung ist hier, mithilfe von Bindestrichen Klarheit zu schaffen. +Allerdings ist es im Allgemeinen besser, die grammatikalische Struktur des +Begriffs +aufzubrechen und ihn klar zu beschreiben. Dabei ist es notwendig, +nachzulesen, was dieser Begriff im Kontext von Godot eigentlich genau bedeutet: + +> :arrow_forward: Medium Quality Probe Ray Count +> +> :x: Mittelqualitätsprobestrahlenanzahl +> +> :heavy_check_mark: Strahlenzahl für Probes bei mittlerer Qualität + +Es sollte bei der Übersetzung generell vermieden werden, überlange Komposita zu +erzeugen. Als Richtschnur sollten mehr als zwei Wörter nur in Ausnahmefällen zu +Komposita verbunden werden, mehr als drei Wörter hingegen am besten gar nicht. +Sollte sich keine brauchbare Übersetzung eines Kompositums finden, dann +sollten zumindest Bindestriche eingesetzt werden, um die Teilbegriffe klarer +voneinander zu trennen. + +Beispiele: + +> :arrow_forward: Interaction Profile Path +> +> :x: Interaktionsprofilpfad +> +> :heavy_check_mark: Interaktionsprofil-Pfad +> +> :heavy_check_mark: Pfad zum Interaktionsprofil + +
+ +> :arrow_forward: Render Target Size Multiplier +> +> :x: Renderzielgrößenfaktor +> +> :heavy_check_mark: Render-Zielgrößen-Faktor +> +> :heavy_check_mark: Faktor für Render-Zielgröße + +### Schachtelsätze und „die die”-Wiederholungen + +Beim direkten Übersetzen eines englischen Satzes kommt man leicht in +Versuchung, Schachtelsätze oder allgemein sehr lange Sätze zu bilden. Auch hier +ist eine KI-Vorübersetzung von Nutzen, die dies oft recht gut vermeidet. +Im Allgemeinen ist es allerdings einfach so, dass deutsche Wörter und Sätze im Mittel länger +als ihre englischen Pendants sind. Daher sollte darauf geachtet werden, +die deutsche Übersetzung nicht zu komplex oder zu lang werden zu lassen. Es +kann durchaus guter Stil sein, einen Satz in zwei Sätze aufzuteilen, auch wenn +dabei die grammatikalische Form des Originals nicht erhalten bleibt. + +Ein weiterer verwandter Aspekt ist hier die Verwendung der Wortwiederholung +„die die”, die ebenfalls vermieden werden sollte. Eine Ersetzung durch „welche +die” scheint oft naheliegend, klingt aber umständlich und ist keine gute Lösung. +Stattdessen ist eine Umformulierung des Satzes oft die bessere Wahl. + +Beispiele: + +> :arrow_forward: Min SDK cannot be lower than %d, which is the version +> needed by the Godot library. +> +> :x: Min SDK kann nicht niedriger als %d sein, der Version, die die +> Godot-Bibliothek benötigt. +> +> :heavy_check_mark: Min SDK kann nicht niedriger als %d sein (die +> Version, die von der Godot-Bibliothek benötigt wird). + +
+ +> :arrow_forward: In addition, one will need a primary GUI for their game that +> manages the various menus and widgets the project needs. +> +> :x: Außerdem benötigt man für sein Spiel eine primäre GUI, die die +> verschiedenen Menüs und Widgets verwaltet, die das Projekt benötigt. +> +> :heavy_check_mark: Außerdem benötigt man für sein Spiel eine primäre GUI, +> um die verschiedenen Menüs und Widgets des Projekts zu verwalten. +> +> :heavy_check_mark: Außerdem benötigt man für sein Spiel eine primäre GUI. +> Diese GUI verwaltet die verschiedenen Menüs und Widgets des Projekts. + +### Eigene Ergänzungen + +Achte bei der Übersetzung der Anleitung darauf, nur den Originaltext zu +übersetzen, ohne eigene Ergänzungen oder Erläuterungen vorzunehmen. Sollte +der Originaltext unvollständig oder erklärungswürdig sein, so beantrage zuerst +eine Änderung am Original oder stelle selbst einen Pull-Request in +[godot-docs](https://github.com/godotengine/godot-docs). +Wir sollten uns auf Weblate ausschließlich als Übersetzer und nicht als +Autoren verstehen. + +> :arrow_forward:: Computes the arctan of x +> +> :x: Berechnet den Arcustangens von x. Der Arcustangens ist die Umkehrfunktion +> des Tangens. +> +> :heavy_check_mark: Berechnet den Arcustangens von x + +## Konsistenz zwischen Editor/Properties und Anleitung + +Wenn Du einen Begriff aus dem Editor oder den Properties änderst, solltest Du +die Weblate-Seite der Anleitung nach diesen Begriffen durchsuchen und sie +entsprechend anpassen, damit die Übersetzungen konsistent bleiben. + +Beachte auch, dass ein Editor/Properties-Begriff meist an mehreren Stellen im Editor +oder den Properties vorkommt, sodass nach Möglichkeit alle dieser Stellen +mit übersetzt werden sollten. + +## Testen der Übersetzung + +Für Übersetzungen des Editors und der Properties ist es ratsam, diese +auch selbst zu testen, indem +man [die aktuelle Übersetzung herunterlädt](https://contributing.godotengine.org/en/latest/documentation/translation/index.html#offline-translation-and-testing) +und Godot mit den Änderungen [selbst kompiliert](https://docs.godotengine.org/de/4.x/engine_details/development/compiling/compiling_for_windows.html). + +Gerade bei der Anleitung kommt es oft auf den Kontext zwischen benachbarten +Textblöcken an, sodass das Lesen eines ganzen Artikels Fehler sichtbar +macht, die in Weblate leicht überlesen werden können. + +## Recherchetipps + +Grundsätzlich sollte man sich bei +der Übersetzung eines Begriffs gut überlegen, ob man eine korrekte +Übersetzung aus der eigenen Spracherfahrung vornehmen kann, oder besser erst +einmal etwas näher recherchieren sollte. + +Die erste Quelle bei der Übersetzung feststehender Begriffe +sollte das Glossar und die bestehenden Übersetzungen sein. +Die Suchfunktion von Weblate leistet hier gute Dienste. + +Wenn ein Begriff in diesen Quellen nicht gefunden werden kann oder Zweifel an +ihrer Korrektheit bestehen, gibt es einige weitere hilfreiche Quellen: + +Grundbegriffe aus der +Wissenschaft kann man auf der englischen [Wikipedia](https://www.wikipedia.org) +nachschlagen. +Von dort aus lässt sich über das Sprachmenü der deutsche +Schwesterartikel aufrufen, wo man oft eine korrekte deutsche Übersetzung des +Begriffs findet. Achte allerdings darauf, ob der deutsche Artikel auch +dieselbe Bedeutung des Wortes beschreibt, wie der englische Artikel. + +Bei weiteren allgemeinen technischen Begriffen kann +man auf Webseiten wie www.linguee.com zurückgreifen, um zu schauen, wie +ein Begriff von anderen, oft professionellen, Übersetzern in unterschiedlichen +Kontexten bereits übersetzt wurde. + +Zuletzt gibt es Fachbegriffe, die direkt aus dem Gaming oder Game-Design +stammen, und es ist sicherlich nicht verkehrt, bei der Übersetzung einmal +nachzuschauen, wie andere Tools aus dem Bereich diese Begriffe übersetzen +(Unity, Unreal). Da diese Tools über das Budget für professionelle +Übersetzer verfügen, ist dies eine besonders hilfreiche Quelle für sehr +spezifische Fachbegriffe. + +Zuletzt kann es sinnvoll sein, sich an erfahrene Entwickler zu wenden, um +die Übersetzung eines Begriffs zu klären, entweder im [Chat](https://chat.godotengine.org/channel/translation-de) oder im +[deutschen Godot-Discord](https://discord.com/channels/553242711109533729/) + + +## Glossar-Regeln + +Dieser Abschnitt befasst sich mit dem Glossar. Wenn Du einfach nur übersetzen +möchtest, kannst Du hier aufhören zu lesen. Falls Du aber Glossar-Einträge pflegen +möchtest, solltest Du weiterlesen. + +Das Weblate-Glossar folgt bestimmten eigenen Regeln, die beachtet werden +sollten: + +### Was kommt überhaupt ins Glossar? + +Das Glossar hat seinen praktischen Nutzen dort, wo man ein Wort an +verschiedenen Stellen gleich übersetzen möchte. Immer, wenn das +gewährleistet werden soll, lohnt sich auch ein Glossar-Eintrag. Beachte +allerdings auch, dass ein sehr großes Glossar Pflegeaufwand bedeutet. Nicht +jedes Wort muss also unbedingt einen Eintrag bekommen. + +> :x: color -> Farbe + +Das Wort „color” ist ziemlich eindeutig und bedarf vermutlich keiner +expliziten Klärung in einem Glossar. + +> :heavy_check_mark: ctrl -> Strg + +Hier haben wir einen Fachbegriff, der über ein eindeutiges +deutsches Äquivalent verfügt. Dafür kann man durch eine „Forbidden +Translation” (s.u.) darauf hinweisen, dass eine Übersetzung als das +vielleicht naheliegende „Ctrl” nicht zulässig ist. + + +> :heavy_check_mark: aligned -> bündig/ausgerichet + +In diesem Fall kann das Glossar dabei helfen, die verschiedenen +Übersetzungen des Wortes „aligned” zu definieren, das in der Form +*left-aligned* als *linksbündig* und in der Form *axis-aligned* als *an den +Achsen ausgerichtet* übersetzt werden sollte. + +> :heavy_check_mark: blitting -> Blitting + +Hier verweist das Glossar darauf, dass ein Begriff ein +feststehender Fachbegriff ist, der im keine gute deutsche Entsprechung +hat und daher englisch bleibt. + +### Ein Wort, ein Eintrag + +Da Weblate seine Glossar-Einträge bei der Übersetzung automatisch anbietet, +sobald im Originaltext ein bestimmter Begriff vorkommt, sollte +sichergestellt werden, dass Einträge auch gefunden werden. Das kann nur +gelingen, wenn ein Eintrag in der englischen Form genau so auch in einem +Text vorkommen kann. + +> :x: float, floats -> float +> +> :heavy_check_mark: float -> float + +Im vorigen Beispiel könnte Weblate für einen Text, der den *Float*-Datentyp +erklärt, den Glossareintrag nicht finden, da der Begriff *float, floats* so +im Originaltext nicht vorkommt. + +### Ein Wort, mehrere Bedeutungen + +Sollte ein englisches Wort auf mehrere Arten übersetzt werden können, dann +sollte für jede Übersetzung ein eigener Glossar-Eintrag angelegt werden. +Dies hilft bei der Lesbarkeit und macht es später leichter, weitere Bedeutungen +hinzuzufügen. + +> :x: volume -> Volumen, Lautstärke +> +> :heavy_check_mark: volume -> Volumen (*Translation Explanation:* im Sinne von „Rauminhalt”) +> +> :heavy_check_mark: volume -> Lautstärke (*Translation Explanation:* im Audio-Kontext) + +Es bietet sich an, über das jeweilige „Translation Explanation”-Feld +zu beschreiben, wie sich +die verschiedenen Übersetzungen unterscheiden und in welchen Fällen man sie +verwenden sollte. + +**Achtung:** Es gibt auch das Feld +„Explanation”, das für die Erklärung des Originaltextes gedacht +ist. Dieses Feld sollte nicht verwendet werden, da es in der Seitenleiste +zu unschönen Doppeleinträgen führen kann. + +### Grundformen verwenden + +Ein englisches Wort sollte grundsätzlich in seiner einfachsten Form ins +Glossar eingetragen werden, damit es in möglichst vielen Fällen automatisch +zugeordnet werden kann. Das bedeutet bei Verben die Grundform (**wichtig:** ohne *to*) +und bei Substantiven der Singular. + +Beispiele: + +> :x: to hide -> verbergen +> +> :heavy_check_mark: hide -> verbergen + +
+ +> :x: constants -> Konstanten +> +> :heavy_check_mark: constant -> Konstante + +Leider unterstützt die aktuelle Version von Weblate keine +morphologischen Varianten. Wenn also ein Wort im Glossar als Singular angegeben wird, dann +wird es beim Übersetzen nur angeboten, wenn auch im Übersetzungstext der Singular +verwendet wird. Es gibt bereits ein [Ticket](https://github.com/WeblateOrg/weblate/issues/3023) +dazu im Weblate-Github. Bis zur Lösung dieses Problems sollten wir vermeiden, +als Workaround Singular *und* Plural-Einträge im Glossar zu erzeugen, da das +schlecht zu warten ist. + +### Terminology + +Ein als „Terminology” markierter Eintrag wird automatisch in allen +anderen Sprachen in die Glossare eingetragen und führt dort zu offenen +Arbeitspaketen. + +Das kann dazu führen, dass neue Glossareinträge in der deutschen +Übersetzung erscheinen, weil eine andere Sprache sie eingefügt hat. In diesem +Fall ist es legitim, das Terminology-Flag zu entfernen und den Eintrag zu löschen, +wenn er aus unserer Sicht nicht sinnvoll ist. Dieser Vorgang lässt den Eintrag +in allen anderen Sprachen unverändert. + +Wir sollten das Terminology-Flag grundsätzlich nicht setzen, da es potentiell +die Glossare anderer Sprachen zumüllt, insbesondere, wenn diese andere Definitionen +davon haben, welche Art von Begriffen als „Terminologie” zu bewerten sind. + + +### Untranslatable + +Ein als „Untranslatable” markierter Eintrag ist ein Begriff, der bewusst nicht +übersetzt werden soll, z.B. feststehende Begriffe wie `Android` oder `OpenGL`. +Allerdings haben viele dieser Begriffe eigentlich nichts im Glossar verloren, +sodass dieses Flag nicht allzu häufig vorkommen sollte. +Man kann einen als „Untranslatable” markierten Begriff daran +erkennen, dass er bei der Glossar-Einblendung in der Seitenleiste gelb hinterlegt ist. + +### Forbidden Translation + +Ein als „Forbidden Translation” markierter Eintrag kann dazu verwendet +werden, um eine Übersetzung aufzuzeigen, die nicht verwendet werden soll, zum +Beispiel weil sie einen fehleranfälligen +[Falschen Freund](https://de.wikipedia.org/wiki/Falscher_Freund) darstellt +oder um bestimmte deutsche Begriffe zu sperren. Zum Beispiel könnte man sich +darauf einigen, den Begriff *enemy* durchgängig als *Gegner* und nicht als das +extremere *Feind* zu übersetzen. In dem Fall würden beide Begriffe ins Glossar +eingetragen, wobei der zweite als „Forbidden Translation” markiert wird. + +## Änderungen an diesem Dokument + +Änderungen an diesem Dokument sollten im [Chat](https://chat.godotengine.org/channel/translation-de) diskutiert und nach +Klärung per Pull-Request ins Github-Repo committet werden. diff --git a/_templates/breadcrumbs.html b/_templates/breadcrumbs.html index 804ad69e671..bf1f8389aeb 100644 --- a/_templates/breadcrumbs.html +++ b/_templates/breadcrumbs.html @@ -1,7 +1,40 @@ {%- extends "sphinx_rtd_theme/breadcrumbs.html" %} +{% block breadcrumbs %} +
  • +
    + {{ godot_docs_title | replace("%s", godot_version) }} +
    +
      + {{ super() }} +
    +
    • +{% endblock %} + {% block breadcrumbs_aside %} {% if not meta or meta.get('github_url') != 'hide' %} -{{ super() }} +
  • +
      + {{ super() }} +
    + + + + Learn how to contribute! + +
    • {% endif %} {% endblock %} diff --git a/_templates/layout.html b/_templates/layout.html index fdec13a7bc8..609d6c5cd9d 100644 --- a/_templates/layout.html +++ b/_templates/layout.html @@ -1,19 +1,79 @@ {% extends "!layout.html" -%} -{% block linktags -%} - - {% if godot_inject_language_links -%} - {% for alternate_lang in godot_docs_supported_languages -%} - {# Convert to ISO 639-1 format, e.g. zh_CN -> zh-cn -#} - {% set alternate_lang_href = alternate_lang.lower().replace("_", "-") -%} - - {% endfor -%} - - - - {% endif -%} - {{ super() }} -{% endblock -%} +{# Refer to https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html #} {% block htmltitle -%} {{ godot_title_prefix }}{{ title|striptags|e }}{{ titlesuffix }} {% endblock -%} + +{% block extrahead -%} + + + +{% endblock -%} + +{% block linktags -%} + + {{ super() }} +{% endblock -%} + +{%- block document %} +
    + {% if godot_is_latest or godot_show_article_status %} +
    + {% if godot_is_latest %} +
    +

    Attention: Here be dragons

    +

    + This is the latest + (unstable) version of this documentation, which may document features + not available in or compatible with released stable versions of Godot. +

    +

    + Checking the stable version of the documentation... +

    +
    + {% endif %} + + {% if godot_show_article_status and not godot_is_latest and meta and meta.get('article_outdated') == 'True' %} +
    +

    Work in progress

    +

    + The content of this page was not yet updated for Godot + {{ godot_version }} + and may be outdated. If you know how to improve this page or you can confirm + that it's up to date, feel free to open a pull request. +

    +
    + {% endif %} +
    + {% endif %} + + {% block body %}{% endblock %} + +{% if (not meta or meta.get('allow_comments') != 'False') and godot_show_article_comments %} +
    + {%- if (theme_prev_next_buttons_location == 'bottom' or theme_prev_next_buttons_location == 'both') and (next or prev) %} + + {%- endif %} +
    +

    User-contributed notes

    +

    + Please read the User-contributed notes policy before submitting a comment. +

    +
    +{% endif %} + +{%- if self.comments()|trim %} +
    + {%- block comments %}{% endblock %} +
    +{%- endif%} +
    +{%- endblock %} diff --git a/_templates/versions.html b/_templates/versions.html new file mode 100644 index 00000000000..e46ca819a95 --- /dev/null +++ b/_templates/versions.html @@ -0,0 +1,60 @@ +{# Add rst-badge after rst-versions for small badge style. #} +{% set display_version = version -%} +{% set listed_languages = ({"en":"#", "de":"#", "es":"#", "fr":"#"}).items() -%} +{% set listed_versions = ({"stable":"#", "latest":"#"}).items() -%} + +{% if READTHEDOCS and current_version %} + {% set display_version = current_version -%} +{% endif %} +{% if READTHEDOCS and versions %} + {% set listed_versions = versions -%} +{% endif %} + +
    + + Read the Docs + v: {{ display_version }}{% if display_version != godot_version %} ({{ godot_version }}){% endif %} + + +
    + {# + The contents of this element will be replaced in production. + But we can still have some mock data for testing. + #} + +
    +
    {{ _('Languages') }}
    + {% for slug, url in listed_languages %} +
    {{ slug }}
    + {% endfor %} +
    +
    +
    {{ _('Versions') }}
    + {% for slug, url in listed_versions %} +
    {{ slug }}
    + {% endfor %} +
    +
    + {# Translators: The phrase "Read the Docs" is not translated #} +
    {{ _('On Read the Docs') }}
    +
    + {{ _('Project Home') }} +
    +
    + {{ _('Builds') }} +
    +
    + {{ _('Downloads') }} +
    +
    + +
    + + Hosted by Read the Docs + · + Privacy Policy + + + {##} +
    +
    diff --git a/_tools/check-rst.sh b/_tools/check-rst.sh new file mode 100755 index 00000000000..3abb28cbc2a --- /dev/null +++ b/_tools/check-rst.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash + +set -uo pipefail + +output=$(grep -r -P '^(?!\s*\.\.).*\S::$' --include='*.rst' --exclude='docs_writing_guidelines.rst' .) +if [[ -n $output ]]; then + echo 'The shorthand codeblock syntax (trailing `::`) is not allowed.' + echo "$output" + exit 1 +fi diff --git a/_tools/codespell-dict.txt b/_tools/codespell-dict.txt new file mode 100644 index 00000000000..f8e93f339d9 --- /dev/null +++ b/_tools/codespell-dict.txt @@ -0,0 +1 @@ +anti-aliasing->antialiasing diff --git a/_tools/codespell-ignore-lines.txt b/_tools/codespell-ignore-lines.txt index 7a125d5a12c..dc72b48eec3 100644 --- a/_tools/codespell-ignore-lines.txt +++ b/_tools/codespell-ignore-lines.txt @@ -1 +1 @@ -| te | Telugu | +.. image:: img/expres.png diff --git a/_tools/codespell-ignore.txt b/_tools/codespell-ignore.txt index aaf18813b9d..61c28438701 100644 --- a/_tools/codespell-ignore.txt +++ b/_tools/codespell-ignore.txt @@ -4,3 +4,7 @@ lod que raison uint +implementors +thirdparty +inout +findn diff --git a/_tools/format.sh b/_tools/format.sh deleted file mode 100755 index 1b0e22f0be3..00000000000 --- a/_tools/format.sh +++ /dev/null @@ -1,42 +0,0 @@ -#!/usr/bin/env bash - -set -uo pipefail -IFS=$'\n\t' - -# Loops through all text files tracked by Git. -git grep -zIl '' | -while IFS= read -rd '' f; do - # Exclude csproj and hdr files. - if [[ "$f" == *"csproj" ]]; then - continue - elif [[ "$f" == *"hdr" ]]; then - continue - fi - # Ensures that files are UTF-8 formatted. - recode UTF-8 "$f" 2> /dev/null - # Ensures that files have LF line endings. - dos2unix "$f" 2> /dev/null - # Ensures that files do not contain a BOM. - sed -i '1s/^\xEF\xBB\xBF//' "$f" - # Ensures that files end with newline characters. - tail -c1 < "$f" | read -r _ || echo >> "$f"; -done - -git diff > patch.patch -FILESIZE="$(stat -c%s patch.patch)" -MAXSIZE=5 - -# If no patch has been generated all is OK, clean up, and exit. -if (( FILESIZE < MAXSIZE )); then - printf "Files in this commit comply with the formatting rules.\n" - rm -f patch.patch - exit 0 -fi - -# A patch has been created, notify the user, clean up, and exit. -printf "\n*** The following differences were found between the code " -printf "and the formatting rules:\n\n" -cat patch.patch -printf "\n*** Aborting, please fix your commit(s) with 'git commit --amend' or 'git rebase -i '\n" -rm -f patch.patch -exit 1 diff --git a/_tools/list-unused-images.sh b/_tools/list-unused-images.sh old mode 100644 new mode 100755 index 44c70f6d480..58d3ce7ba0a --- a/_tools/list-unused-images.sh +++ b/_tools/list-unused-images.sh @@ -1,4 +1,7 @@ -#!/bin/bash +#!/usr/bin/env bash + +set -uo pipefail +IFS=$'\n\t' check_git_history=false @@ -9,19 +12,17 @@ rm -f tmp-unused-images-history # Exceptions are ignored, and for .svg files we also look for potential .png # files with the same base name, as they might be sources. -exceptions="docs_logo.png tween_cheatsheet.png" - -files=$(find -name "_build" -prune -o \( -name "*.png" -o -name "*.jpg" -o -name "*.svg" -o -name "*.gif" \) -print | sort) +files=$(find -name "_build" -prune -o \( -iname "*.png" -o -iname "*.webp" -o -iname "*.jpg" -o -iname "*.svg" -o -iname "*.gif" \) -print | sort) for path in $files; do - file=$(basename $path) - if echo "$exceptions" | grep -q "$file"; then + file=$(basename "$path") + if [[ "$path" == *./img/* ]]; then continue fi ext=${file##*.} base=${file%.*} found=$(rg -l ":: .*[ /]$file") - if [ -z "$found" -a "$ext" == "svg" ]; then + if [ -z "$found" ] && [ "$ext" == "svg" ]; then # May be source file. found=$(rg -l ":: .*[ /]$base.png") fi @@ -30,11 +31,13 @@ for path in $files; do fi done +echo "Wrote list of unused images to: tmp-unused-images" if [ "$check_git_history" = true ]; then for file in $(cat tmp-unused-images); do echo "File: $file" - git log --diff-filter=A --follow $file + git log --diff-filter=A --follow "$file" echo done > tmp-unused-images-history + echo "Wrote list of unused images in Git history to: tmp-unused-images-history" fi diff --git a/_tools/redirects/README.md b/_tools/redirects/README.md new file mode 100644 index 00000000000..c991b956426 --- /dev/null +++ b/_tools/redirects/README.md @@ -0,0 +1,54 @@ +# ReadTheDocs redirect tools + +The scripts located in this directory help in creating and maintaining redirects on [Read the Docs](https://readthedocs.io). +Also refer to Read the Docs [API documentation](https://docs.readthedocs.io/en/stable/api/index.html). + +Note that RTD redirects only apply in case of 404 errors, and to all branches and languages: +. +If this ever changes, we need to rework how we manage these (likely adding per-branch logic). + +`convert_git_renames_to_csv.py` creates a list of renamed files in Git to create redirects for. +`create_redirects.py` is used to actually manage redirects on ReadTheDocs. + +For more information on the scripts themselves, see their help output. + +## Setup + +To install requirements: `pip3 install -r requirements.txt`. +Git is also required and needs to be available in the `PATH`. +To interact with the Read the Docs API, a valid API key must be set as +`RTD_AUTH_TOKEN` (either as an environment variable or in a [.env file](https://pypi.org/project/python-dotenv/)). + +## Usage + +Let's say we recently renamed some files in the Git branch `3.4` (compared to the `stable` branch), +and now we want to create redirects for these. For this, we would (after setting up the API token +and requirements, see Setup above): + +``` +python convert_git_renames_to_csv.py stable 3.4 +``` + +This should output a list of the redirects to create. Let's append these to the redirects file: + +``` +python convert_git_renames_to_csv.py stable 3.4 >> ../../_tools/redirects.csv +``` + +After this, redirects for renamed files should have been appended to `../../_tools/redirects.csv`. +You may want to double-check that! Now let's submit these to ReadTheDocs and create redirects there: + +``` +python create_redirects.py +``` + +And that should be it! + +The script takes care to not add duplicate redirects if the same ones already exist. +The created redirects are also valid for all branches and languages, which works out +as they only apply for actually missing files - when a user encounters a 404, that is. + +The script also only touches `page` type redirects, all other types may still be added +and managed manually on RTD or via other means. All `page` redirects need to +be managed with these tools however, as they will otherwise just overwrite any +changes made elsewhere. diff --git a/_tools/redirects/convert_git_renames_to_csv.py b/_tools/redirects/convert_git_renames_to_csv.py new file mode 100644 index 00000000000..6a6cd09d297 --- /dev/null +++ b/_tools/redirects/convert_git_renames_to_csv.py @@ -0,0 +1,115 @@ +#!/usr/bin/env python3 + +"""Uses Git to list files that were renamed between two revisions and converts +that to a CSV table. + +Use it to prepare and double-check data for create_redirects.py. +""" + +import subprocess +import argparse +import csv +import sys + + +def parse_command_line_args(): + parser = argparse.ArgumentParser( + description="Uses Git to list files that were renamed between two revisions and " + "converts that to a CSV table. Use it to prepare and double-check data for create_redirects.py." + ) + parser.add_argument( + "revision1", + type=str, + help="Start revision to get renamed files from (old).", + ) + parser.add_argument( + "revision2", + type=str, + help="End revision to get renamed files from (new).", + ) + parser.add_argument("-f", "--output-file", type=str, help="Path to the output file") + return parser.parse_args() + + +def dict_item_to_str(item): + s = "" + for key in item: + s += item[key] + return s + + +def main(): + try: + subprocess.check_output(["git", "--version"]) + except subprocess.CalledProcessError: + print("Git not found. It's required to run this program.") + exit(1) + + args = parse_command_line_args() + assert args.revision1 != args.revision2, "Revisions must be different." + for revision in [args.revision1, args.revision2]: + assert not "/" in revision, "Revisions must be local branches only." + + # Ensure that both revisions are present in the local repository. + for revision in [args.revision1, args.revision2]: + try: + subprocess.check_output( + ["git", "rev-list", f"HEAD..{revision}"], stderr=subprocess.STDOUT + ) + except subprocess.CalledProcessError: + print( + f"Revision {revision} not found in this repository. " + "Please make sure that both revisions exist locally in your Git repository." + ) + exit(1) + + # Get the list of renamed files between the two revisions. + renamed_files = ( + subprocess.check_output( + [ + "git", + "diff", + "--find-renames", + "--name-status", + "--diff-filter=R", + args.revision1, + args.revision2, + ] + ) + .decode("utf-8") + .split("\n") + ) + renamed_documents = [f for f in renamed_files if f.lower().endswith(".rst")] + + csv_data: list[dict] = [] + + for document in renamed_documents: + _, source, destination = document.split("\t") + source = source.replace(".rst", ".html") + destination = destination.replace(".rst", ".html") + if not source.startswith("/"): + source = "/" + source + if not destination.startswith("/"): + destination = "/" + destination + csv_data.append( + {"source": source, "destination": destination} + ) + + if len(csv_data) < 1: + print("No renames found for", args.revision1, "->", args.revision2) + return + + csv_data.sort(key=dict_item_to_str) + + out = args.output_file + if not out: + out = sys.stdout.fileno() + + with open(out, "w", encoding="utf-8", newline="") as f: + writer = csv.DictWriter(f, fieldnames=csv_data[0].keys()) + writer.writeheader() + writer.writerows(csv_data) + + +if __name__ == "__main__": + main() diff --git a/_tools/redirects/create_redirects.py b/_tools/redirects/create_redirects.py new file mode 100644 index 00000000000..67c5fd9563b --- /dev/null +++ b/_tools/redirects/create_redirects.py @@ -0,0 +1,344 @@ +#!/usr/bin/env python3 + +"""Manages page redirects for the Godot documentation on ReadTheDocs. (https://docs.godotengine.org) +Note that RTD redirects only apply in case of 404 errors, and to all branches and languages: +https://docs.readthedocs.io/en/stable/user-defined-redirects.html. +If this ever changes, we need to rework how we manage these (likely adding per-branch logic). + +How to use: +- Install requirements: pip3 install -r requirements.txt +- Store your API token in RTD_API_TOKEN environment variable or + a .env file (the latter requires the package dotenv) +- Generate new redirects from two git revisions using convert_git_renames_to_csv.py +- Run this script + +Example: + python convert_git_renames_to_csv.py stable latest >> redirects.csv + python create_redirects.py + +This would add all files that were renamed in latest from stable to redirects.csv, +and then create the redirects on RTD accordingly. +Make sure to use the old branch first, then the more recent branch (i.e., stable > master). +You need to have both branches or revisions available and up to date locally. +Care is taken to not add redirects that already exist on RTD. +""" + +import argparse +import csv +import os +import time + +import requests +from requests.models import default_hooks +from requests.adapters import HTTPAdapter +from requests.packages.urllib3.util.retry import Retry + +RTD_AUTH_TOKEN = "" +REQUEST_HEADERS = "" +REDIRECT_URL = "https://readthedocs.org/api/v3/projects/godot/redirects/" +USER_AGENT = "Godot RTD Redirects on Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36" +DEFAULT_PAGINATED_SIZE = 1024 +API_SLEEP_TIME = 0.2 # Seconds. +REDIRECT_SUFFIXES = [".html", "/"] +BUILD_PATH = "../../_build/html" +TIMEOUT_SECONDS = 5 +HTTP = None + +def parse_command_line_args(): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument( + "-f", + "--file", + metavar="file", + default="../../_static/redirects.csv", + type=str, + help="Path to a CSV file used to keep a list of redirects, containing two columns: source and destination.", + ) + parser.add_argument( + "--delete", + action="store_true", + help="Deletes all currently setup 'page' and 'exact' redirects on ReadTheDocs.", + ) + parser.add_argument( + "--dry-run", + action="store_true", + help="Safe mode: Run the program and output information without any calls to the ReadTheDocs API.", + ) + parser.add_argument( + "--dump", + action="store_true", + help="Only dumps or deletes (if --delete) existing RTD redirects, skips submission.", + ) + parser.add_argument( + "-v", + "--verbose", + action="store_true", + help="Enables verbose output.", + ) + parser.add_argument( + "--validate", + action="store_true", + help="Validates each redirect by checking the target page exists. Implies --dry-run.", + ) + return parser.parse_args() + +def is_dry_run(args): + return args.dry_run or args.validate + +def validate(destination): + p = BUILD_PATH + destination + if not os.path.exists(p): + print("Invalid destination: " + destination + " (" + p + ")") + +def make_redirect(source, destination, args, retry=0): + if args.validate: + validate(destination) + + json_data = {"from_url": source, "to_url": destination, "type": "page"} + headers = REQUEST_HEADERS + + if args.verbose: + print("POST " + REDIRECT_URL, headers, json_data) + + if is_dry_run(args): + if not args.validate: + print(f"Created redirect {source} -> {destination} (DRY RUN)") + return + + response = HTTP.post( + REDIRECT_URL, + json=json_data, + headers=headers, + timeout=TIMEOUT_SECONDS + ) + + if response.status_code == 201: + print(f"Created redirect {source} -> {destination}") + elif response.status_code == 429 and retry<5: + retry += 1 + time.sleep(retry*retry) + make_redirect(source, destination, args, retry) + return + else: + print( + f"Failed to create redirect {source} -> {destination}. " + f"Status code: {response.status_code}" + ) + exit(1) + + +def sleep(): + time.sleep(API_SLEEP_TIME) + + +def id(from_url, to_url): + return from_url + " -> " + to_url + + +def get_paginated(url, parameters={"limit": DEFAULT_PAGINATED_SIZE}): + entries = [] + count = -1 + while True: + data = HTTP.get( + url, + headers=REQUEST_HEADERS, + params=parameters, + timeout=TIMEOUT_SECONDS + ) + if data.status_code != 200: + if data.status_code == 401: + print("Access denied, check RTD API key in RTD_AUTH_TOKEN!") + print("Error accessing RTD API: " + url + ": " + str(data.status_code)) + exit(1) + else: + json = data.json() + if json["count"] and count < 0: + count = json["count"] + entries.extend(json["results"]) + next = json["next"] + if next and len(next) > 0 and next != url: + url = next + sleep() + continue + if count > 0 and len(entries) != count: + print( + "Mismatch getting paginated content from " + url + ": " + + "expected " + str(count) + " items, got " + str(len(entries))) + exit(1) + return entries + + +def delete_redirect(id): + url = REDIRECT_URL + str(id) + data = HTTP.delete(url, headers=REQUEST_HEADERS, timeout=TIMEOUT_SECONDS) + if data.status_code != 204: + print("Error deleting redirect with ID", id, "- code:", data.status_code) + exit(1) + else: + print("Deleted redirect", id, "on RTD.") + + +def get_existing_redirects(delete=False): + redirs = get_paginated(REDIRECT_URL) + existing = [] + for redir in redirs: + if redir["type"] != "page": + print( + "Ignoring redirect (only type 'page' is handled): #" + + str(redir["pk"]) + " " + id(redir["from_url"], redir["to_url"]) + + " on ReadTheDocs is '" + redir["type"] + "'. " + ) + continue + if delete: + delete_redirect(redir["pk"]) + sleep() + else: + existing.append([redir["from_url"], redir["to_url"]]) + return existing + + +def set_auth(token): + global RTD_AUTH_TOKEN + RTD_AUTH_TOKEN = token + global REQUEST_HEADERS + REQUEST_HEADERS = {"Authorization": f"token {RTD_AUTH_TOKEN}", "User-Agent": USER_AGENT} + + +def load_auth(): + try: + import dotenv + dotenv.load_dotenv() + except: + print("Failed to load dotenv. If you want to use .env files, install the dotenv.") + token = os.environ.get("RTD_AUTH_TOKEN", "") + if len(token) < 1: + print("Missing auth token in RTD_AUTH_TOKEN env var or .env file not found. Aborting.") + exit(1) + set_auth(token) + + +def has_suffix(s, suffixes): + for suffix in suffixes: + if s.endswith(suffix): + return True + return False + + +def is_valid_redirect_url(url): + if len(url) < len("/a"): + return False + + if not has_suffix(url.lower(), REDIRECT_SUFFIXES): + return False + + return True + + +def redirect_to_str(item): + return id(item[0], item[1]) + + +def main(): + args = parse_command_line_args() + + if not is_dry_run(args): + load_auth() + + retry_strategy = Retry( + total=3, + status_forcelist=[429, 500, 502, 503, 504], + backoff_factor=2, + method_whitelist=["HEAD", "GET", "PUT", "DELETE", "OPTIONS", "TRACE"] + ) + adapter = HTTPAdapter(max_retries=retry_strategy) + global HTTP + HTTP = requests.Session() + HTTP.mount("https://", adapter) + HTTP.mount("http://", adapter) + + to_add = [] + redirects_file = [] + with open(args.file, "r", encoding="utf-8") as f: + redirects_file = list(csv.DictReader(f)) + if len(redirects_file) > 0: + assert redirects_file[0].keys() == { + "source", + "destination", + }, "CSV file must have a header and two columns: source, destination." + + for row in redirects_file: + to_add.append([row["source"], row["destination"]]) + print("Loaded", len(redirects_file), "redirects from", args.file + ".") + + existing = [] + if not is_dry_run(args): + existing = get_existing_redirects(args.delete) + print("Loaded", len(existing), "existing redirects from RTD.") + + print("Total redirects:", str(len(to_add)) + + " new + " + str(len(existing)), "existing =", to_add+existing, "total") + + redirects = [] + added = {} + sources = {} + + for redirect in to_add: + if len(redirect) != 2: + print("Invalid redirect:", redirect, "- expected 2 elements, got:", len(redirect)) + continue + + if redirect[0] == redirect[1]: + print("Invalid redirect:", redirect, "- redirects to itself!") + continue + + if not is_valid_redirect_url(redirect[0]) or not is_valid_redirect_url(redirect[1]): + print("Invalid redirect:", redirect, "- invalid URL!") + continue + + if not redirect[0].startswith("/") or not redirect[1].startswith("/"): + print("Invalid redirect:", redirect, "- invalid URL: should start with slash!") + continue + + if redirect[0] in sources: + print("Invalid redirect:", redirect, + "- collision, source", redirect[0], "already has redirect:", + sources[redirect[0]]) + continue + + redirect_id = id(redirect[0], redirect[1]) + if redirect_id in added: + # Duplicate; skip. + continue + + added[redirect_id] = True + sources[redirect[0]] = redirect + redirects.append(redirect) + + redirects.sort(key=redirect_to_str) + + with open(args.file, "w", encoding="utf-8", newline="") as f: + writer = csv.writer(f) + writer.writerows([["source", "destination"]]) + writer.writerows(redirects) + + existing_ids = {} + for e in existing: + existing_ids[id(e[0], e[1])] = True + + if not args.dump: + print("Creating redirects.") + for redirect in redirects: + if not id(redirect[0], redirect[1]) in existing_ids: + make_redirect(redirect[0], redirect[1], args) + + if not is_dry_run(args): + sleep() + + print("Finished creating", len(redirects), "redirects.") + + if is_dry_run(args): + print("THIS WAS A DRY RUN, NOTHING WAS SUBMITTED TO READTHEDOCS!") + + +if __name__ == "__main__": + main() diff --git a/_tools/redirects/requirements.txt b/_tools/redirects/requirements.txt new file mode 100644 index 00000000000..987545961fe --- /dev/null +++ b/_tools/redirects/requirements.txt @@ -0,0 +1,2 @@ +python-dotenv==0.18.0 +requests==2.32.4 diff --git a/about/complying_with_licenses.rst b/about/complying_with_licenses.rst index ef87b00a21d..6ba70db555f 100644 --- a/about/complying_with_licenses.rst +++ b/about/complying_with_licenses.rst @@ -1,14 +1,21 @@ +:allow_comments: False + .. _doc_complying_with_licenses: Complying with licenses ======================= +.. warning:: + + The recommendations in this page **are not legal advice.** They are provided + in good faith to help users navigate license attribution requirements. + What are licenses? ------------------ Godot is created and distributed under the `MIT License `_. -It doesn't have a sole owner either, as every contributor that submits code to -the project does it under this same license and keeps ownership of the +It doesn't have a sole owner, as every contributor that submits code to +the project does it under this same license and keeps ownership of their contribution. The license is the legal requirement for you (or your company) to use and @@ -16,6 +23,19 @@ distribute the software (and derivative projects, including games made with it). Your game or project can have a different license, but it still needs to comply with the original one. +.. note:: + + This section covers compliance with licenses from a user perspective. + If you are interested in licence compliance as a contributor, you can find + guidelines `here `__. + +.. tip:: + + Alongside the Godot license text, remember to also list third-party notices + for assets you're using, such as textures, models, sounds, music and fonts. + This includes free assets, which often come with licenses that require + attribution. + Requirements ------------ @@ -24,16 +44,33 @@ text somewhere in your game or derivative project. This text reads as follows: +.. code-block:: none + This game uses Godot Engine, available under the following license: - Copyright (c) 2007-2021 Juan Linietsky, Ariel Manzur. - Copyright (c) 2014-2021 Godot Engine contributors. + Copyright (c) 2014-present Godot Engine contributors. + Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. - Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: - The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + +Beside its own MIT license, Godot includes code from a number of third-party +libraries. See :ref:`doc_complying_with_licenses_thirdparty` for details. .. note:: @@ -44,96 +81,83 @@ This text reads as follows: Inclusion --------- -The license does not specify how it has to be included, so anything is valid as -long as it can be displayed under some condition. These are the most common -approaches (only need to implement one of them, not all). +The license text must be made available to the user. The license doesn't specify +how the text has to be included, but here are the most common approaches (you +only need to implement one of them, not all). Credits screen -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ Include the above license text somewhere in the credits screen. It can be at the bottom after showing the rest of the credits. Most large studios use this approach with open source licenses. Licenses screen -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ Some games have a special menu (often in the settings) to display licenses. +This menu is typically accessed with a button called **Third-party Licenses** +or **Open Source Licenses**. Output log -^^^^^^^^^^ +~~~~~~~~~~ -Just printing the licensing text using the :ref:`print() ` +Printing the license text using the :ref:`print() ` function may be enough on platforms where a global output log is readable. -This is the case on desktop platforms, Android and HTML5 (but not iOS and UWP). +This is the case on desktop platforms, Android and HTML5 (but not iOS). Accompanying file -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ If the game is distributed on desktop platforms, a file containing the license -can be added to the software that is installed to the user PC. +text can be added to the software that is installed to the user PC. Printed manual -^^^^^^^^^^^^^^ - -If the game includes printed manuals, license text can be included there. +~~~~~~~~~~~~~~ -Third-party licenses --------------------- - -Godot itself contains software written by -`third parties `_. -Most of it does not require license inclusion, but some do. -Make sure to do it if these are compiled in your Godot export template. If -you're using the official export templates, all libraries are enabled. This -means you need to provide attribution for all the libraries listed below. - -Here's a list of libraries requiring attribution: - -FreeType -^^^^^^^^ +If the game includes a printed manual, the license text can be included there. -Godot uses `FreeType `_ to render fonts. Its license -requires attribution, so the following text must be included together with the -Godot license: +Link to the license +~~~~~~~~~~~~~~~~~~~ - Portions of this software are copyright © The FreeType Project (www.freetype.org). All rights reserved. +The Godot Engine developers consider that a link to ``godotengine.org/license`` +in your game documentation or credits would be an acceptable way to satisfy +the license terms. -ENet -^^^^ +.. tip:: -Godot includes the `ENet `_ library to handle -high-level multiplayer. ENet has similar licensing terms as Godot: + Godot provides several methods to get license information in the + :ref:`Engine ` singleton. This allows you to source the + license information directly from the engine binary, which prevents the + information from becoming outdated if you update engine versions. + For the engine itself: - Copyright (c) 2002-2020 Lee Salzman + - :ref:`Engine.get_license_text` - Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + For third-party components used by the engine: - The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + - :ref:`Engine.get_license_info` + - :ref:`Engine.get_copyright_info` - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.. _doc_complying_with_licenses_thirdparty: -MBedTLS -^^^^^^^ - -If the project is done with Godot 3.1 or above and it utilizes SSL (usually -through HTTP requests), the `MBedTLS `_ Apache license -needs to be complied by including the following text: - - Copyright The Mbed TLS Contributors +Third-party licenses +-------------------- - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. - You may obtain a copy of the License at +Godot itself contains software written by +`third parties `_, +which is compatible with, but not covered by Godot's MIT license. - http://www.apache.org/licenses/LICENSE-2.0 +Many of these dependencies are distributed under permissive open source licenses +which require attribution by explicitly citing their copyright statement and +license text in the final product's documentation. - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +Given the scope of the Godot project, this is fairly difficult to do thoroughly. +For the Godot editor, the full documentation of third-party copyrights and +licenses is provided in the `COPYRIGHT.txt `_ +file. -Keep in mind that Godot 2.x and 3.0 use `OpenSSL `_ -instead. +A good option for end users to document third-party licenses is to include this +file in your project's distribution, which you can e.g. rename to +``GODOT_COPYRIGHT.txt`` to prevent any confusion with your own code and assets. diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst index 5f9ea448b18..a48e057e0fc 100644 --- a/about/docs_changelog.rst +++ b/about/docs_changelog.rst @@ -1,53 +1,406 @@ +:allow_comments: False + .. _doc_docs_changelog: Documentation changelog ======================= -The documentation is continually being improved. The release of version 3.2 -includes many new tutorials, many fixes and updates for old tutorials, and many updates -to the :ref:`class reference `. Below is a list of new tutorials -added since version 3.1. +The documentation is continually being improved. New releases +include new pages, fixes and updates to existing pages, and many updates +to the :ref:`class reference `. Below is a list of new pages +added since version 3.0. + +.. note:: + + This document only contains new pages, so not all changes are reflected. + Many pages have been substantially updated but are not reflected in this document. + +New pages since version 4.4 +--------------------------- + +Editor +~~~~~~ + +- :ref:`doc_engine_compilation_configuration_editor` + +GDExtension +~~~~~~~~~~~ + +- :ref:`doc_gdextension_c_example` + +Migrating +~~~~~~~~~ + +- :ref:`doc_upgrading_to_godot_4.5` + + +Scripting +~~~~~~~~~ + +- :ref:`doc_logging` + +New pages since version 4.3 +--------------------------- + +2D +~~ + +- :ref:`doc_introduction_to_2d` + +3D +~~ + +- :ref:`doc_spring_arm` + +Debug +~~~~~ + +- :ref:`doc_output_panel` + +Editor +~~~~~~ + +- :ref:`doc_using_the_xr_editor` + +Migrating +~~~~~~~~~ + +- :ref:`doc_upgrading_to_godot_4.4` + +Performance +~~~~~~~~~~~ + +- :ref:`doc_pipeline_compilations` + +Physics +~~~~~~~ + +- :ref:`doc_physics_interpolation` +- :ref:`doc_physics_interpolation_quick_start_guide` +- :ref:`doc_physics_interpolation_introduction` +- :ref:`doc_using_physics_interpolation` +- :ref:`doc_advanced_physics_interpolation` +- :ref:`doc_2d_and_3d_physics_interpolation` + +Rendering +~~~~~~~~~ + +- :ref:`doc_renderers` + +Shaders +~~~~~~~ + +- :ref:`doc_shader_functions` + +New pages since version 4.2 +--------------------------- -.. note:: This document only contains new tutorials so not all changes are reflected, - many tutorials have been substantially updated but are not reflected in this document. +About +~~~~~ -New tutorials since version 3.1 -------------------------------- +- :ref:`doc_system_requirements` + +2D +~~ + +- :ref:`doc_2d_parallax` + +Contributing +~~~~~~~~~~~~ + +- :ref:`doc_handling_compatibility_breakages` + +GDExtension +~~~~~~~~~~~ + +- :ref:`doc_gdextension_file` +- :ref:`doc_godot_cpp_docs_system` + +Migrating +~~~~~~~~~ + +- :ref:`doc_upgrading_to_godot_4.3` + +Rendering +~~~~~~~~~ + +- :ref:`doc_compositor` + +XR +~~ + +- :ref:`doc_a_better_xr_start_script` +- :ref:`doc_openxr_passthrough` +- :ref:`doc_xr_next_steps` +- :ref:`doc_openxr_settings` +- :ref:`doc_openxr_composition_layers` +- :ref:`doc_openxr_body_tracking` + + +New pages since version 4.1 +--------------------------- + +C# +~~ + +- :ref:`doc_c_sharp_diagnostics` + +Development +~~~~~~~~~~~ + +- :ref:`doc_2d_coordinate_systems` + +Migrating +~~~~~~~~~ + +- :ref:`doc_upgrading_to_godot_4.2` + +I/O +~~~ + +- :ref:`doc_runtime_loading_and_saving` + +Platform-specific +~~~~~~~~~~~~~~~~~ + +- :ref:`doc_android_library` + +New pages since version 4.0 +--------------------------- + +Development +~~~~~~~~~~~ + +- :ref:`doc_internal_rendering_architecture` +- :ref:`doc_using_sanitizers` + +Migrating +~~~~~~~~~ + +- :ref:`doc_upgrading_to_godot_4.1` + +Physics +~~~~~~~ + +- :ref:`doc_troubleshooting_physics_issues` + +New pages since version 3.6 +--------------------------- + +2D +~~ + +- :ref:`doc_2d_antialiasing` + +3D +~~ + +- :ref:`doc_3d_antialiasing` +- :ref:`doc_faking_global_illumination` +- :ref:`doc_introduction_to_global_illumination` +- :ref:`doc_mesh_lod` +- :ref:`doc_occlusion_culling` +- :ref:`doc_using_sdfgi` +- :ref:`doc_using_decals` +- :ref:`doc_visibility_ranges` +- :ref:`doc_volumetric_fog` +- :ref:`doc_variable_rate_shading` +- :ref:`doc_physical_light_and_camera_units` + +Animation +~~~~~~~~~ + +- :ref:`doc_creating_movies` + +Assets pipeline +~~~~~~~~~~~~~~~ + +- :ref:`doc_retargeting_3d_skeletons` + +Development +~~~~~~~~~~~ + +- :ref:`doc_custom_platform_ports` + +Migrating +~~~~~~~~~ + +- :ref:`doc_upgrading_to_godot_4` + +Physics +~~~~~~~ + +- :ref:`doc_large_world_coordinates` + +Scripting +~~~~~~~~~ + +- :ref:`doc_custom_performance_monitors` +- :ref:`doc_c_sharp_collections` +- :ref:`doc_c_sharp_global_classes` +- :ref:`doc_c_sharp_variant` + +Shaders +~~~~~~~ + +- :ref:`doc_compute_shaders` + +XR +~~ + +- :ref:`doc_introducing_xr_tools` +- :ref:`doc_xr_action_map` +- :ref:`doc_deploying_to_android` + +New pages since version 3.5 +--------------------------- + +None. + +New pages since version 3.4 +--------------------------- + +3D +~~ + +- :ref:`doc_3d_text` + +Animation +~~~~~~~~~ + +- :ref:`doc_playing_videos` + +Editor +~~~~~~ + +- :ref:`doc_managing_editor_features` + +New pages since version 3.3 +--------------------------- + +GDScript +~~~~~~~~ + +- :ref:`doc_gdscript_documentation_comments` + +New pages since version 3.2 +--------------------------- + +3D +~~ + +- :ref:`doc_3d_rendering_limitations` + +About +~~~~~ + +- :ref:`doc_troubleshooting` +- :ref:`doc_list_of_features` +- :ref:`doc_release_policy` + +Best practices +~~~~~~~~~~~~~~ + +- :ref:`doc_version_control_systems` + +Development +~~~~~~~~~~~ + +- :ref:`doc_common_engine_methods_and_macros_error_macros` +- :ref:`doc_vulkan_validation_layers` +- :ref:`doc_gdscript_grammar` +- Configuring an IDE: :ref:`doc_configuring_an_ide_code_blocks` + +Editor +~~~~~~ + +- :ref:`doc_default_key_mapping` +- :ref:`doc_using_the_web_editor` + +Export +~~~~~~ + +- :ref:`doc_exporting_for_dedicated_servers` + +Input +~~~~~ + +- :ref:`doc_controllers_gamepads_joysticks` + +Math +~~~~ + +- :ref:`doc_random_number_generation` + +Platform-specific +~~~~~~~~~~~~~~~~~ + +- :ref:`doc_plugins_for_ios` +- :ref:`doc_ios_plugin` +- :ref:`doc_html5_shell_classref` + +Physics +~~~~~~~ + +- :ref:`doc_collision_shapes_2d` +- :ref:`doc_collision_shapes_3d` + +Shaders +~~~~~~~ + +- :ref:`doc_shaders_style_guide` + +Scripting +~~~~~~~~~ + +- :ref:`doc_debugger_panel` +- :ref:`doc_creating_script_templates` +- :ref:`doc_evaluating_expressions` +- :ref:`doc_what_is_gdextension` +- :ref:`doc_gdscript_warning_system` (split from :ref:`doc_gdscript_static_typing`) + +User Interface (UI) +~~~~~~~~~~~~~~~~~~~ + +- :ref:`doc_control_node_gallery` + +New pages since version 3.1 +--------------------------- Project workflow -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ -- :ref:`doc_android_custom_build` +- :ref:`doc_android_gradle_build` 2D -^^ +~~ - :ref:`doc_2d_sprite_animation` Audio -^^^^^ +~~~~~ - :ref:`doc_recording_with_microphone` - :ref:`doc_sync_with_audio` Math -^^^^ +~~~~ - :ref:`doc_beziers_and_curves` - :ref:`doc_interpolation` Inputs -^^^^^^ +~~~~~~ - :ref:`doc_input_examples` Internationalization -^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~ - :ref:`doc_localization_using_gettext` Shading -^^^^^^^ +~~~~~~~ - Your First Shader Series: - :ref:`doc_introduction_to_shaders` @@ -57,65 +410,59 @@ Shading - :ref:`doc_visual_shaders` Networking -^^^^^^^^^^ +~~~~~~~~~~ - :ref:`doc_webrtc` -VR -^^ - -- :ref:`doc_vr_starter_tutorial_part_one` -- :ref:`doc_vr_starter_tutorial_part_two` - Plugins -^^^^^^^ +~~~~~~~ - :ref:`doc_android_plugin` - :ref:`doc_inspector_plugins` - :ref:`doc_visual_shader_plugins` Multi-threading -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ - :ref:`doc_using_multiple_threads` Creating content -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ Procedural geometry series: - :ref:`Procedural geometry ` - :ref:`doc_arraymesh` - :ref:`doc_surfacetool` - :ref:`doc_meshdatatool` - - :ref:`doc_immediategeometry` + - :ref:`doc_immediatemesh` Optimization -^^^^^^^^^^^^ +~~~~~~~~~~~~ - :ref:`doc_using_multimesh` - :ref:`doc_using_servers` Legal -^^^^^ +~~~~~ - :ref:`doc_complying_with_licenses` -New tutorials since version 3.0 -------------------------------- +New pages since version 3.0 +--------------------------- Step by step -^^^^^^^^^^^^ +~~~~~~~~~~~~ - :ref:`doc_signals` -- :ref:`doc_exporting_basics` +- Exporting Scripting -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_gdscript_static_typing` Project workflow -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ Best Practices: @@ -131,43 +478,43 @@ Best Practices: - :ref:`doc_logic_preferences` 2D -^^ +~~ - :ref:`doc_2d_lights_and_shadows` - :ref:`doc_2d_meshes` 3D -^^ +~~ - :ref:`doc_csg_tools` - :ref:`doc_animating_thousands_of_fish` - :ref:`doc_controlling_thousands_of_fish` Physics -^^^^^^^ +~~~~~~~ - :ref:`doc_ragdoll_system` - :ref:`doc_soft_body` Animation -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_2d_skeletons` - :ref:`doc_animation_tree` GUI -^^^ +~~~ - :ref:`doc_gui_containers` Viewports -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_viewport_as_texture` - :ref:`doc_custom_postprocessing` Shading -^^^^^^^ +~~~~~~~ - :ref:`doc_converting_glsl_to_godot_shaders` - :ref:`doc_advanced_postprocessing` @@ -181,41 +528,40 @@ Shading Reference: - :ref:`doc_particle_shader` Plugins -^^^^^^^ +~~~~~~~ - :ref:`doc_making_main_screen_plugins` -- :ref:`doc_spatial_gizmo_plugins` +- :ref:`doc_3d_gizmo_plugins` Platform-specific -^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~ - :ref:`doc_customizing_html5_shell` Multi-threading -^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~ - :ref:`doc_thread_safe_apis` Creating content -^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~ - :ref:`doc_making_trees` Miscellaneous -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ - :ref:`doc_jitter_stutter` - :ref:`doc_running_code_in_the_editor` - :ref:`doc_change_scenes_manually` -- :ref:`doc_gles2_gles3_differences` Compiling -^^^^^^^^^ +~~~~~~~~~ - :ref:`doc_optimizing_for_size` - :ref:`doc_compiling_with_script_encryption_key` Engine development -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ - :ref:`doc_binding_to_external_libraries` diff --git a/about/faq.rst b/about/faq.rst index b459ef7d2b7..1b8a76a3ab2 100644 --- a/about/faq.rst +++ b/about/faq.rst @@ -1,3 +1,5 @@ +:allow_comments: False + .. meta:: :keywords: FAQ @@ -9,23 +11,27 @@ Frequently asked questions What can I do with Godot? How much does it cost? What are the license terms? ---------------------------------------------------------------------------- -Godot is `Free and Open-Source Software `_ available under the `OSI-approved `_ MIT license. This means it is free as in "free speech" as well as in "free beer." +Godot is `Free and open source Software `_ +available under the `OSI-approved `_ MIT license. This means it is +free as in "free speech" as well as in "free beer." In short: -* You are free to download and use Godot for any purpose, personal, non-profit, commercial, or otherwise. -* You are free to modify, distribute, redistribute, and remix Godot to your heart's content, for any reason, both non-commercially and commercially. +* You are free to download and use Godot for any purpose: personal, non-profit, commercial, or otherwise. +* You are free to modify, distribute, redistribute, and remix Godot to your heart's content, for any reason, + both non-commercially and commercially. -All the contents of this accompanying documentation are published under -the permissive Creative Commons Attribution 3.0 (`CC-BY 3.0 `_) license, with attribution +All the contents of this accompanying documentation are published under the permissive Creative Commons +Attribution 3.0 (`CC BY 3.0 `_) license, with attribution to "Juan Linietsky, Ariel Manzur and the Godot Engine community." Logos and icons are generally under the same Creative Commons license. Note that some third-party libraries included with Godot's source code may have different licenses. -For full details, look at the `COPYRIGHT.txt `_ as well -as the `LICENSE.txt `_ and `LOGO_LICENSE.txt `_ files +For full details, look at the `COPYRIGHT.txt `_ +as well as the `LICENSE.txt `_ +and `LOGO_LICENSE.txt `_ files in the Godot repository. Also, see `the license page on the Godot website `_. @@ -38,10 +44,12 @@ Which platforms are supported by Godot? * Windows * macOS * Linux, \*BSD +* Android (experimental) +* `Web `__ (experimental) **For exporting your games:** -* Windows (and UWP) +* Windows * macOS * Linux, \*BSD * Android @@ -49,24 +57,31 @@ Which platforms are supported by Godot? * Web Both 32- and 64-bit binaries are supported where it makes sense, with 64 -being the default. +being the default. Official macOS builds support Apple Silicon natively as well as x86_64. Some users also report building and using Godot successfully on ARM-based systems with Linux, like the Raspberry Pi. -Additionally, there is some unofficial third-party work being done on building -for some consoles. However, none of this is included in the default build -scripts or export templates at this time. +The Godot team can't provide an open source console export due to the licensing +terms imposed by console manufacturers. Regardless of the engine you use, +though, releasing games on consoles is always a lot of work. You can read more +about :ref:`doc_consoles`. For more on this, see the sections on :ref:`exporting ` and :ref:`compiling Godot yourself `. +.. note:: + + Godot 3 also had support for Universal Windows Platform (UWP). This platform + port was removed in Godot 4 due to lack of maintenance, and it being + deprecated by Microsoft. It is still available in the current stable release + of Godot 3 for interested users. + Which programming languages are supported in Godot? --------------------------------------------------- -The officially supported languages for Godot are GDScript, Visual Scripting, -C#, and C++. See the subcategories for each language in the -:ref:`scripting ` section. +The officially supported languages for Godot are GDScript, C#, and C++. +See the subcategories for each language in the :ref:`scripting ` section. If you are just starting out with either Godot or game development in general, GDScript is the recommended language to learn and use since it is native to Godot. @@ -75,16 +90,17 @@ the long run, for prototyping, developing Minimum Viable Products (MVPs), and focusing on Time-To-Market (TTM), GDScript will provide a fast, friendly, and capable way of developing your games. -Note that C# support is still relatively new, and as such, you may encounter some -issues along the way. Our friendly and hard-working development community is always -ready to tackle new problems as they arise, but since this is an open-source project, -we recommend that you first do some due diligence yourself. Searching through -discussions on `open issues `_ is a -great way to start your troubleshooting. - -As for new languages, support is possible via third parties using the GDNative / -NativeScript / PluginScript facilities. (See the question about plugins below.) -Work is currently underway, for example, on unofficial bindings for Godot +Note that C# support is still relatively new, and as such, you may encounter +some issues along the way. C# support is also currently missing on the web +platform. Our friendly and hard-working development community is always +ready to tackle new problems as they arise, but since this is an open source +project, we recommend that you first do some due diligence yourself. Searching +through discussions on +`open issues `__ +is a great way to start your troubleshooting. + +As for new languages, support is possible via third parties with GDExtensions. (See the question +about plugins below). Work is currently underway, for example, on unofficial bindings for Godot to `Python `_ and `Nim `_. .. _doc_faq_what_is_gdscript: @@ -99,25 +115,24 @@ If you've ever written anything in a language like Python before, then you'll fe right at home. For examples and a complete overview of the power GDScript offers you, check out the :ref:`GDScript scripting guide `. -There are several reasons to use GDScript--especially when you are prototyping, in -alpha/beta stages of your project, or are not creating the next AAA title--but the -most salient reason is the overall **reduction of complexity.** +There are several reasons to use GDScript, but the most salient reason is the overall +**reduction of complexity**. The original intent of creating a tightly integrated, custom scripting language for Godot was two-fold: first, it reduces the amount of time necessary to get up and running with Godot, giving developers a rapid way of exposing themselves to the engine with a focus on productivity; second, it reduces the overall burden of maintenance, attenuates the dimensionality of issues, and allows the developers of the engine to focus on squashing -bugs and improving features related to the engine core--rather than spending a lot of time +bugs and improving features related to the engine core, rather than spending a lot of time trying to get a small set of incremental features working across a large set of languages. -Since Godot is an open-source project, it was imperative from the start to prioritize a +Since Godot is an open source project, it was imperative from the start to prioritize a more integrated and seamless experience over attracting additional users by supporting -more familiar programming languages--especially when supporting those more familiar +more familiar programming languages, especially when supporting those more familiar languages would result in a worse experience. We understand if you would rather use another language in Godot (see the list of supported options above). That being said, if you haven't given GDScript a try, try it for **three days**. Just like Godot, -once you see how powerful it is and rapid your development becomes, we think GDScript +once you see how powerful it is and how rapid your development becomes, we think GDScript will grow on you. More information about getting comfortable with GDScript or dynamically typed @@ -127,10 +142,10 @@ What were the motivations behind creating GDScript? --------------------------------------------------- In the early days, the engine used the `Lua `__ scripting -language. Lua can be fast thanks to LuaJIT, but creating bindings to an object -oriented system (by using fallbacks) was complex and slow and took an enormous +language. Lua can be fast thanks to LuaJIT, but creating bindings to an object-oriented +system (by using fallbacks) was complex and slow and took an enormous amount of code. After some experiments with `Python `__, -it also proved difficult to embed. +that also proved difficult to embed. The main reasons for creating a custom scripting language for Godot were: @@ -138,86 +153,188 @@ The main reasons for creating a custom scripting language for Godot were: (Lua, Python, Squirrel, JavaScript, ActionScript, etc.). 2. Poor class-extending support in most script VMs, and adapting to the way Godot works is highly inefficient (Lua, Python, JavaScript). -3. Many existing languages have horrible interfaces for binding to C++, resulting in large amount of - code, bugs, bottlenecks, and general inefficiency (Lua, Python, - Squirrel, JavaScript, etc.) We wanted to focus on a great engine, not a great amount of integrations. -4. No native vector types (vector3, matrix4, etc.), resulting in highly +3. Many existing languages have horrible interfaces for binding to C++, resulting in a + large amount of code, bugs, bottlenecks, and general inefficiency (Lua, Python, + Squirrel, JavaScript, etc.). We wanted to focus on a great engine, not a great number + of integrations. +4. No native vector types (Vector3, Transform3D, etc.), resulting in highly reduced performance when using custom types (Lua, Python, Squirrel, JavaScript, ActionScript, etc.). 5. Garbage collector results in stalls or unnecessarily large memory usage (Lua, Python, JavaScript, ActionScript, etc.). -6. Difficulty to integrate with the code editor for providing code - completion, live editing, etc. (all of them). This is well-supported - by GDScript. +6. Difficulty integrating with the code editor for providing code + completion, live editing, etc. (all of them). GDScript was designed to curtail the issues above, and more. -What 3D model formats does Godot support? ------------------------------------------ +.. _doc_faq_which_programming_language_is_fastest: -Godot supports the following formats: +Which programming language is fastest? +-------------------------------------- -- glTF 2.0 *(recommended)* -- Collada -- OBJ -- FBX (static meshes only) +In most games, the *scripting language* itself is not the cause of performance +problems. Instead, performance is slowed by inefficient algorithms (which are +slow in all languages), by GPU performance, or by the common C++ engine code +like physics or navigation. All languages supported by Godot are fast enough for +general-purpose scripting. You should choose a language based on other factors, +like ease-of-use, familiarity, platform support, or language features. + +In general, the performance of C# and GDScript is within the same order of +magnitude, and C++ is faster than both. + +Comparing GDScript performance to C# is tricky, since C# can be faster in some +specific cases. The C# *language* itself tends to be faster than GDScript, which +means that C# can be faster in situations with few calls to Godot engine code. +However, C# can be slower than GDScript when making many Godot API calls, due +to the cost of *marshalling*. C#'s performance can also be brought down by garbage +collection which occurs at random and unpredictable moments. This can result in +stuttering issues in complex projects, and is not exclusive to Godot. + +C++, using :ref:`GDExtension `, will almost always be +faster than either C# or GDScript. However, C++ is less easy to use than C# or +GDScript, and is slower to develop with. + +You can also use multiple languages within a single project, with +:ref:`cross-language scripting `, or by using +GDExtension and scripting languages together. Be aware that doing so comes with +its own complications. -FBX support is the fruit of reverse engineering via the Open Asset Import library. -However, FBX is proprietary so we recommend using other formats listed above, -if suitable for your workflow. +What 3D model formats does Godot support? +----------------------------------------- -You can find more detailed information on supported formats, and how to export -and import them for Godot :ref:`here `. +You can find detailed information on supported formats, how to export them from +your 3D modeling software, and how to import them for Godot in the +:ref:`doc_importing_3d_scenes` documentation. Will [insert closed SDK such as FMOD, GameWorks, etc.] be supported in Godot? ----------------------------------------------------------------------------- -The aim of Godot is to create a free and open-source MIT-licensed engine that +The aim of Godot is to create a free and open source MIT-licensed engine that is modular and extendable. There are no plans for the core engine development community to support any third-party, closed-source/proprietary SDKs, as integrating with these would go against Godot's ethos. -That said, because Godot is open-source and modular, nothing prevents you or +That said, because Godot is open source and modular, nothing prevents you or anyone else interested in adding those libraries as a module and shipping your -game with them--as either open- or closed-source. +game with them, as either open- or closed-source. To see how support for your SDK of choice could still be provided, look at the Plugins question below. If you know of a third-party SDK that is not supported by Godot but that offers -free and open-source integration, consider starting the integration work yourself. +free and open source integration, consider starting the integration work yourself. Godot is not owned by one person; it belongs to the community, and it grows along with ambitious community contributors like you. -Why does Godot use Vulkan or OpenGL instead of Direct3D? --------------------------------------------------------- +How can I extend Godot? +----------------------- + +For extending Godot, like creating Godot Editor plugins or adding support +for additional languages, take a look at :ref:`EditorPlugins ` +and tool scripts. + +Also, see the official blog post on GDExtension, a way to develop native extensions for Godot: + +* `Introducing GDNative's successor, GDExtension `_ + +You can also take a look at the GDScript implementation, the Godot modules, +as well as the `Jolt physics engine integration `__ +for Godot. This would be a good starting point to see how another +third-party library integrates with Godot. + +How do I install the Godot editor on my system (for desktop integration)? +------------------------------------------------------------------------- + +Since you don't need to actually install Godot on your system to run it, +this means desktop integration is not performed automatically. +There are two ways to overcome this. You can install Godot from +`Steam `__ (all platforms), +`Scoop `__ (Windows), `Homebrew `__ (macOS) +or `Flathub `__ (Linux). +This will automatically perform the required steps for desktop integration. + +Alternatively, you can manually perform the steps that an installer would do for you: + +Windows +~~~~~~~ + +- Move the Godot executable to a stable location (i.e. outside of your Downloads folder), + so you don't accidentally move it and break the shortcut in the future. +- Right-click the Godot executable and choose **Create Shortcut**. +- Move the created shortcut to ``%APPDATA%\Microsoft\Windows\Start Menu\Programs``. + This is the user-wide location for shortcuts that will appear in the Start menu. + You can also pin Godot in the task bar by right-clicking the executable and choosing + **Pin to Task Bar**. + +macOS +~~~~~ + +Drag the extracted Godot application to ``/Applications/Godot.app``, then drag it +to the Dock if desired. Spotlight will be able to find Godot as long as it's in +``/Applications`` or ``~/Applications``. + +Linux +~~~~~ + +- Move the Godot binary to a stable location (i.e. outside of your Downloads folder), + so you don't accidentally move it and break the shortcut in the future. +- Rename and move the Godot binary to a location present in your ``PATH`` environment variable. + This is typically ``/usr/local/bin/godot`` or ``/usr/bin/godot``. + Doing this requires administrator privileges, + but this also allows you to + :ref:`run the Godot editor from a terminal ` by entering ``godot``. + + - If you cannot move the Godot editor binary to a protected location, you can + keep the binary somewhere in your home directory, and modify the ``Path=`` + line in the ``.desktop`` file linked below to contain the full *absolute* path + to the Godot binary. + +- Save `this .desktop file `__ + to ``$HOME/.local/share/applications/``. If you have administrator privileges, + you can also save the ``.desktop`` file to ``/usr/local/share/applications`` + to make the shortcut available for all users. + +Is the Godot editor a portable application? +------------------------------------------- + +In its default configuration, Godot is *semi-portable*. Its executable can run +from any location (including non-writable locations) and never requires +administrator privileges. + +However, configuration files will be written to the user-wide configuration or +data directory. This is usually a good approach, but this means configuration files +will not carry across machines if you copy the folder containing the Godot executable. +See :ref:`doc_data_paths` for more information. + +If *true* portable operation is desired (e.g. for use on a USB stick), +follow the steps in :ref:`doc_data_paths_self_contained_mode`. + +Why does Godot prioritize Vulkan and OpenGL over Direct3D? +---------------------------------------------------------- Godot aims for cross-platform compatibility and open standards first and foremost. OpenGL and Vulkan are the technologies that are both open and -available (nearly) on all platforms. Thanks to this design decision, a project +available on (nearly) all platforms. Thanks to this design decision, a project developed with Godot on Windows will run out of the box on Linux, macOS, and more. -Since Godot only has a few people working on its renderer, we would prefer -having fewer rendering backends to maintain. On top of that, using a single API -on all platforms allows for greater consistency with fewer platform-specific -issues. - -In the long term, we may develop a Direct3D 12 renderer for Godot (mainly for -the Xbox's purposes), but Vulkan and OpenGL will remain the default rendering -backends on all platforms, including Windows. +While Vulkan and OpenGL remain our primary focus for their open standard and +cross-platform benefits, Godot 4.3 introduced experimental support for Direct3D 12. +This addition aims to enhance performance and compatibility on platforms where +Direct3D 12 is prevalent, such as Windows and Xbox. However, Vulkan and OpenGL +will continue as the default rendering drivers on all platforms, including Windows. Why does Godot aim to keep its core feature set small? ------------------------------------------------------ Godot intentionally does not include features that can be implemented by add-ons -unless they are used very often. One example of this would be advanced -artificial intelligence functionality. +unless they are used very often. One example of something not used often is +advanced artificial intelligence functionality. There are several reasons for this: - **Code maintenance and surface for bugs.** Every time we accept new code in - the Godot repository, existing contributors often take the reponsibility of + the Godot repository, existing contributors often take the responsibility of maintaining it. Some contributors don't always stick around after getting their code merged, which can make it difficult for us to maintain the code in question. This can lead to poorly maintained features with bugs that are never @@ -236,16 +353,16 @@ There are several reasons for this: - **Keeping the binary size small for export templates.** This directly impacts the size of projects exported with Godot. On mobile and web platforms, keeping - file sizes low is primordial to ensure fast installation and loading on + file sizes low is important to ensure fast installation and loading on underpowered devices. Again, there are many countries where high-speed Internet is not readily available. To add to this, strict data usage caps are often in effect in those countries. For all the reasons above, we have to be selective of what we can accept as core functionality in Godot. This is why we are aiming to move some core -functionality to officially supported add-ons in future versions of Godot. In -terms of binary size, this also has the advance of making you pay only for what -you actually use in your project. (In the meantime, you can +functionality to officially supported add-ons in future versions of Godot. +In terms of binary size, this also has the advantage of making you pay only for +what you actually use in your project. (In the meantime, you can :ref:`compile custom export templates with unused features disabled ` to optimize the distribution size of your project.) @@ -260,20 +377,21 @@ point and only for Apple devices, but then several Android and Apple devices with different resolutions and aspect ratios were created, with a very wide range of sizes and DPIs. -The most common and proper way to achieve this is to, instead, use a single -base resolution for the game and only handle different screen aspect ratios. -This is mostly needed for 2D, as in 3D it's just a matter of Camera XFov or YFov. +The most common and proper way to achieve this is to, instead, use a single base +resolution for the game and only handle different screen aspect ratios. This is +mostly needed for 2D, as in 3D, it's just a matter of camera vertical or +horizontal FOV. 1. Choose a single base resolution for your game. Even if there are - devices that go up to 2K and devices that go down to 400p, regular + devices that go up to 1440p and devices that go down to 400p, regular hardware scaling in your device will take care of this at little or - no performance cost. Most common choices are either near 1080p + no performance cost. The most common choices are either near 1080p (1920x1080) or 720p (1280x720). Keep in mind the higher the resolution, the larger your assets, the more memory they will take and the longer the time it will take for loading. -2. Use the stretch options in Godot; 2D stretching while keeping aspect - ratios works best. Check the :ref:`doc_multiple_resolutions` tutorial +2. Use the stretch options in Godot; canvas items stretching while keeping + aspect ratios works best. Check the :ref:`doc_multiple_resolutions` tutorial on how to achieve this. 3. Determine a minimum resolution and then decide if you want your game @@ -287,79 +405,80 @@ This is mostly needed for 2D, as in 3D it's just a matter of Camera XFov or YFov And that's it! Your game should work in multiple resolutions. -If there is a desire to make your game also work on ancient -devices with tiny screens (fewer than 300 pixels in width), you can use -the export option to shrink images, and set that build to be used for -certain screen sizes in the App Store or Google Play. +When is the next release of Godot out? +-------------------------------------- -How can I extend Godot? ------------------------ +When it's ready! See :ref:`doc_release_policy_when_is_next_release_out` for more +information. -For extending Godot, like creating Godot Editor plugins or adding support -for additional languages, take a look at :ref:`EditorPlugins ` -and tool scripts. +Which Godot version should I use for a new project? +--------------------------------------------------- -Also, see the official blog posts on these topics: +We recommend using Godot 4.x for new projects, but depending on the feature set +you need, it may be better to use 3.x instead. See +:ref:`doc_release_policy_which_version_should_i_use` for more information. -* `A look at the GDNative architecture `_ -* `GDNative is here! `_ +Should I upgrade my project to use new Godot versions? +------------------------------------------------------ -You can also take a look at the GDScript implementation, the Godot modules, -as well as the `unofficial Python support `_ for Godot. -This would be a good starting point to see how another third-party library -integrates with Godot. +Some new versions are safer to upgrade to than others. In general, whether you +should upgrade depends on your project's circumstances. See +:ref:`doc_release_policy_should_i_upgrade_my_project` for more information. -When is the next release of Godot out? --------------------------------------- +Should I use the Forward+, Mobile, or Compatibility renderer? +------------------------------------------------------------- -When it's ready! See :ref:`doc_release_policy_when_is_next_release_out` for more -information. +You can find a detailed comparison of the renderers in :ref:`doc_renderers`. I would like to contribute! How can I get started? -------------------------------------------------- -Awesome! As an open-source project, Godot thrives off of the innovation and -ambition of developers like you. +Awesome! As an open source project, Godot thrives off of the innovation and +the ambition of developers like you. + +The best way to start contributing to Godot is by using it and reporting +any `issues `_ that you might experience. +A good bug report with clear reproduction steps helps your fellow contributors +fix bugs quickly and efficiently. You can also report issues you find in the +`online documentation `_. + +If you feel ready to submit your first PR, pick any issue that resonates with you from +one of the links above and try your hand at fixing it. You will need to learn how to +compile the engine from sources, or how to build the documentation. You also need to +get familiar with Git, a version control system that Godot developers use. -The first place to get started is in the `issues `_. -Find an issue that resonates with you, then proceed to the `How to Contribute `_ -guide to learn how to fork, modify, and submit a Pull Request (PR) with your changes. +We explain how to work with the engine source, how to edit the documentation, and +what other ways to contribute are there in our `documentation for contributors `__. I have a great idea for Godot. How can I share it? -------------------------------------------------- -It might be tempting to want to bring ideas to Godot, like ones that -result in massive core changes, some sort of mimicry of what another -game engine does, or alternative workflows that you'd like built into -the editor. These are great, and we are thankful to have such motivated -people want to contribute, but Godot's focus is and always will be the -core functionality as outlined in the `Roadmap `_, -`squashing bugs and addressing issues `_, -and conversations between Godot community members. - -Most developers in the Godot community will be more interested to learn -about things like: - -- Your experience using the software and the problems you have (we - care about this much more than ideas on how to improve it). -- The features you would like to see implemented because you need them - for your project. -- The concepts that were difficult to understand while learning the software. -- The parts of your workflow you would like to see optimized. -- Parts where you missed clear tutorials or where the documentation wasn't clear. - -Please don't feel like your ideas for Godot are unwelcome. Instead, -try to reformulate them as a problem first, so developers and the community -have a functional foundation to ground your ideas on. - -A good way to approach sharing your ideas and problems with the community -is as a set of user stories. Explain what you are trying to do, what behavior -you expect to happen, and then what behavior actually happened. Framing problems -and ideas this way will help the whole community stay focused on improving -developer experiences as a whole. - -Bonus points for bringing screenshots, concrete numbers, test cases, or example -projects (if applicable). +We are always looking for suggestions about how to improve the engine. User feedback +is the main driving force behind our decision-making process, and limitations that +you might face while working on your project are a great data point for us when considering +engine enhancements. + +If you experience a usability problem or are missing a feature in the current version of +Godot, start by discussing it with our `community `_. +There may be other, perhaps better, ways to achieve the desired result that community members +could suggest. And you can learn if other users experience the same issue, and figure out +a good solution together. + +If you come up with a well-defined idea for the engine, feel free to open a +`proposal issue `_. +Try to be specific and concrete while describing your problem and your proposed +solution — only actionable proposals can be considered. It is not required, but +if you want to implement it yourself, that's always appreciated! + +If you only have a general idea without specific details, you can open a +`proposal discussion `_. +These can be anything you want, and allow for a free-form discussion in search of +a solution. Once you find one, a proposal issue can be opened. + +Please, read the `readme `_ +document before creating a proposal to learn more about the process. + +.. _doc_faq_non_game_applications: Is it possible to use Godot to create non-game applications? ------------------------------------------------------------ @@ -371,13 +490,12 @@ When creating a non-game application, make sure to enable :ref:`low-processor mode ` in the Project Settings to decrease CPU and GPU usage. -That said, we wouldn't recommend using Godot to create a *mobile* application -since low-processor mode isn't supported on mobile platforms yet. - Check out `Material Maker `__ and `Pixelorama `__ for examples of open source applications made with Godot. +.. _doc_faq_use_godot_as_library: + Is it possible to use Godot as a library? ----------------------------------------- @@ -391,18 +509,77 @@ engine instead. Keep in mind rendering engines usually have smaller communities compared to Godot. This will make it more difficult to find answers to your questions. -Why does Godot not use STL (Standard Template Library) ------------------------------------------------------- - -Like many other libraries (Qt as an example), Godot does not make use of -STL. We believe STL is a great general purpose library, but we had special -requirements for Godot. - -* STL templates create very large symbols, which results in huge debug binaries. We use few templates with very short names instead. -* Most of our containers cater to special needs, like Vector, which uses copy on write and we use to pass data around, or the RID system, which requires O(1) access time for performance. Likewise, our hash map implementations are designed to integrate seamlessly with internal engine types. +What user interface toolkit does Godot use? +------------------------------------------- + +Godot does not use a standard :abbr:`GUI (Graphical User Interface)` toolkit +like GTK, Qt or wxWidgets. Instead, Godot uses its own user interface toolkit, +rendered using OpenGL ES or Vulkan. This toolkit is exposed in the form of +Control nodes, which are used to render the editor (which is written in C++). +These Control nodes can also be used in projects from any scripting language +supported by Godot. + +This custom toolkit makes it possible to benefit from hardware acceleration and +have a consistent appearance across all platforms. On top of that, it doesn't +have to deal with the LGPL licensing caveats that come with GTK or Qt. Lastly, +this means Godot is "eating its own dog food" since the editor itself is one of +the most complex users of Godot's UI system. + +This custom UI toolkit :ref:`can't be used as a library `, +but you can still +:ref:`use Godot to create non-game applications by using the editor `. + +.. _doc_faq_why_scons: + +Why does Godot use the SCons build system? +------------------------------------------ + +Godot uses the `SCons `__ build system. There are no +plans to switch to a different build system in the near future. There are many +reasons why we have chosen SCons over other alternatives. For example: + +- Godot can be compiled for a dozen different platforms: all PC + platforms, all mobile platforms, many consoles, and WebAssembly. +- Developers often need to compile for several of the platforms **at + the same time**, or even different targets of the same platform. They + can't afford reconfiguring and rebuilding the project each time. + SCons can do this with no sweat, without breaking the builds. +- SCons will *never* break a build no matter how many changes, + configurations, additions, removals etc. +- Godot's build process is not simple. Several files are generated by + code (binders), others are parsed (shaders), and others need to offer + customization (:ref:`modules `). This requires + complex logic which is easier to write in an actual programming language (like Python) + rather than using a mostly macro-based language only meant for building. +- Godot's build process makes heavy use of cross-compiling tools. Each + platform has a specific detection process, and all these must be + handled as specific cases with special code written for each. + +Please try to keep an open mind and get at least a little familiar with SCons if +you are planning to build Godot yourself. + +.. _doc_faq_why_not_stl: + +Why does Godot not use STL (Standard Template Library)? +------------------------------------------------------- + +Like many other libraries (Qt as an example), Godot does not make use of STL +(with a few exceptions such as threading primitives). We believe STL is a great +general-purpose library, but we had special requirements for Godot. + +* STL templates create very large symbols, which results in huge debug binaries. We use few + templates with very short names instead. +* Most of our containers cater to special needs, like Vector, which uses copy on write and we + use to pass data around, or the RID system, which requires O(1) access time for performance. + Likewise, our hash map implementations are designed to integrate seamlessly with internal + engine types. * Our containers have memory tracking built-in, which helps better track memory usage. -* For large arrays, we use pooled memory, which can be mapped to either a preallocated buffer or virtual memory. -* We use our custom String type, as the one provided by STL is too basic and lacks proper internationalization support. +* For large arrays, we use pooled memory, which can be mapped to either a preallocated buffer + or virtual memory. +* We use our custom String type, as the one provided by STL is too basic and lacks proper + internationalization support. + +Check out :ref:`Godot's container types ` for alternatives. Why does Godot not use exceptions? ---------------------------------- @@ -412,15 +589,8 @@ situation happens, Godot will print an error (which can be traced even to script), but then it will try to recover as gracefully as possible and keep going. -Additionally, exceptions significantly increase binary size for the -executable. - -Why does Godot not enforce RTTI? --------------------------------- - -Godot provides its own type-casting system, which can optionally use RTTI -internally. Disabling RTTI in Godot means considerably smaller binary sizes can -be achieved, at a little performance cost. +Additionally, exceptions significantly increase the binary size for the +executable and result in increased compile times. Does Godot use an ECS (Entity Component System)? ------------------------------------------------ @@ -431,36 +601,35 @@ resulted in better usability while still being fast enough for most use cases. That said, nothing prevents you from making use of composition in your project by creating child Nodes with individual scripts. These nodes can then be added and -removed at run-time to dynamically add and remove behaviors. +removed at runtime to dynamically add and remove behaviors. More information about Godot's design choices can be found in `this article `__. -Why does Godot not force users to implement DoD (Data oriented Design)? +Why does Godot not force users to implement DOD (Data-Oriented Design)? ----------------------------------------------------------------------- -While Godot internally for a lot of the heavy performance tasks attempts -to use cache coherency as well as possible, we believe most users don't -really need to be forced to use DoD practices. +While Godot internally attempts to use cache coherency as much as possible, +we believe users don't need to be forced to use DOD practices. -DoD is mostly a cache coherency optimization that can only gain you +DOD is mostly a cache coherency optimization that can only provide significant performance improvements when dealing with dozens of -thousands of objects (which are processed every frame with little -modification). As in, if you are moving a few hundred sprites or enemies -per frame, DoD won't help you, and you should consider a different approach -to optimization. +thousands of objects which are processed every frame with little +modification. That is, if you are moving a few hundred sprites or enemies +per frame, DOD won't result in a meaningful improvement in performance. In +such a case, you should consider a different approach to optimization. The vast majority of games do not need this and Godot provides handy helpers to do the job for most cases when you do. -If a game that really needs to process such large amount of objects is -needed, our recommendation is to use C++ and GDNative for the high -performance parts and GDScript (or C#) for the rest of the game. +If a game needs to process such a large amount of objects, our recommendation +is to use C++ and GDExtensions for performance-heavy tasks and GDScript (or C#) +for the rest of the game. How can I support Godot development or contribute? -------------------------------------------------- -See :ref:`doc_ways_to_contribute`. +See `How to contribute `__. Who is working on Godot? How can I contact you? ----------------------------------------------- diff --git a/about/img/eol.png b/about/img/eol.png index ad9cb36e39a..d4e9206d3a9 100644 Binary files a/about/img/eol.png and b/about/img/eol.png differ diff --git a/about/img/partial.png b/about/img/partial.png index 06f8610ab70..3c540af2c0f 100644 Binary files a/about/img/partial.png and b/about/img/partial.png differ diff --git a/about/img/supported.png b/about/img/supported.png index 668711c16fd..24facbeb55c 100644 Binary files a/about/img/supported.png and b/about/img/supported.png differ diff --git a/about/img/unstable.png b/about/img/unstable.png index 6815a7332bc..dd3c0f797c1 100644 Binary files a/about/img/unstable.png and b/about/img/unstable.png differ diff --git a/about/index.rst b/about/index.rst deleted file mode 100644 index 5a3f5995992..00000000000 --- a/about/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -About -===== - -.. toctree:: - :maxdepth: 1 - :name: toc-about - - introduction - faq - troubleshooting - list_of_features - docs_changelog - release_policy - complying_with_licenses - -.. history -.. authors -.. license diff --git a/about/introduction.rst b/about/introduction.rst index d951c4cce12..06454b2072e 100644 --- a/about/introduction.rst +++ b/about/introduction.rst @@ -1,109 +1,110 @@ +:allow_comments: False + .. _doc_about_intro: Introduction ============ -:: +.. tabs:: + .. code-tab:: gdscript func _ready(): - $Label.text = "Hello world!" + print("Hello world!") + + .. code-tab:: csharp -Welcome to the official documentation of Godot Engine, the free and open source + public override void _Ready() + { + GD.Print("Hello world!"); + } + +Welcome to the official documentation of **Godot Engine**, the free and open source community-driven 2D and 3D game engine! Behind this mouthful, you will find a powerful yet user-friendly tool that you can use to develop any kind of game, for any platform and with no usage restriction whatsoever. -This page gives a broad presentation of the engine and of the contents -of this documentation, so that you know where to start if you are a beginner or -where to look if you need info on a specific feature. +This page gives a broad overview of the engine and of this documentation, +so that you know where to start if you are a beginner or +where to look if you need information on a specific feature. Before you start ---------------- The :ref:`Tutorials and resources ` page lists video tutorials contributed by the community. If you prefer video to text, -those may be worth a look. +consider checking them out. Otherwise, :ref:`Getting Started ` +is a great starting point. In case you have trouble with one of the tutorials or your project, -you can find help on the various :ref:`Community channels `, -especially the Godot Discord community and Q&A. +you can find help on the various `Community channels `_, +especially the Godot `Discord `_ community and +`Forum `_. About Godot Engine ------------------ -A game engine is a complex tool, and it is therefore difficult to present Godot -in a few words. Here's a quick synopsis, which you are free to reuse -if you need a quick writeup about Godot Engine. +A game engine is a complex tool and difficult to present in a few words. +Here's a quick synopsis, which you are free to reuse +if you need a quick write-up about Godot Engine: Godot Engine is a feature-packed, cross-platform game engine to create 2D and 3D games from a unified interface. It provides a comprehensive set of - common tools, so users can focus on making games without having to - reinvent the wheel. Games can be exported in one click to a number of - platforms, including the major desktop platforms (Linux, macOS, Windows) - as well as mobile (Android, iOS) and web-based (HTML5) platforms. - - Godot is completely free and open source under the permissive MIT - license. No strings attached, no royalties, nothing. Users' games are - theirs, down to the last line of engine code. Godot's development is fully - independent and community-driven, empowering users to help shape their - engine to match their expectations. It is supported by the `Software - Freedom Conservancy `_ not-for-profit. - -For a more in-depth view of the engine, you are encouraged to read this -documentation further, especially the :ref:`Getting Started ` series. - -About the documentation ------------------------ - -This documentation is continuously written, corrected, edited, and revamped by -members of the Godot Engine community. It is edited via text files in the -`reStructuredText `_ markup -language and then compiled into a static website/offline document using the -open source `Sphinx `_ and `ReadTheDocs -`_ tools. - -.. note:: You can contribute to Godot's documentation by opening issue tickets - or sending patches via pull requests on its GitHub - `source repository `_, or - translating it into your language on `Hosted Weblate - `_. - -All the contents are under the permissive Creative Commons Attribution 3.0 -(`CC-BY 3.0 `_) license, with -attribution to "Juan Linietsky, Ariel Manzur and the Godot Engine community". + common tools, so that users can focus on making games without having to + reinvent the wheel. Games can be exported with one click to a number of + platforms, including the major desktop platforms (Linux, macOS, Windows), + mobile platforms (Android, iOS), as well as Web-based platforms and consoles. + + Godot is completely free and open source under the :ref:`permissive MIT + license `. No strings attached, no royalties, + nothing. Users' games are theirs, down to the last line of engine code. + Godot's development is fully independent and community-driven, empowering + users to help shape their engine to match their expectations. + It is supported by the `Godot Foundation `_ + not-for-profit. + Organization of the documentation --------------------------------- -This documentation is organized in five sections with an impressively -unbalanced distribution of contents – but the way it is split up should be -relatively intuitive: +This documentation is organized into several sections: -- The :ref:`sec-general` section contains this introduction as well as - the information about the engine, its history, its licensing, authors, etc. It +- **About** contains this introduction as well as + information about the engine, its history, its licensing, authors, etc. It also contains the :ref:`doc_faq`. -- The :ref:`sec-learn` section is the *raison d'être* of this - documentation, as it contains all the necessary information on using the - engine to make games. It starts with the :ref:`Step by step - ` tutorial which should be the entry point for all - new users. -- The :ref:`sec-tutorials` section can be read as needed, +- **Getting Started** contains all necessary information on using the engine to + make games. It starts with the :ref:`doc_getting_started_intro` section which + should be the entry point for all new users. **This is the best place to start + if you're new!** +- The **Manual** can be read or referenced as needed, in any order. It contains feature-specific tutorials and documentation. -- The :ref:`sec-devel` section is intended for advanced users and contributors - to the engine development, with the information on compiling the engine, - contributing to the editor, or developing C++ modules. -- The :ref:`sec-community` section gives the information related to contributing to - the engine development and the life of its community, e.g. how to report bugs, - help with the documentation, etc. It also points to various community channels - like Godot Contributors Chat and Discord and contains a list of recommended - third-party tutorials outside of this documentation. -- Finally, the :ref:`sec-class-ref` is the documentation of the Godot API, - which is also available directly within the engine's script editor. It is - generated automatically from a file in the main source repository, therefore - the generated files of the documentation are not meant to be modified. See - :ref:`doc_class_reference_writing_guidelines` for details. - -In addition to this documentation you may also want to take a look at the +- **Engine details** contains sections intended for advanced users and contributors, + with information on compiling the engine, working on the editor, + or developing C++ modules. +- **Community** is dedicated to the life of Godot's community and contains a list of + recommended third-party tutorials and materials outside of this documentation. + It also provides details on the Asset Library. It also used to list Godot + communities, which are now listed on the `Godot website `_. +- Finally, the **Class reference** documents the full Godot API, + also available directly within the engine's script editor. + You can find information on all classes, functions, signals and so on here. + +In addition to this documentation, you may also want to take a look at the various `Godot demo projects `_. -Have fun reading and making games with Godot Engine! +About this documentation +------------------------ + +Members of the Godot Engine community continuously write, correct, edit, and +improve this documentation. We are always looking for more help. You can also +contribute by opening Github issues or translating the documentation into your language. +If you are interested in helping, see `How to contribute `__ +and `Writing documentation `__, +or get in touch with the `Documentation team `_ +on `Godot Contributors Chat `_. + +All documentation content is licensed under the permissive Creative Commons Attribution 3.0 +(`CC BY 3.0 `_) license, +with attribution to "*Juan Linietsky, Ariel Manzur, and the Godot Engine community*" +unless otherwise noted. + +*Have fun reading and making games with Godot Engine!* diff --git a/about/list_of_features.rst b/about/list_of_features.rst index 5a35f0b0647..f0f69792e0b 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -1,57 +1,79 @@ +:allow_comments: False + .. _doc_list_of_features: List of features ================ -This page aims to list all features currently supported by Godot. +This page aims to list **all** features currently supported by Godot. .. note:: - This page lists features supported by the current development version of - Godot (4.0.dev). Some of these features may not be available in the current - stable release series (3.2). - -Features --------- + This page lists features supported by the current stable version of + Godot. Some of these features are not available in the + `3.x release series `__. Platforms -^^^^^^^^^ +--------- + +.. seealso:: + + See :ref:`doc_system_requirements` for hardware and software version requirements. **Can run both the editor and exported projects:** -- Windows 7 and later (64-bit and 32-bit). -- macOS 10.12 and later (64-bit, x86 and ARM). -- Linux (64-bit, x86 and ARM). +- Windows (x86 and ARM, 64-bit and 32-bit). +- macOS (x86 and ARM, 64-bit only). +- Linux (x86 and ARM, 64-bit and 32-bit). - Binaries are statically linked and can run on any distribution if compiled on an old enough base distribution. - - Official binaries are compiled on Ubuntu 14.04. - - 32-bit binaries can be compiled from source. + - Official binaries are compiled using the + `Godot Engine buildroot `__, + allowing for binaries that work across common Linux distributions. + +- Android (editor support is experimental). +- :ref:`Web browsers `. Experimental in 4.0, + using Godot 3.x is recommended instead when targeting HTML5. + +.. note:: + + Linux supports rv64 (RISC-V), ppc64 & ppc32 (PowerPC), and loongarch64. However + you must compile the editor for that platform (as well as export templates) + yourself, no official downloads are currently provided. RISC-V compiling + instructions can be found on the :ref:`doc_compiling_for_linuxbsd` page. **Runs exported projects:** -- Android 4.4 and later. -- iOS 10.0 and later. -- HTML5 via WebAssembly (Firefox, Chrome, Edge, Opera). +- iOS. - :ref:`Consoles `. -Godot aims to be as platform-independent as possible and can be ported to new -platforms with relative ease. +Godot aims to be as platform-independent as possible and can be +:ref:`ported to new platforms ` with relative ease. + +.. note:: + + Projects written in C# using Godot 4 currently cannot be exported to the + web platform. To use C# on that platform, consider Godot 3 instead. + Android and iOS platform support is available as of Godot 4.2, but is + experimental and :ref:`some limitations apply `. Editor -^^^^^^ +------ **Features:** - Scene tree editor. -- Script editor. +- Built-in script editor. - Support for :ref:`external script editors ` such as Visual Studio Code or Vim. - GDScript :ref:`debugger `. - - No support for debugging in threads yet. -- Visual profiler with CPU and GPU time indications. -- Performance monitoring tools. + - Support for debugging in threads is available since 4.2. +- Visual profiler with CPU and GPU time indications for each step of the + rendering pipeline. +- Performance monitoring tools, including + :ref:`custom performance monitors `. - Live script reloading. - Live scene editing. @@ -65,87 +87,131 @@ Editor - Move the in-editor camera and see the result in the running project. +- Built-in offline class reference documentation. - Use the editor in dozens of languages contributed by the community. **Plugins:** - Editor plugins can be downloaded from the :ref:`asset library ` to extend editor functionality. -- Create your own plugins using GDScript to add new features or speed up your workflow. -- Download projects from the asset library in the project manager and import them directly. +- :ref:`Create your own plugins ` using GDScript to add new + features or speed up your workflow. +- :ref:`Download projects from the asset library ` + in the Project Manager and import them directly. -2D graphics -^^^^^^^^^^^ - -Vulkan renderer. - -- Sprite, polygon and line rendering. +Rendering +--------- - - High-level tools to draw lines and polygons such as Polygon2D and Line2D. +Godot 4 includes three renderers: -- AnimatedSprite as a helper for creating animated sprites. -- Parallax layers. +- **Forward+**. The most advanced renderer, suited for desktop platforms only. + Used by default on desktop platforms. This renderer uses **Vulkan**, **Direct3D 12**, + or **Metal** as the rendering driver, and it uses the **RenderingDevice** backend. +- **Mobile**. Fewer features, but renders simple scenes faster. Suited for mobile + and desktop platforms. Used by default on mobile platforms. This renderer uses + **Vulkan**, **Direct3D 12**, or **Metal** as the rendering driver, and it uses + the **RenderingDevice** backend. +- **Compatibility**, sometimes called **GL Compatibility**. The least advanced + renderer, suited for low-end desktop and mobile platforms. Used by default on + the web platform. This renderer uses **OpenGL** as the rendering driver. - - Pseudo-3D support by automatically duplicating a layer several times. +See :ref:`doc_renderers` for a detailed comparison of the rendering methods. -- 2D lighting with normal maps and specular maps. +2D graphics +----------- - - Hard or soft shadows. +- Sprite, polygon and line rendering. -- Font rendering using bitmaps (BitmapFont) or rasterization using FreeType (DynamicFont). + - High-level tools to draw lines and polygons such as + :ref:`class_Polygon2D` and :ref:`class_Line2D`, with support for texturing. - - Bitmap fonts can be exported using tools like BMFont. - - DynamicFont supports monochrome fonts as well as colored fonts. - Supported formats are TTF and OTF. - - DynamicFont supports optional font outlines with adjustable width and color. - - Support for font oversampling to keep fonts sharp at higher resolutions. +- AnimatedSprite2D as a helper for creating animated sprites. +- Parallax layers. -- GPU-based particles with support for custom particle shaders. + - Pseudo-3D support including preview in the editor. + +- :ref:`2D lighting ` with normal maps and specular maps. + + - Point (omni/spot) and directional 2D lights. + - Hard or soft shadows (adjustable on a per-light basis). + - Custom shaders can access a real-time :abbr:`SDF (Signed Distance Field)` + representation of the 2D scene based on :ref:`class_LightOccluder2D` nodes, + which can be used for improved 2D lighting effects including 2D global illumination. + +- :ref:`Font rendering ` using bitmaps, rasterization using FreeType + or multi-channel signed distance fields (MSDF). + + - Bitmap fonts can be exported using tools like BMFont, or imported from images + (for fixed-width fonts only). + - Dynamic fonts support monochrome fonts as well as colored fonts (e.g. for emoji). + Supported formats are TTF, OTF, WOFF1 and WOFF2. + - Dynamic fonts support optional font outlines with adjustable width and color. + - Dynamic fonts support variable fonts and OpenType features including ligatures. + - Dynamic fonts support simulated bold and italic when the font file lacks + those styles. + - Dynamic fonts support oversampling to keep fonts sharp at higher resolutions. + - Dynamic fonts support subpixel positioning to make fonts crisper at low sizes. + - Dynamic fonts support LCD subpixel optimizations to make fonts even crisper at low sizes. + - Signed distance field fonts can be scaled at any resolution without + requiring re-rasterization. Multi-channel usage makes SDF fonts scale down + to lower sizes better compared to monochrome SDF fonts. + +- GPU-based :ref:`particles ` with support for + :ref:`custom particle shaders `. - CPU-based particles. +- Optional :ref:`2D HDR rendering ` + for better glow capabilities. 2D tools -^^^^^^^^ +-------- +- :ref:`TileMaps ` for 2D tile-based level design. - 2D camera with built-in smoothing and drag margins. - Path2D node to represent a path in 2D space. - Can be drawn in the editor or generated procedurally. - PathFollow2D node to make nodes follow a Path2D. -- 2D geometry helper class. -- Line2D node to draw textured 2D lines. +- :ref:`2D geometry helper class `. 2D physics -^^^^^^^^^^ +---------- **Physics bodies:** - Static bodies. +- Animatable bodies (for objects moving only by script or animation, such as doors and platforms). - Rigid bodies. -- Kinematic bodies. +- Character bodies. - Joints. - Areas to detect bodies entering or leaving it. **Collision detection:** -- Built-in shapes: line, box, circle, capsule. +- Built-in shapes: line, box, circle, capsule, world boundary (infinite plane). - Collision polygons (can be drawn manually or generated from a sprite in the editor). 3D graphics -^^^^^^^^^^^ - -Vulkan renderer. +----------- - HDR rendering with sRGB. - Perspective, orthographic and frustum-offset cameras. +- When using the Forward+ renderer, a depth prepass is used to improve + performance in complex scenes by reducing the cost of overdraw. +- :ref:`doc_variable_rate_shading` on supported GPUs in Forward+ and Mobile. -**Physically-based rendering:** +**Physically-based rendering (built-in material features):** - Follows the Disney PBR model. +- Supports Burley, Lambert, Lambert Wrap (half-Lambert) and Toon diffuse shading modes. +- Supports Schlick-GGX, Toon and Disabled specular shading modes. - Uses a roughness-metallic workflow with support for ORM textures. +- Uses horizon specular occlusion (Filament model) to improve material appearance. - Normal mapping. - Parallax/relief mapping with automatic level of detail based on distance. +- Detail mapping for the albedo and normal maps. - Sub-surface scattering and transmittance. +- Screen-space refraction with support for material roughness (resulting in blurry refraction). - Proximity fade (soft particles) and distance fade. - Distance fade can use alpha blending or dithering to avoid going through the transparent pipeline. @@ -156,9 +222,15 @@ Vulkan renderer. - Directional lights (sun/moon). Up to 4 per scene. - Omnidirectional lights. - Spot lights with adjustable cone angle and attenuation. +- Specular, indirect light, and volumetric fog energy can be adjusted on a per-light basis. - Adjustable light "size" for fake area lights (will also make shadows blurrier). -- Lights are rendered with clustered forward optimizations to decrease their - individual cost. +- Optional distance fade system to fade distant lights and their shadows, improving performance. +- When using the Forward+ renderer (default on desktop), lights are + rendered with clustered forward optimizations to decrease their individual cost. + Clustered rendering also lifts any limits on the number of lights that can be used on a mesh. +- When using the Mobile renderer, up to 8 omni lights and 8 spot lights can + be displayed per mesh resource. Baked lighting can be used to overcome this limit + if needed. **Shadow mapping:** @@ -167,59 +239,129 @@ Vulkan renderer. - *OmniLight:* Dual paraboloid (fast) or cubemap (slower but more accurate). Supports colored projector textures in the form of panoramas. - *SpotLight:* Single texture. Supports colored projector textures. -- Shadow pancaking to decrease the amount of visible shadow acne and peter-panning. -- PCSS-like shadow blur based on the light size and distance from the surface - the shadow is casted on. -- Adjustable blur on a per-light basis. +- Shadow normal offset bias and shadow pancaking to decrease the amount of + visible shadow acne and peter-panning. +- :abbr:`PCSS (Percentage Closer Soft Shadows)`-like shadow blur based on the + light size and distance from the surface the shadow is cast on. +- Adjustable shadow blur on a per-light basis. **Global illumination with indirect lighting:** -- Baked lightmaps (fast, but can't be updated at run-time). - - - Lightmaps are baked on the GPU using compute shaders. - -- GI probes (slower, fully real-time). Supports reflections. -- Signed distance field GI (intermediate, supports dynamic lights but not - dynamic occluders). Supports reflections. -- Global illumination uses a deferred pass to allow for adaptive subsampling. +- :ref:`Baked lightmaps ` (fast, but can't be updated at runtime). + + - Supports baking indirect light only or baking both direct and indirect lighting. + The bake mode can be adjusted on a per-light basis to allow for hybrid light + baking setups. + - Supports lighting dynamic objects using automatic and manually placed probes. + - Optionally supports directional lighting and rough reflections based on spherical + harmonics. + - Lightmaps are baked on the GPU using compute shaders (much faster compared + to CPU lightmapping). Baking can only be performed from the editor, + not in exported projects. + - Supports GPU-based :ref:`denoising ` + with JNLM, or CPU/GPU-based denoising with OIDN. + +- :ref:`Voxel-based GI probes `. Supports + dynamic lights *and* dynamic occluders, while also supporting reflections. + Requires a fast baking step which can be performed in the editor or at + runtime (including from an exported project). +- :ref:`Signed-distance field GI ` designed for large open worlds. + Supports dynamic lights, but not dynamic occluders. Supports reflections. + No baking required. +- :ref:`Screen-space indirect lighting (SSIL) ` + at half or full resolution. Fully real-time and supports any kind of emissive + light source (including decals). +- VoxelGI and SDFGI use a deferred pass to allow for rendering GI at half + resolution to improve performance (while still having functional MSAA support). **Reflections:** -- Voxel-based reflections (when using GI probes) and SDF-based reflections (when using signed distance field GI). +- Voxel-based reflections (when using GI probes) and SDF-based reflections + (when using signed distance field GI). Voxel-based reflections are visible + on transparent surfaces, while rough SDF-based reflections are visible + on transparent surfaces. - Fast baked reflections or slow real-time reflections using ReflectionProbe. - Parallax correction can optionally be enabled. -- Screen-space reflections. -- Reflection techniques can be mixed together for greater accuracy. + Parallax box correction can optionally be enabled. +- Screen-space reflections with support for material roughness. +- Reflection techniques can be mixed together for greater accuracy or scalability. +- When using the Forward+ renderer (default on desktop), reflection probes are + rendered with clustered forward optimizations to decrease their individual cost. + Clustered rendering also lifts any limits on the number of reflection probes that can be used on a mesh. +- When using the Mobile renderer, up to 8 reflection probes can be displayed per mesh + resource. When using the Compatibility renderer, up to 2 reflection probes can + be displayed per mesh resource. + +**Decals:** + +- :ref:`Supports albedo `, emissive, :abbr:`ORM (Occlusion Roughness Metallic)`, + and normal mapping. +- Texture channels are smoothly overlaid on top of the underlying material, + with support for normal/ORM-only decals. +- Support for normal fade to fade the decal depending on its incidence angle. +- Does not rely on runtime mesh generation. This means decals can be used on + complex skinned meshes with no performance penalty, even if the decal moves every frame. +- Support for nearest, bilinear, trilinear or anisotropic texture filtering (configured globally). +- Optional distance fade system to fade distant decals, improving performance. +- When using the Forward+ renderer (default on desktop), decals are + rendered with clustered forward optimizations to decrease their individual cost. + Clustered rendering also lifts any limits on the number of decals that can be used on a mesh. +- When using the Mobile renderer, up to 8 decals can be displayed per mesh + resource. **Sky:** - Panorama sky (using an HDRI). - Procedural sky and Physically-based sky that respond to the DirectionalLights in the scene. -- Support for custom sky shaders. -- Radiance can be updated in real-time depending on the quality settings chosen. +- Support for :ref:`custom sky shaders `, which can be animated. +- The radiance map used for ambient and specular light can be updated in + real-time depending on the quality settings chosen. **Fog:** -- Depth fog (exponential or with custom attenuation). -- Height fog (floor or ceiling) with adjustable attenuation. -- Support for automatic depth fog color depending on the camera direction - (to match the sun color). -- Optional transmittance to make lights more visible in the fog. +- Exponential depth fog. +- Exponential height fog. +- Support for automatic fog color depending on the sky color (aerial perspective). +- Support for sun scattering in the fog. +- Support for controlling how much fog rendering should affect the sky, with + separate controls for traditional and volumetric fog. +- Support for making specific materials ignore fog. + +**Volumetric fog:** + +- Global :ref:`volumetric fog ` that reacts to lights and shadows. +- Volumetric fog can take indirect light into account when using VoxelGI or SDFGI. +- Fog volume nodes that can be placed to add fog to specific areas (or remove fog from specific areas). + Supported shapes include box, ellipse, cone, cylinder, and 3D texture-based density maps. +- Each fog volume can have its own custom shader. +- Can be used together with traditional fog. **Particles:** -- GPU-based particles with support for custom particle shaders. +- GPU-based particles with support for subemitters (2D + 3D), trails (2D + 3D), + attractors (3D only) and collision (2D + 3D). + + - 3D particle attractor shapes supported: box, sphere and 3D vector fields. + - 3D particle collision shapes supported: box, sphere, baked signed distance field + and real-time heightmap (suited for open world weather effects). + - 2D particle collision is handled using a signed distance field generated in real-time + based on :ref:`class_LightOccluder2D` nodes in the scene. + - Trails can use the built-in ribbon trail and tube trail meshes, or custom + meshes with skeletons. + - Support for custom particle shaders with manual emission. + - CPU-based particles. **Post-processing:** -- Tonemapping (Linear, Reinhard, Filmic, ACES). -- Automatic exposure adjustments based on viewport brightness. -- Near and far depth of field with adjustable bokeh simulation. -- Screen-space ambient occlusion at half or full resolution. +- Tonemapping (Linear, Reinhard, Filmic, ACES, AgX). +- Automatic exposure adjustments based on viewport brightness (and manual exposure override). +- Near and far depth of field with adjustable bokeh simulation (box, hexagon, circle). +- Screen-space ambient occlusion (SSAO) at half or full resolution. - Glow/bloom with optional bicubic upscaling and several blend modes available: Screen, Soft Light, Add, Replace, Mix. -- Color correction using an one-dimensional ramp. +- Glow can have a colored dirt map texture, acting as a lens dirt effect. +- Glow can be :ref:`used as a screen-space blur effect `. +- Color correction using a one-dimensional ramp or a 3D LUT texture. - Roughness limiter to reduce the impact of specular aliasing. - Brightness, contrast and saturation adjustments. @@ -235,35 +377,55 @@ Vulkan renderer. - ETC2 (not supported on macOS). - S3TC (not supported on mobile/Web platforms). -**Anti-aliasing:** +**Antialiasing:** +- Temporal :ref:`antialiasing ` (TAA). +- AMD FidelityFX Super Resolution 2.2 :ref:`antialiasing ` (FSR2), + which can be used at native resolution as a form of high-quality temporal antialiasing. +- Multi-sample antialiasing (MSAA), for both :ref:`doc_2d_antialiasing` and :ref:`doc_3d_antialiasing`. - Fast approximate antialiasing (FXAA). -- Multi-sample antialiasing (MSAA). +- Super-sample antialiasing (SSAA) using bilinear 3D scaling and a 3D resolution scale above 1.0. +- Alpha antialiasing, MSAA alpha to coverage and alpha hashing on a per-material basis. + +**Resolution scaling:** + +- Support for :ref:`rendering 3D at a lower resolution ` + while keeping 2D rendering at the original scale. This can be used to improve + performance on low-end systems or improve visuals on high-end systems. +- Resolution scaling uses bilinear filtering, AMD FidelityFX Super Resolution + 1.0 (FSR1) or AMD FidelityFX Super Resolution 2.2 (FSR2). +- Texture mipmap LOD bias is adjusted automatically to improve quality at lower + resolution scales. It can also be modified with a manual offset. -Most of these effects can be adjusted for better performance or to further -improve quality. This can be helpful when using Godot for offline rendering. +Most effects listed above can be adjusted for better performance or to further +improve quality. This can be helpful when +:ref:`using Godot for offline rendering `. 3D tools -^^^^^^^^ +-------- -- Built-in meshes: cube, cylinder/cone, (hemi)sphere, prism, plane, quad. -- Tools for :ref:`procedural geometry generation `. +- Built-in meshes: cube, cylinder/cone, (hemi)sphere, prism, plane, quad, torus, ribbon, tube. +- :ref:`GridMaps ` for 3D tile-based level design. - :ref:`Constructive solid geometry ` (intended for prototyping). +- Tools for :ref:`procedural geometry generation `. - Path3D node to represent a path in 3D space. - Can be drawn in the editor or generated procedurally. - PathFollow3D node to make nodes follow a Path3D. -- 3D geometry helper class. +- :ref:`3D geometry helper class `. +- Support for exporting the current scene as a glTF 2.0 file, both from the editor + and at runtime from an exported project. 3D physics -^^^^^^^^^^ +---------- **Physics bodies:** - Static bodies. +- Animatable bodies (for objects moving only by script or animation, such as doors and platforms). - Rigid bodies. -- Kinematic bodies. +- Character bodies. - Vehicle bodies (intended for arcade physics, not simulation). - Joints. - Soft bodies. @@ -272,70 +434,72 @@ improve quality. This can be helpful when using Godot for offline rendering. **Collision detection:** -- Built-in shapes: cuboid, sphere, capsule, cylinder (only with Bullet physics). +- Built-in shapes: cuboid, sphere, capsule, cylinder, world boundary (infinite plane). - Generate triangle collision shapes for any mesh from the editor. - Generate one or several convex collision shapes for any mesh from the editor. Shaders -^^^^^^^ +------- - *2D:* Custom vertex, fragment, and light shaders. - *3D:* Custom vertex, fragment, light, and sky shaders. -- Text-based shaders using a `shader language inspired by GLSL `. +- Text-based shaders using a :ref:`shader language inspired by GLSL `. - Visual shader editor. - Support for visual shader plugins. Scripting -^^^^^^^^^ +--------- **General:** - Object-oriented design pattern with scripts extending nodes. - Signals and groups for communicating between scripts. - Support for :ref:`cross-language scripting `. -- Many 2D and 3D linear algebra data types such as vectors and transforms. +- Many 2D, 3D and 4D linear algebra data types such as vectors and transforms. -:ref:`GDScript: ` +:ref:`GDScript: ` -- :ref:`High-level interpreted language ` with +- :ref:`High-level interpreted language ` with :ref:`optional static typing `. - Syntax inspired by Python. However, GDScript is **not** based on Python. - Syntax highlighting is provided on GitHub. - :ref:`Use threads ` to perform asynchronous actions or make use of multiple processor cores. -:ref:`C#: ` +:ref:`C#: ` - Packaged in a separate binary to keep file sizes and dependencies down. -- Uses Mono 6.x. +- Supports .NET 8 and higher. - - Full support for the C# 8.0 syntax and features. + - Full support for the C# 12.0 syntax and features. -- Supports all platforms. -- Using an external editor is recommended to benefit from IDE functionality. +- Supports Windows, Linux, and macOS. Since Godot 4.2, experimental support for Android and iOS is also available. -:ref:`VisualScript: ` + - On the iOS platform only some architectures are supported: ``arm64``. + - The web platform is currently unsupported. To use C# on that platform, + consider Godot 3 instead. -- :ref:`Graph-based visual scripting language `. -- Works best when used for specific purposes (such as level-specific logic) - rather than as a language to create entire projects. +- Using an external editor is recommended to benefit from IDE functionality. -**GDNative (C, C++, Rust, D, ...):** +**GDExtension (C, C++, Rust, D, ...):** - When you need it, link to native libraries for higher performance and third-party integrations. - For scripting game logic, GDScript or C# are recommended if their performance is suitable. -- Official bindings for C and C++. +- Official GDExtension bindings for `C `__ + and `C++ `__. - Use any build system and language features you wish. -- Maintained D, Kotlin, Python, Nim, and Rust bindings provided by the community. +- Actively developed GDExtension bindings for `D `__, + `Swift `__, and `Rust `__ + bindings provided by the community. (Some of these bindings may be experimental and not production-ready). Audio -^^^^^ +----- **Features:** @@ -346,7 +510,13 @@ Audio - Support for re-routable :ref:`audio buses ` and effects with dozens of effects included. -- Listener3D node to listen from a position different than the camera in 3D. +- Support for polyphony (playing several sounds from a single AudioStreamPlayer node). +- Support for random volume and pitch. +- Support for real-time pitch scaling. +- Support for sequential/random sample selection, including repetition prevention + when using random sample selection. +- Listener2D and Listener3D nodes to listen from a position different than the camera. +- Support for :ref:`procedural audio generation `. - Audio input to record microphones. - MIDI input. @@ -359,32 +529,36 @@ Audio - *Linux:* PulseAudio or ALSA. Import -^^^^^^ +------ - Support for :ref:`custom import plugins `. **Formats:** -- *Images:* See :ref:`doc_import_images`. +- *Images:* See :ref:`doc_importing_images`. - *Audio:* - WAV with optional IMA-ADPCM compression. - Ogg Vorbis. - MP3. -- *3D scenes:* +- *3D scenes:* See :ref:`doc_importing_3d_scenes`. - glTF 2.0 *(recommended)*. - - `ESCN `__ - (direct export from Blender). - - FBX. + - ``.blend`` (by calling Blender's glTF export functionality transparently). + - FBX (by calling `FBX2glTF `__ transparently). - Collada (.dae). - - Wavefront OBJ (static scenes only, can be loaded directly as a mesh). + - Wavefront OBJ (static scenes only, can be loaded directly as a mesh or imported as a 3D scene). + +- Support for loading glTF 2.0 scenes at runtime, including from an exported project. +- 3D meshes use `Mikktspace `__ to generate tangents + on import, which ensures consistency with other 3D applications such as Blender. Input -^^^^^ +----- -- Input mapping system using hardcoded input events or remappable input actions. +- :ref:`Input mapping system ` using hardcoded input events + or remappable input actions. - Axis values can be mapped to two different actions with a configurable deadzone. - Use the same code to support both keyboards and gamepads. @@ -403,76 +577,104 @@ Input - Pen/tablet input with pressure support. Navigation -^^^^^^^^^^ +---------- -- A* algorithm in 2D and 3D. -- Navigation meshes with dynamic obstacle avoidance. -- Generate navigation meshes from the editor. +- A* algorithm in :ref:`2D ` and :ref:`3D `. +- Navigation meshes with dynamic obstacle avoidance in + :ref:`2D ` and :ref:`3D `. +- Generate navigation meshes from the editor or at runtime (including from an exported project). Networking -^^^^^^^^^^ +---------- -- Low-level TCP networking using StreamPeer and TCP_Server. -- Low-level UDP networking using PacketPeer and UDPServer. -- Low-level HTTP requests using HTTPClient. -- High-level HTTP requests using HTTPRequest. +- Low-level TCP networking using :ref:`class_StreamPeer` and :ref:`class_TCPServer`. +- Low-level UDP networking using :ref:`class_PacketPeer` and :ref:`class_UDPServer`. +- Low-level HTTP requests using :ref:`class_HTTPClient`. +- High-level HTTP requests using :ref:`class_HTTPRequest`. - Supports HTTPS out of the box using bundled certificates. -- High-level multiplayer API using UDP and ENet. +- :ref:`High-level multiplayer ` API using UDP and ENet. - Automatic replication using remote procedure calls (RPCs). - Supports unreliable, reliable and ordered transfers. -- WebSocket client and server, available on all platforms. -- WebRTC client and server, available on all platforms. -- Support for UPnP to sidestep the requirement to forward ports when hosting - a server behind a NAT. +- :ref:`WebSocket ` client and server, available on all platforms. +- :ref:`WebRTC ` client and server, available on all platforms. +- Support for :ref:`UPnP ` to sidestep the requirement to forward ports + when hosting a server behind a NAT. Internationalization -^^^^^^^^^^^^^^^^^^^^ +-------------------- - Full support for Unicode including emoji. - Store localization strings using :ref:`CSV ` or :ref:`gettext `. + + - Support for generating gettext POT and PO files from the editor. + - Use localized strings in your project automatically in GUI elements or by using the ``tr()`` function. -- Support for right-to-left typesetting and text shaping planned in Godot 4.0. +- Support for pluralization and translation contexts when using gettext translations. +- Support for :ref:`bidirectional typesetting `, + text shaping and OpenType localized forms. +- Automatic UI mirroring for right-to-left locales. +- Support for pseudolocalization to test your project for i18n-friendliness. Windowing and OS integration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- +- Spawn multiple independent windows within a single process. - Move, resize, minimize, and maximize windows spawned by the project. - Change the window title and icon. - Request attention (will cause the title bar to blink on most platforms). - Fullscreen mode. - - Doesn't use exclusive fullscreen, so the screen resolution can't be changed this way. - Use a Viewport with a different resolution instead. + - Uses borderless fullscreen by default on Windows for fast alt-tabbing, + but can optionally use exclusive fullscreen to reduce input lag. - Borderless windows (fullscreen or non-fullscreen). - Ability to keep a window always on top. -- Transparent windows with per-pixel transparency. - Global menu integration on macOS. -- Execute commands in a blocking or non-blocking manner. +- Execute commands in a blocking or non-blocking manner (including running + multiple instances of the same project). - Open file paths and URLs using default or custom protocol handlers (if registered on the system). - Parse custom command line arguments. +- Any Godot binary (editor or exported project) can be + :ref:`used as a headless server ` + by starting it with the ``--headless`` command line argument. + This allows running the engine without a GPU or display server. Mobile -^^^^^^ +------ -- In-app purchases on Android and iOS. +- In-app purchases on :ref:`Android ` + and :ref:`iOS `. - Support for advertisements using third-party modules. +.. _doc_xr_support: + XR support (AR and VR) -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- + +- Out of the box :ref:`support for OpenXR `. + + - Including support for popular desktop headsets like the Valve Index, WMR headsets, and Quest over Link. + +- Support for :ref:`Android-based headsets ` using OpenXR through a plugin. -- Support for ARKit on iOS out of the box. -- Support for the OpenXR and OpenVR APIs. -- Popular VR headsets like the Oculus Quest and HTC Vive are supported thanks to plugins. + - Including support for popular stand alone headsets like the Meta Quest 1/2/3 and Pro, Pico 4, Magic Leap 2, and Lynx R1. + +- Out of the box limited support for visionOS Apple headsets. + + - Currently only exporting an application for use on a flat plane within the + headset is supported. Immersive experiences are not supported. + +- Other devices supported through an XR plugin structure. +- Various advanced toolkits are available that implement common features required by XR applications. GUI system -^^^^^^^^^^ +---------- Godot's GUI is built using the same Control nodes used to make games in Godot. The editor UI can easily be extended in many ways using add-ons. @@ -481,13 +683,16 @@ The editor UI can easily be extended in many ways using add-ons. - Buttons. - Checkboxes, check buttons, radio buttons. -- Text entry using LineEdit (single line) and TextEdit (multiple lines). -- Dropdown menus using PopupMenu and OptionButton. +- Text entry using :ref:`class_LineEdit` (single line) and :ref:`class_TextEdit` (multiple lines). + TextEdit also supports code editing features such as displaying line numbers + and syntax highlighting. +- Dropdown menus using :ref:`class_PopupMenu` and :ref:`class_OptionButton`. - Scrollbars. - Labels. -- RichTextLabel for :ref:`text formatted using BBCode `. +- RichTextLabel for :ref:`text formatted using BBCode `, + with support for animated custom effects. - Trees (can also be used to represent tables). -- Containers (horizontal, vertical, grid, center, margin, draggable splitter, ...). +- Color picker with RGB and HSV modes. - Controls can be rotated and scaled. **Sizing:** @@ -497,11 +702,13 @@ The editor UI can easily be extended in many ways using add-ons. - :ref:`Stack ` layouts. - :ref:`Grid ` layouts. - - :ref:`Margin ` and :ref:`centered ` - layouts. + - :ref:`Flow ` layouts (similar to autowrapping text). + - :ref:`Margin `, :ref:`centered ` + and :ref:`aspect ratio ` layouts. - :ref:`Draggable splitter ` layouts. -- Scale to multiple resolutions using the ``2d`` or ``viewport`` stretch modes. +- Scale to :ref:`multiple resolutions ` using the + ``canvas_items`` or ``viewport`` stretch modes. - Support any aspect ratio using anchors and the ``expand`` stretch aspect. **Theming:** @@ -512,7 +719,7 @@ The editor UI can easily be extended in many ways using add-ons. - Procedural vector-based theming using :ref:`class_StyleBoxFlat`. - - Supports rounded/beveled corners, drop shadows and per-border widths. + - Supports rounded/beveled corners, drop shadows, per-border widths and antialiasing. - Texture-based theming using :ref:`class_StyleBoxTexture`. @@ -520,7 +727,7 @@ Godot's small distribution size can make it a suitable alternative to frameworks like Electron or Qt. Animation -^^^^^^^^^ +--------- - Direct kinematics and inverse kinematics. - Support for animating any property with customizable interpolation. @@ -528,42 +735,57 @@ Animation - Support for playing sounds in animation tracks. - Support for Bézier curves in animation. -Formats -^^^^^^^ +File formats +------------ - Scenes and resources can be saved in :ref:`text-based ` or binary formats. - Text-based formats are human-readable and more friendly to version control. - Binary formats are faster to save/load for large scenes/resources. -- Read and write text or binary files using :ref:`class_File`. +- Read and write text or binary files using :ref:`class_FileAccess`. - Can optionally be compressed or encrypted. - Read and write :ref:`class_JSON` files. - Read and write INI-style configuration files using :ref:`class_ConfigFile`. - - Can (de)serialize any Godot datatype, including Vector, Color, ... + - Can (de)serialize any Godot datatype, including Vector2/3, Color, ... - Read XML files using :ref:`class_XMLParser`. +- :ref:`Load and save images, audio/video, fonts and ZIP archives ` + in an exported project without having to go through Godot's import system. - Pack game data into a PCK file (custom format optimized for fast seeking), into a ZIP archive, or directly into the executable for single-file distribution. - :ref:`Export additional PCK files` that can be read by the engine to support mods and DLCs. Miscellaneous -^^^^^^^^^^^^^ +------------- +- :ref:`Video playback ` with built-in support for Ogg Theora. +- :ref:`Movie Maker mode ` to record videos from a running + project with synchronized audio and perfect frame pacing. - :ref:`Low-level access to servers ` which allows bypassing the scene tree's overhead when needed. -- Command line interface for automation. +- :ref:`Command line interface ` for automation. - Export and deploy projects using continuous integration platforms. - - `Completion scripts `__ + - `Shell completion scripts `__ are available for Bash, zsh and fish. - -- Support for :ref:`C++ modules ` statically linked + - Print colored text to standard output on all platforms using + :ref:`print_rich `. + +- The editor can + :ref:`detect features used in a project and create a compilation profile `, + which can be used to create smaller export template binaries + with unneeded features disabled. +- Support for :ref:`C++ modules ` statically linked into the engine binary. + + - Most built-in modules can be disabled at compile-time to reduce binary size + in custom builds. See :ref:`doc_optimizing_for_size` for details. + - Engine and editor written in C++17. - Can be :ref:`compiled ` using GCC, @@ -574,10 +796,10 @@ Miscellaneous - Licensed under the permissive MIT license. - - Open developement process with :ref:`contributions welcome `. + - Open development process with `contributions welcome `__. .. seealso:: - The `roadmap `__ repository - documents features that have been agreed upon and may be implemented in - future Godot releases. + The `Godot proposals repository `__ + lists features that have been requested by the community and may be implemented + in future Godot releases. diff --git a/about/release_policy.rst b/about/release_policy.rst index 502e9b95b34..64bcd14e871 100644 --- a/about/release_policy.rst +++ b/about/release_policy.rst @@ -1,11 +1,13 @@ +:allow_comments: False + .. _doc_release_policy: Godot release policy ==================== -Godot's release policy is in constant evolution. What is described below is -intended to give a general idea of what to expect, but what will actually -happen depends on the choices of core contributors, and the needs of the +Godot's release policy is in constant evolution. The description below +provides a general idea of what to expect, but what will actually +happen depends on the choices of core contributors and the needs of the community at a given time. Godot versioning @@ -19,26 +21,25 @@ term adapted to the complexity of a game engine: which imply significant porting work to move projects from one major version to another. - For example, porting Godot projects from Godot 2.1 to Godot 3.0 required + For example, porting Godot projects from Godot 3.x to Godot 4.x requires running the project through a conversion tool, and then performing a number of further adjustments manually for what the tool could not do automatically. -- The ``minor`` version is incremented for feature releases which do not break +- The ``minor`` version is incremented for feature releases that do not break compatibility in a major way. Minor compatibility breakage in very specific areas *may* happen in minor versions, but the vast majority of projects should not be affected or require significant porting work. - The reason for this is that as a game engine, Godot covers many areas such - as rendering, physics, scripting, etc., and fixing bugs or implementing new - features in a given area may sometimes require changing the behavior of a - feature, or modifying the interface of a given class, even if the rest of - the engine API remains backwards compatible. + This is because Godot, as a game engine, covers many areas like rendering, + physics, and scripting. Fixing bugs or implementing new features in one area + might sometimes require changing a feature's behavior or modifying a class's + interface, even if the rest of the engine API remains backwards compatible. .. tip:: - Upgrading to a new minor version is therefore recommended for all users, + Upgrading to a new minor version is recommended for all users, but some testing is necessary to ensure that your project still behaves as - expected in a new minor version. + expected. - The ``patch`` version is incremented for maintenance releases which focus on fixing bugs and security issues, implementing new requirements for platform @@ -56,20 +57,15 @@ term adapted to the complexity of a game engine: We call ``major.minor`` combinations *stable branches*. Each stable branch starts with a ``major.minor`` release (without the ``0`` for ``patch``) and is further developed for maintenance releases in a Git branch of the same name -(for example patch updates for the 3.3 stable branch are developed in the -``3.3`` Git branch). - -.. note:: - - As mentioned in the introduction, Godot's release policy is evolving, and - earlier Godot releases may not have followed the above rules to the letter. - In particular, the 3.2 stable branch received a number of new features in - 3.2.2 which would have warranted a ``minor`` version increment. +(for example patch updates for the 4.0 stable branch are developed in the +``4.0`` Git branch). Release support timeline ------------------------ -Stable branches are supported *at minimum* until the next stable branch is +.. UPDATE: Table changes every minor version. Support policy may change. + +Stable branches are supported *at least* until the next stable branch is released and has received its first patch update. In practice, we support stable branches on a *best effort* basis for as long as they have active users who need maintenance updates. @@ -77,37 +73,59 @@ who need maintenance updates. Whenever a new major version is released, we make the previous stable branch a long-term supported release, and do our best to provide fixes for issues encountered by users of that branch who cannot port complex projects to the new -major version. This is the case for the 2.1 branch, and will be the case for -the latest 3.x stable branch by the time Godot 4.0 is released. - -+-------------+-------------------+--------------------------------------------------------------------------+ -| **Version** | **Release date** | **Support level** | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 4.0 | ~2021 (see below) | |unstable| *Current focus of development (unstable).* | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 3.4 | Q2 or Q3 2021 | |supported| *Beta.* Receives new features as well as bug fixes while | -| | | under development. | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 3.3 | April 2021 | |supported| Receives fixes for bugs, security and platform support | -| | | issues, as well as backwards-compatible usability enhancements. | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 3.2 | January 2020 | |eol| No longer supported as fully superseded by the compatible 3.3 | -| | | release (last update: 3.2.3). | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 3.1 | March 2019 | |partial| Only critical, security and platform support fixes | -| | | (last update: 3.1.2). | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 3.0 | January 2018 | |eol| No longer supported (last update: 3.0.6). | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 2.1 | July 2016 | |partial| Only critical, security and platform support fixes | -| | | (last update: 2.1.6). | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 2.0 | February 2016 | |eol| No longer supported (last update: 2.0.4.1). | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 1.1 | May 2015 | |eol| No longer supported. | -+-------------+-------------------+--------------------------------------------------------------------------+ -| Godot 1.0 | December 2014 | |eol| No longer supported. | -+-------------+-------------------+--------------------------------------------------------------------------+ +major version. This was the case for the 2.1 branch, and is the case for the +3.x branch. + +In a given minor release series, only the latest patch release receives support. +If you experience an issue using an older patch release, please upgrade to the +latest patch release of that series and test again before reporting an issue +on GitHub. + ++--------------+----------------------+--------------------------------------------------------------------------+ +| **Version** | **Release date** | **Support level** | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 4.6 | Q1 2026 (estimate) | |unstable| *Development.* Receives new features, usability and | +| (`master`) | | performance improvements, as well as bug fixes, while under development. | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 4.5 | September 2025 | |supported| Receives fixes for bugs and security issues, as well as | +| | | patches that enable platform support. | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 4.4 | March 2025 | |partial| Receives fixes for security and platform support issues only. | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 4.3 | August 2024 | |eol| No longer supported (last update: 4.3). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 4.2 | November 2023 | |eol| No longer supported (last update: 4.2.2). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 4.1 | July 2023 | |eol| No longer supported (last update: 4.1.4). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 4.0 | March 2023 | |eol| No longer supported (last update: 4.0.4). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 3.7 | No ETA for now | |supported| *Beta.* Receives new features, usability and performance | +| (`3.x`) | | improvements, as well as bug fixes, while under development. | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 3.6 | September 2024 | |supported| Receives fixes for bugs and security issues, as well as | +| | | patches that enable platform support. | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 3.5 | August 2022 | |eol| No longer supported (last update: 3.5.3). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 3.4 | November 2021 | |eol| No longer supported (last update: 3.4.5). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 3.3 | April 2021 | |eol| No longer supported (last update: 3.3.4). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 3.2 | January 2020 | |eol| No longer supported (last update: 3.2.3). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 3.1 | March 2019 | |eol| No longer supported (last update: 3.1.2). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 3.0 | January 2018 | |eol| No longer supported (last update: 3.0.6). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 2.1 | July 2016 | |eol| No longer supported (last update: 2.1.6). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 2.0 | February 2016 | |eol| No longer supported (last update: 2.0.4.1). | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 1.1 | May 2015 | |eol| No longer supported. | ++--------------+----------------------+--------------------------------------------------------------------------+ +| Godot 1.0 | December 2014 | |eol| No longer supported. | ++--------------+----------------------+--------------------------------------------------------------------------+ .. |supported| image:: img/supported.png .. |partial| image:: img/partial.png @@ -123,22 +141,148 @@ the latest 3.x stable branch by the time Godot 4.0 is released. Pre-release Godot versions aren't intended to be used in production and are provided for testing purposes only. +.. seealso:: + + See :ref:`doc_upgrading_to_godot_4` for instructions on migrating a project + from Godot 3.x to 4.x. + +.. _doc_release_policy_which_version_should_i_use: + +Which version should I use for a new project? +--------------------------------------------- + +We recommend using Godot 4.x for new projects, as the Godot 4.x series will be +supported long after 3.x stops receiving updates in the future. One caveat is +that a lot of third-party documentation hasn't been updated for Godot 4.x yet. +If you have to follow a tutorial designed for Godot 3.x, we recommend keeping +:ref:`doc_upgrading_to_godot_4` open in a separate tab to check which methods +have been renamed (if you get a script error while trying to use a specific node +or method that was renamed in Godot 4.x). + +If your project requires a feature that is missing in 4.x (such as GLES2/WebGL +1.0), you should use Godot 3.x for a new project instead. + +.. _doc_release_policy_should_i_upgrade_my_project: + +Should I upgrade my project to use new engine versions? +------------------------------------------------------- + +.. note:: + + Upgrading software while working on a project is inherently risky, so + consider whether it's a good idea for your project before attempting an + upgrade. Also, make backups of your project or use version control to + prevent losing data in case the upgrade goes wrong. + + That said, we do our best to keep minor and especially patch releases + compatible with existing projects. + +The general recommendation is to upgrade your project to follow new *patch* +releases, such as upgrading from 4.0.2 to 4.0.3. This ensures you get bug fixes, +security updates and platform support updates (which is especially important for +mobile platforms). You also get continued support, as only the last patch +release receives support on official community platforms. + +For *minor* releases, you should determine whether it's a good idea to upgrade +on a case-by-case basis. We've made a lot of effort in making the upgrade +process as seamless as possible, but some breaking changes may be present in +minor releases, along with a greater risk of regressions. Some fixes included in +minor releases may also change a class' expected behavior as required to fix +some bugs. This is especially the case in classes marked as *experimental* in +the documentation. + +*Major* releases bring a lot of new functionality, but they also remove +previously existing functionality and may raise hardware requirements. They also +require much more work to upgrade to compared to minor releases. As a result, we +recommend sticking with the major release you've started your project with if +you are happy with how your project currently works. For example, if your +project was started with 3.5, we recommend upgrading to 3.5.2 and possibly 3.6 +in the future, but not to 4.0+, unless your project really needs the new +features that come with 4.0+. + .. _doc_release_policy_when_is_next_release_out: When is the next release out? ----------------------------- -While Godot contributors aren't working under any deadlines, we have -historically had one major or minor release per year, with several maintenance -updates between each. +.. UPDATE: Refers to specific current minor versions 3.6 and 3.7. + +While Godot contributors aren't working under any deadlines, we strive to +publish minor releases relatively frequently. -Starting with Godot 3.3, we aim to accelerate our development cycles for minor -releases, so you can expect a new minor release every 3 to 6 months. +In particular, after the very long release cycle for 4.0, we are pivoting to +a faster-paced development workflow, 4.1 released 4 months after 4.0, and 4.2 +released 4 months after 4.1. -Maintenance (patch) releases will be released as needed with potentially very +Frequent minor releases will enable us to ship new features faster (possibly +as experimental), get user feedback quickly, and iterate to improve those +features and their usability. Likewise, the general user experience will be +improved more steadily with a faster path to the end users. + +Maintenance (patch) releases are released as needed with potentially very short development cycles, to provide users of the current stable branch with the latest bug fixes for their production needs. -As for the upcoming Godot 4.0, we can only say that we aim for a **2021** -release, but any closer estimate is likely to be hard to uphold. Alpha builds -will be published as soon as the main features for Godot 4.0 are finalized. +There is currently no planned release date for the next 3.x minor version, 3.7. +The current stable release, 3.6, may be the last stable branch of Godot 3.x. +Godot 3.x is supported on a best-effort basis, as long as contributors continue +to maintain it. + +What are the criteria for compatibility across engine versions? +--------------------------------------------------------------- + +.. note:: + + This section is intended to be used by contributors to determine which + changes are safe for a given release. The list is not exhaustive; it only + outlines the most common situations encountered during Godot's development. + +The following changes are acceptable in patch releases: + +- Fixing a bug in a way that has no major negative impact on most projects, such + as a visual or physics bug. Godot's physics engine is not deterministic, so + physics bug fixes are not considered to break compatibility. If fixing a bug + has a negative impact that could impact a lot of projects, it should be made + optional (e.g. using a project setting or separate method). +- Adding a new optional parameter to a method. +- Small-scale editor usability tweaks. + +Note that we tend to be more conservative with the fixes we allow in each +subsequent patch release. For instance, 4.0.1 may receive more impactful fixes +than 4.0.4 would. + +The following changes are acceptable in minor releases, but not patch releases: + +- Significant new features. +- Renaming a method parameter. In C#, method parameters can be passed by name + (but not in GDScript). As a result, this can break some projects that use C#. +- Deprecating a method, member variable, or class. This is done by adding a + deprecated flag to its class reference, which will show up in the editor. When + a method is marked as deprecated, it's slated to be removed in the next + *major* release. +- Changes that affect the default project theme's visuals. +- Bug fixes which significantly change the behavior or the output, with the aim + to meet user expectations better. In comparison, in patch releases, we may + favor keeping a buggy behavior so we don't break existing projects which + likely already rely on the bug or use a workaround. +- Performance optimizations that result in visual changes. + +The following changes are considered **compatibility-breaking** and can only be +performed in a new major release: + +- Renaming or removing a method, member variable, or class. +- Modifying a node's inheritance tree by making it inherit from a different class. +- Changing the default value of a project setting value in a way that affects existing + projects. To only affect new projects, the project manager should write a + modified ``project.godot`` instead. + +Since Godot 5.0 hasn't been branched off yet, we currently discourage making +compatibility-breaking changes of this kind. + +.. note:: + + When modifying a method's signature in any fashion (including adding an + optional parameter), a GDExtension compatibility method must be created. + This ensures that existing GDExtensions continue to work across patch and + minor releases, so that users don't have to recompile them. + See :ref:`doc_handling_compatibility_breakages` for more information. diff --git a/about/system_requirements.rst b/about/system_requirements.rst new file mode 100644 index 00000000000..2a095eaf136 --- /dev/null +++ b/about/system_requirements.rst @@ -0,0 +1,376 @@ +:allow_comments: False + +.. _doc_system_requirements: + +System requirements +=================== + +This page contains system requirements for the editor and exported projects. +These specifications are given for informative purposes only, but they can be +referred to if you're looking to build or upgrade a system to use Godot on. + +Godot editor +------------ + +These are the **minimum** specifications required to run the Godot editor and work +on a simple 2D or 3D project: + +Desktop or laptop PC - Minimum +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. When adjusting specifications, make sure to only mention hardware that can run the required OS version. +.. For example, the x86 CPU requirement for macOS is set after the MacBook Air 11" (late 2010 model), +.. which can run up to macOS 10.13. + ++----------------------+-----------------------------------------------------------------------------------------+ +| **CPU** | - **Windows:** x86_32 CPU with SSE2 support, x86_64 CPU with SSE4.2 support, ARMv8 CPU | +| | | +| | - *Example: Intel Core 2 Duo E8200, AMD FX-4100, Snapdragon X Elite* | +| | | +| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | +| | | +| | - *Example: Intel Core 2 Duo SU9400, Apple M1* | +| | | +| | - **Linux:** x86_32 CPU with SSE2 support, x86_64 CPU with SSE4.2 support, ARMv7 or | +| | ARMv8 CPU | +| | | +| | - *Example: Intel Core 2 Duo E8200, AMD FX-4100, Raspberry Pi 4* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ renderer:** Integrated graphics with full Vulkan 1.0 support | +| | | +| | - *Example: Intel HD Graphics 510 (Skylake), AMD Radeon R5 Graphics (Kaveri)* | +| | | +| | - **Mobile renderer:** Integrated graphics with full Vulkan 1.0 support | +| | | +| | - *Example: Intel HD Graphics 510 (Skylake), AMD Radeon R5 Graphics (Kaveri)* | +| | | +| | - **Compatibility renderer:** Integrated graphics with full OpenGL 3.3 support | +| | | +| | - *Example: Intel HD Graphics 2500 (Ivy Bridge), AMD Radeon R5 Graphics (Kaveri)* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **RAM** | - **Native editor:** 4 GB | +| | - **Web editor:** 8 GB | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Storage** | 200 MB (used for the executable, project files and cache). | +| | Exporting projects requires downloading export templates separately | +| | (1.3 GB after installation). | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Operating system** | - **Native editor:** Windows 10, macOS 10.13 (Compatibility) or | +| | macOS 10.15 (Forward+/Mobile), Linux distribution released after 2018 | +| | - **Web editor:** Recent versions of mainstream browsers: Firefox and derivatives | +| | (including ESR), Chrome and Chromium derivatives, Safari and WebKit derivatives. | ++----------------------+-----------------------------------------------------------------------------------------+ + +.. note:: + + If your x86_64 CPU does not support SSE4.2, you can still run the 32-bit Godot + executable which only has a SSE2 requirement (all x86_64 CPUs support SSE2). + + While supported on Linux, we have no official minimum requirements for running on + rv64 (RISC-V), ppc64 & ppc32 (PowerPC), and loongarch64. In addition you must + compile the editor for that platform (as well as export templates) yourself, + no official downloads are currently provided. RISC-V compiling instructions can + be found on the :ref:`doc_compiling_for_linuxbsd` page. + +Mobile device (smartphone/tablet) - Minimum +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------+-----------------------------------------------------------------------------------------+ +| **CPU** | - **Android:** SoC with any 32-bit or 64-bit ARM or x86 CPU | +| | | +| | - *Example: Qualcomm Snapdragon 430, Samsung Exynos 5 Octa 5430* | +| | | +| | - **iOS:** *Cannot run the editor* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ renderer:** SoC featuring GPU with full Vulkan 1.0 support | +| | | +| | - *Example: Qualcomm Adreno 505, Mali-G71 MP2* | +| | | +| | - **Mobile renderer:** SoC featuring GPU with full Vulkan 1.0 support | +| | | +| | - *Example: Qualcomm Adreno 505, Mali-G71 MP2* | +| | | +| | - **Compatibility renderer:** SoC featuring GPU with full OpenGL ES 3.0 support | +| | | +| | - *Example: Qualcomm Adreno 306, Mali-T628 MP6* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **RAM** | - **Native editor:** 3 GB | +| | - **Web editor:** 6 GB | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Storage** | 200 MB (used for the executable, project files and cache) | +| | Exporting projects requires downloading export templates separately | +| | (1.3 GB after installation) | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Operating system** | - **Native editor:** Android 6.0 (Compatibility) or Android 9.0 (Forward+/Mobile) | +| | - **Web editor:** Recent versions of mainstream browsers: Firefox and derivatives | +| | (including ESR), Chrome and Chromium derivatives, Safari and WebKit derivatives. | ++----------------------+-----------------------------------------------------------------------------------------+ + +These are the **recommended** specifications to get a smooth experience with the +Godot editor on a simple 2D or 3D project: + +Desktop or laptop PC - Recommended +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------+---------------------------------------------------------------------------------------------+ +| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 support, with 4 physical cores or more, ARMv8 CPU | +| | | +| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Snapdragon X Elite* | +| | | +| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | +| | | +| | - *Example: Intel Core i5-8500, Apple M1* | +| | | +| | - **Linux:** x86_64 CPU with SSE4.2 support, ARMv7 or ARMv8 CPU | +| | | +| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* | ++----------------------+---------------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ renderer:** Dedicated graphics with full Vulkan 1.2 support | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Mobile renderer:** Dedicated graphics with full Vulkan 1.2 support | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Compatibility renderer:** Dedicated graphics with full OpenGL 4.6 support | +| | | +| | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* | ++----------------------+---------------------------------------------------------------------------------------------+ +| **RAM** | - **Native editor:** 8 GB | +| | - **Web editor:** 12 GB | ++----------------------+---------------------------------------------------------------------------------------------+ +| **Storage** | 1.5 GB (used for the executable, project files, all export templates and cache) | ++----------------------+---------------------------------------------------------------------------------------------+ +| **Operating system** | - **Native editor:** Windows 10, macOS 10.15, | +| | Linux distribution released after 2020 | +| | - **Web editor:** Latest version of Firefox, Chrome, Edge, Safari, Opera | ++----------------------+---------------------------------------------------------------------------------------------+ + +Mobile device (smartphone/tablet) - Recommended +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------+-----------------------------------------------------------------------------------------+ +| **CPU** | - **Android:** SoC with 64-bit ARM or x86 CPU, with 3 "performance" cores or more | +| | | +| | - *Example: Qualcomm Snapdragon 845, Samsung Exynos 9810* | +| | | +| | - **iOS:** *Cannot run the editor* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ renderer:** SoC featuring GPU with full Vulkan 1.2 support | +| | | +| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* | +| | | +| | - **Mobile renderer:** SoC featuring GPU with full Vulkan 1.2 support | +| | | +| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* | +| | | +| | - **Compatibility renderer:** SoC featuring GPU with full OpenGL ES 3.2 support | +| | | +| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **RAM** | - **Native editor:** 6 GB | +| | - **Web editor:** 8 GB | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Storage** | 1.5 GB (used for the executable, project files, all export templates and cache) | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Operating system** | - **Native editor:** Android 9.0 | +| | - **Web editor:** Latest version of Firefox, Chrome, Edge, Safari, Opera, | +| | Samsung Internet | ++----------------------+-----------------------------------------------------------------------------------------+ + +Exported Godot project +---------------------- + +.. warning:: + + The requirements below are a baseline for a **simple** 2D or 3D project, + with basic scripting and few visual flourishes. CPU, GPU, RAM and + storage requirements will heavily vary depending on your project's scope, + its renderer, viewport resolution and graphics settings chosen. + Other programs running on the system while the project is running + will also compete for resources, including RAM and video RAM. + + It is strongly recommended to do your own testing on low-end hardware to + make sure your project runs at the desired speed. To provide scalability for + low-end hardware, you will also need to introduce a + `graphics options menu `__ + to your project. + +These are the **minimum** specifications required to run a simple 2D or 3D +project exported with Godot: + +Desktop or laptop PC - Minimum +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. When adjusting specifications, make sure to only mention hardware that can run the required OS version. +.. For example, the x86 CPU requirement for macOS is set after the MacBook Air 11" (late 2010 model), +.. which can run up to macOS 10.13. + ++----------------------+-----------------------------------------------------------------------------------------+ +| **CPU** | - **Windows:** x86_32 CPU with SSE2 support, x86_64 CPU with SSE4.2 support, | +| | ARMv8 CPU | +| | | +| | - *Example: Intel Core 2 Duo E8200, AMD FX-4100, Snapdragon X Elite* | +| | | +| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | +| | | +| | - *Example: Intel Core 2 Duo SU9400, Apple M1* | +| | | +| | - **Linux:** x86_32 CPU with SSE2 support, x86_64 CPU with SSE4.2 support, | +| | ARMv7 or ARMv8 CPU | +| | | +| | - *Example: Intel Core 2 Duo E8200, AMD FX-4100, Raspberry Pi 4* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ renderer:** Integrated graphics with full Vulkan 1.0 support, | +| | Metal 3 support (macOS) or Direct3D 12 (12_0 feature level) support (Windows) | +| | | +| | - *Example: Intel HD Graphics 510 (Skylake), AMD Radeon R5 Graphics (Kaveri)* | +| | | +| | - **Mobile renderer:** Integrated graphics with full Vulkan 1.0 support, | +| | Metal 3 support (macOS) or Direct3D 12 (12_0 feature level) support (Windows) | +| | | +| | - *Example: Intel HD Graphics 510 (Skylake), AMD Radeon R5 Graphics (Kaveri)* | +| | | +| | - **Compatibility renderer:** Integrated graphics with full OpenGL 3.3 support | +| | or Direct3D 11 support (Windows). | +| | | +| | - *Example: Intel HD Graphics 2500 (Ivy Bridge), AMD Radeon R5 Graphics (Kaveri)* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **RAM** | - **For native exports:** 2 GB | +| | - **For web exports:** 4 GB | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Storage** | 150 MB (used for the executable, project files and cache) | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Operating system** | - **For native exports:** Windows 10, macOS 10.13 (Compatibility), macOS 10.15 | +| | (Forward+/Mobile, Vulkan), macOS 13.0 (Forward+/Mobile, Metal), Linux distribution | +| | released after 2018 | +| | - **Web editor:** Recent versions of mainstream browsers: Firefox and derivatives | +| | (including ESR), Chrome and Chromium derivatives, Safari and WebKit derivatives. | ++----------------------+-----------------------------------------------------------------------------------------+ + +Mobile device (smartphone/tablet) - Minimum +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------+-----------------------------------------------------------------------------------------+ +| **CPU** | - **Android:** SoC with any 32-bit or 64-bit ARM or x86 CPU | +| | | +| | - *Example: Qualcomm Snapdragon 430, Samsung Exynos 5 Octa 5430* | +| | | +| | - **iOS:** SoC with any 64-bit ARM CPU | +| | | +| | - *Example: Apple A7 (iPhone 5S)* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ renderer:** SoC featuring GPU with full Vulkan 1.0 support, or | +| | Metal 3 support (iOS/iPadOS) | +| | | +| | - *Example (Vulkan): Qualcomm Adreno 505, Mali-G71 MP2, Apple A12 (iPhone XR/XS)* | +| | - *Example (Metal): Apple A11 (iPhone 8/X)* | +| | | +| | - **Mobile renderer:** SoC featuring GPU with full Vulkan 1.0 support, or | +| | Metal 3 support (iOS/iPadOS) | +| | | +| | - *Example (Vulkan): Qualcomm Adreno 505, Mali-G71 MP2, Apple A12 (iPhone XR/XS)* | +| | - *Example (Metal): Apple A11 (iPhone 8/X)* | +| | | +| | - **Compatibility renderer:** SoC featuring GPU with full OpenGL ES 3.0 support | +| | | +| | - *Example: Qualcomm Adreno 306, Mali-T628 MP6, Apple A7 (iPhone 5S)* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **RAM** | - **For native exports:** 1 GB | +| | - **For web exports:** 2 GB | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Storage** | 150 MB (used for the executable, project files and cache) | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Operating system** | - **For native exports:** Android 6.0 (Compatibility), Android 9.0 (Forward+/Mobile), | +| | iOS 12.0 (Forward+/Mobile, Vulkan), iOS 16.0 (Forward+/Mobile, Metal) | +| | - **Web editor:** Recent versions of mainstream browsers: Firefox and derivatives | +| | (including ESR), Chrome and Chromium derivatives, Safari and WebKit derivatives. | ++----------------------+-----------------------------------------------------------------------------------------+ + +These are the **recommended** specifications to get a smooth experience with a +simple 2D or 3D project exported with Godot: + +Desktop or laptop PC - Recommended +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------+----------------------------------------------------------------------------------------------+ +| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 support, with 4 physical cores or more, ARMv8 CPU | +| | | +| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Snapdragon X Elite* | +| | | +| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) | +| | | +| | - *Example: Intel Core i5-8500, Apple M1* | +| | | +| | - **Linux:** x86_64 CPU with SSE4.2 support, with 4 physical cores or more, | +| | ARMv7 or ARMv8 CPU | +| | | +| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* | ++----------------------+----------------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ renderer:** Dedicated graphics with full Vulkan 1.2 support, | +| | Metal 3 support (macOS), or Direct3D 12 (12_0 feature level) support (Windows) | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Mobile renderer:** Dedicated graphics with full Vulkan 1.2 support, | +| | Metal 3 support (macOS), or Direct3D 12 (12_0 feature level) support (Windows) | +| | | +| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* | +| | | +| | - **Compatibility renderer:** Dedicated graphics with full OpenGL 4.6 support | +| | | +| | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* | ++----------------------+----------------------------------------------------------------------------------------------+ +| **RAM** | - **For native exports:** 4 GB | +| | - **For web exports:** 8 GB | ++----------------------+----------------------------------------------------------------------------------------------+ +| **Storage** | 150 MB (used for the executable, project files and cache) | ++----------------------+----------------------------------------------------------------------------------------------+ +| **Operating system** | - **For native exports:** Windows 10, macOS 10.15 (Forward+/Mobile, Vulkan), macOS 13.0 | +| | (Forward+/Mobile, Metal), Linux distribution released after 2020 | +| | - **For web exports:** Latest version of Firefox, Chrome, Edge, Safari, Opera | ++----------------------+----------------------------------------------------------------------------------------------+ + +Mobile device (smartphone/tablet) - Recommended +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------+-----------------------------------------------------------------------------------------+ +| **CPU** | - **Android:** SoC with 64-bit ARM or x86 CPU, with 3 "performance" cores or more | +| | | +| | - *Example: Qualcomm Snapdragon 845, Samsung Exynos 9810* | +| | | +| | - **iOS:** SoC with 64-bit ARM CPU | +| | | +| | - *Example: Apple A14 (iPhone 12)* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **GPU** | - **Forward+ renderer:** SoC featuring GPU with full Vulkan 1.2 support, or | +| | Metal 3 support (iOS/iPadOS) | +| | | +| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple A14 (iPhone 12)* | +| | | +| | - **Mobile renderer:** SoC featuring GPU with full Vulkan 1.2 support, or | +| | Metal 3 support (iOS/iPadOS) | +| | | +| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple A14 (iPhone 12)* | +| | | +| | - **Compatibility renderer:** SoC featuring GPU with full OpenGL ES 3.2 support | +| | | +| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple A14 (iPhone 12)* | ++----------------------+-----------------------------------------------------------------------------------------+ +| **RAM** | - **For native exports:** 2 GB | +| | - **For web exports:** 4 GB | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Storage** | 150 MB (used for the executable, project files and cache) | ++----------------------+-----------------------------------------------------------------------------------------+ +| **Operating system** | - **For native exports:** Android 9.0, iOS 14.1 (Forward+/Mobile, Vulkan), iOS 16.0 | +| | (Forward+/Mobile, Metal) | +| | - **For web exports:** Latest version of Firefox, Chrome, Edge, Safari, Opera, | +| | Samsung Internet | ++----------------------+-----------------------------------------------------------------------------------------+ + +.. note:: + + Godot doesn't use OpenGL/OpenGL ES extensions introduced after OpenGL + 3.3/OpenGL ES 3.0, but GPUs supporting newer OpenGL/OpenGL ES versions + generally have fewer driver issues. diff --git a/about/troubleshooting.rst b/about/troubleshooting.rst deleted file mode 100644 index 65b7defbd67..00000000000 --- a/about/troubleshooting.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. _doc_troubleshooting: - -Troubleshooting -=============== - -This page lists common issues encountered when using Godot and possible solutions. - -.. seealso:: - - See :ref:`doc_using_the_web_editor` for caveats specific to the HTML5 version - of the Godot editor. - -Everything I do in the editor or project manager appears delayed by one frame. ------------------------------------------------------------------------------- - -This is a `known bug `__ on -Intel graphics drivers on Windows. Updating to the latest graphics driver -version *provided by Intel* should fix the issue. - -You should use the graphics driver provided by Intel rather than the one -provided by your desktop or laptop's manufacturer because their version is often -outdated. - -The editor runs slowly and uses all my CPU and GPU resources, making my computer noisy. ---------------------------------------------------------------------------------------- - -This is a known issue, especially on macOS since most Macs have Retina displays. -Due to Retina displays' higher pixel density, everything has to be rendered at a -higher resolution. This increases the load on the GPU and decreases perceived -performance. - -There are several ways to improve performance and battery life: - -- In 3D, click the **Perspective** button in the top left corner and enable - **Half Resolution**. The 3D viewport will now be rendered at half resolution, - which can be up to 4 times faster. -- Open the Editor Settings and increase the value of **Low Processor Mode Sleep Usec** - to ``33000`` (30 FPS). This value determines the amount of *microseconds* - between frames to render. Higher values will make the editor feel less reactive, - but will help decrease CPU and GPU usage significantly. -- If you have a node that causes the editor to redraw continuously (such as - particles), hide it and show it using a script in the ``_ready()`` method. - This way, it will be hidden in the editor but will still be visible in the - running project. - -The editor stutters and flickers on my variable refresh rate monitor (G-Sync/FreeSync). ---------------------------------------------------------------------------------------- - -This is a `known issue `__. -There are two workarounds for this: - -- Enable **Interface > Editor > Update Continuously** in the Editor Settings. Keep in mind - this will increase power usage and heat/noise emissions, since the editor will - now be rendering constantly, even if nothing has changed on screen. To - alleviate this, you can increase **Low Processor Mode Sleep Usec** to - ``33000`` (30 FPS) in the Editor Settings. This value determines the amount of - *microseconds* between frames to render. Higher values will make the editor - feel less reactive, but will help decrease CPU and GPU usage significantly. -- Alternatively, disable variable refresh rate on your monitor or in the graphics driver. - -The grid disappears and meshes turn black when I rotate the 3D camera in the editor. ------------------------------------------------------------------------------------- - -This is a `known bug `__ on -Intel graphics drivers on Windows. - -The only workaround, for now, is to switch to the GLES2 renderer. You can switch -the renderer in the top-right corner of the editor or the Project Settings. - -If you use a computer allowing you to switch your graphics card, like NVIDIA -Optimus, you can use the dedicated graphics card to run Godot. - -The editor or project takes a very long time to start. ------------------------------------------------------- - -This is a `known bug `__ on -Windows when you have specific USB peripherals connected. In particular, -Corsair's iCUE software seems to cause the bug. Try updating your USB -peripherals' drivers to their latest version. If the bug persists, you need to -disconnect the faulty peripherals before opening the editor. You can then -connect the peripheral again. - -The Godot editor appears frozen after clicking the system console. ------------------------------------------------------------------- - -When running Godot on Windows with the system console enabled, you can -accidentally enable *selection mode* by clicking inside the command window. This -Windows-specific behavior pauses the application to let you select text inside -the system console. Godot cannot override this system-specific behavior. - -To solve this, select the system console window and press Enter to leave -selection mode. - -Some text such as "NO DC" appears in the top-left corner of the project manager and editor window. --------------------------------------------------------------------------------------------------- - -This is caused by the NVIDIA graphics driver injecting an overlay to display information. - -To disable this overlay on Windows, restore your graphics driver settings to the -default values in the NVIDIA Control Panel. - -To disable this overlay on Linux, open ``nvidia-settings``, go to **X Screen 0 > -OpenGL Settings** then uncheck **Enable Graphics API Visual Indicator**. - -The project window appears blurry, unlike the editor. ------------------------------------------------------ - -Unlike the editor, the project isn't marked as DPI-aware by default. This is -done to improve performance, especially on integrated graphics, where rendering -3D scenes in hiDPI is slow. - -To resolve this, open **Project > Project Settings** and enable **Display > -Window > Dpi > Allow Hidpi**. On top of that, make sure your project is -configured to support :ref:`multiple resolutions `. - -The project window doesn't appear centered when I run the project. ------------------------------------------------------------------- - -This is a `known bug `__. To -resolve this, open **Project > Project Settings** and enable **Display > Window -> Dpi > Allow Hidpi**. On top of that, make sure your project is configured to -support :ref:`multiple resolutions `. - -The project works when run from the editor, but fails to load some files when running from an exported copy. ------------------------------------------------------------------------------------------------------------- - -This is usually caused by forgetting to specify a filter for non-resource files -in the Export dialog. By default, Godot will only include actual *resources* -into the PCK file. Some files commonly used, such as JSON files, are not -considered resources. For example, if you load ``test.json`` in the exported -project, you need to specify ``*.json`` in the non-resource export filter. See -:ref:`doc_exporting_projects_export_mode` for more information. - -Also, note that files and folders whose name begin with a period will never be -included in the exported project. This is done to prevent version control -folders like ``.git`` from being included in the exported PCK file. - -On Windows, this can also be due to :ref:`case sensitivity -` issues. If you reference a resource -in your script with a different case than on the filesystem, loading will fail -once you export the project. This is because the virtual PCK filesystem is -case-sensitive, while Windows's filesystem is case-insensitive by default. diff --git a/classes/class_@c#.rst b/classes/class_@c#.rst deleted file mode 100644 index 99fd1a7607c..00000000000 --- a/classes/class_@c#.rst +++ /dev/null @@ -1,13 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the @C#.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_@C#: - -@C# -=== - - - diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index e16782b4a84..cae078bf5e6 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -1,1599 +1,1419 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the @GDScript.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/gdscript/doc_classes/@GDScript.xml. .. _class_@GDScript: @GDScript ========= -Built-in GDScript functions. +Built-in GDScript constants, functions, and annotations. + +.. rst-class:: classref-introduction-group Description ----------- -List of core built-in GDScript functions. Math functions and other utilities. Everything else is provided by objects. (Keywords: builtin, built in, global functions.) +A list of utility functions and annotations accessible from any script written in GDScript. + +For the list of global functions and constants that can be accessed in any scripting language, see :ref:`@GlobalScope`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`GDScript exports <../tutorials/scripting/gdscript/gdscript_exports>` + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`Color8` **(** :ref:`int` r8, :ref:`int` g8, :ref:`int` b8, :ref:`int` a8=255 **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`ColorN` **(** :ref:`String` name, :ref:`float` alpha=1.0 **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`abs` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`acos` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`asin` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`assert` **(** :ref:`bool` condition **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`atan` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`atan2` **(** :ref:`float` y, :ref:`float` x **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`bytes2var` **(** :ref:`PackedByteArray` bytes, :ref:`bool` allow_objects=false **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`cartesian2polar` **(** :ref:`float` x, :ref:`float` y **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`ceil` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`char` **(** :ref:`int` code **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`clamp` **(** :ref:`float` value, :ref:`float` min, :ref:`float` max **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`convert` **(** :ref:`Variant` what, :ref:`int` type **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`cos` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`cosh` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`db2linear` **(** :ref:`float` db **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`dectime` **(** :ref:`float` value, :ref:`float` amount, :ref:`float` step **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`deg2rad` **(** :ref:`float` deg **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Object` | :ref:`dict2inst` **(** :ref:`Dictionary` dict **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`ease` **(** :ref:`float` s, :ref:`float` curve **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`exp` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`floor` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`fmod` **(** :ref:`float` a, :ref:`float` b **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`fposmod` **(** :ref:`float` a, :ref:`float` b **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`FuncRef` | :ref:`funcref` **(** :ref:`Object` instance, :ref:`String` funcname **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_stack` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`hash` **(** :ref:`Variant` var **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Dictionary` | :ref:`inst2dict` **(** :ref:`Object` inst **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Object` | :ref:`instance_from_id` **(** :ref:`int` instance_id **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`inverse_lerp` **(** :ref:`float` from, :ref:`float` to, :ref:`float` weight **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_equal_approx` **(** :ref:`float` a, :ref:`float` b **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_inf` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_instance_valid` **(** :ref:`Object` instance **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_nan` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_zero_approx` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`len` **(** :ref:`Variant` var **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`lerp` **(** :ref:`Variant` from, :ref:`Variant` to, :ref:`float` weight **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`lerp_angle` **(** :ref:`float` from, :ref:`float` to, :ref:`float` weight **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`linear2db` **(** :ref:`float` nrg **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Resource` | :ref:`load` **(** :ref:`String` path **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`log` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`max` **(** :ref:`float` a, :ref:`float` b **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`min` **(** :ref:`float` a, :ref:`float` b **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`move_toward` **(** :ref:`float` from, :ref:`float` to, :ref:`float` delta **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`nearest_po2` **(** :ref:`int` value **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`ord` **(** :ref:`String` char **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`parse_json` **(** :ref:`String` json **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`polar2cartesian` **(** :ref:`float` r, :ref:`float` th **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`posmod` **(** :ref:`int` a, :ref:`int` b **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`pow` **(** :ref:`float` base, :ref:`float` exp **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Resource` | :ref:`preload` **(** :ref:`String` path **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`print` **(** ... **)** vararg | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`print_debug` **(** ... **)** vararg | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`print_stack` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`printerr` **(** ... **)** vararg | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`printraw` **(** ... **)** vararg | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`prints` **(** ... **)** vararg | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`printt` **(** ... **)** vararg | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`push_error` **(** :ref:`String` message **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`push_warning` **(** :ref:`String` message **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`rad2deg` **(** :ref:`float` rad **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`rand_range` **(** :ref:`float` from, :ref:`float` to **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`rand_seed` **(** :ref:`int` seed **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`randf` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`randi` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`randomize` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`range` **(** ... **)** vararg | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`range_lerp` **(** :ref:`float` value, :ref:`float` istart, :ref:`float` istop, :ref:`float` ostart, :ref:`float` ostop **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`round` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`seed` **(** :ref:`int` seed **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`sign` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`sin` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`sinh` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`smoothstep` **(** :ref:`float` from, :ref:`float` to, :ref:`float` weight **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`sqrt` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`step_decimals` **(** :ref:`float` step **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`stepify` **(** :ref:`float` s, :ref:`float` step **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`str` **(** ... **)** vararg | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`str2var` **(** :ref:`String` string **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`tan` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`tanh` **(** :ref:`float` s **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`to_json` **(** :ref:`Variant` var **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`type_exists` **(** :ref:`String` type **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`typeof` **(** :ref:`Variant` what **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`validate_json` **(** :ref:`String` json **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedByteArray` | :ref:`var2bytes` **(** :ref:`Variant` var, :ref:`bool` full_objects=false **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`var2str` **(** :ref:`Variant` var **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`WeakRef` | :ref:`weakref` **(** :ref:`Object` obj **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`wrapf` **(** :ref:`float` value, :ref:`float` min, :ref:`float` max **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`wrapi` **(** :ref:`int` value, :ref:`int` min, :ref:`int` max **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`GDScriptFunctionState` | :ref:`yield` **(** :ref:`Object` object=null, :ref:`String` signal="" **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`Color8`\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`assert`\ (\ condition\: :ref:`bool`, message\: :ref:`String` = ""\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`char`\ (\ code\: :ref:`int`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`convert`\ (\ what\: :ref:`Variant`, type\: :ref:`Variant.Type`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Object` | :ref:`dict_to_inst`\ (\ dictionary\: :ref:`Dictionary`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`get_stack`\ (\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`inst_to_dict`\ (\ instance\: :ref:`Object`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_instance_of`\ (\ value\: :ref:`Variant`, type\: :ref:`Variant`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`len`\ (\ var\: :ref:`Variant`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Resource` | :ref:`load`\ (\ path\: :ref:`String`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`ord`\ (\ char\: :ref:`String`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Resource` | :ref:`preload`\ (\ path\: :ref:`String`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`print_debug`\ (\ ...\ ) |vararg| | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`print_stack`\ (\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`range`\ (\ ...\ ) |vararg| | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`type_exists`\ (\ type\: :ref:`StringName`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Constants --------- .. _class_@GDScript_constant_PI: -.. _class_@GDScript_constant_TAU: +.. rst-class:: classref-constant -.. _class_@GDScript_constant_INF: +**PI** = ``3.14159265358979`` :ref:`🔗` -.. _class_@GDScript_constant_NAN: +Constant that represents how many times the diameter of a circle fits around its perimeter. This is equivalent to ``TAU / 2``, or 180 degrees in rotations. -- **PI** = **3.141593** --- Constant that represents how many times the diameter of a circle fits around its perimeter. +.. _class_@GDScript_constant_TAU: -- **TAU** = **6.283185** --- The circle constant, the circumference of the unit circle. +.. rst-class:: classref-constant -- **INF** = **inf** --- A positive infinity. (For negative infinity, use -INF). +**TAU** = ``6.28318530717959`` :ref:`🔗` -- **NAN** = **nan** --- Macro constant that expands to an expression of type float that represents a NaN. +The circle constant, the circumference of the unit circle in radians. This is equivalent to ``PI * 2``, or 360 degrees in rotations. -The NaN values are used to identify undefined or non-representable values for floating-point elements, such as the square root of negative numbers or the result of 0/0. +.. _class_@GDScript_constant_INF: -Method Descriptions -------------------- +.. rst-class:: classref-constant -.. _class_@GDScript_method_Color8: +**INF** = ``inf`` :ref:`🔗` -- :ref:`Color` **Color8** **(** :ref:`int` r8, :ref:`int` g8, :ref:`int` b8, :ref:`int` a8=255 **)** +Positive floating-point infinity. This is the result of floating-point division when the divisor is ``0.0``. For negative infinity, use ``-INF``. Dividing by ``-0.0`` will result in negative infinity if the numerator is positive, so dividing by ``0.0`` is not the same as dividing by ``-0.0`` (despite ``0.0 == -0.0`` returning ``true``). -Returns a color constructed from integer red, green, blue, and alpha channels. Each channel should have 8 bits of information ranging from 0 to 255. +\ **Warning:** Numeric infinity is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer number by ``0`` will not result in :ref:`INF` and will result in a run-time error instead. -``r8`` red channel +.. _class_@GDScript_constant_NAN: -``g8`` green channel +.. rst-class:: classref-constant -``b8`` blue channel +**NAN** = ``nan`` :ref:`🔗` -``a8`` alpha channel +"Not a Number", an invalid floating-point value. It is returned by some invalid operations, such as dividing floating-point ``0.0`` by ``0.0``. -:: +\ :ref:`NAN` has special properties, including that ``!=`` always returns ``true``, while other comparison operators always return ``false``. This is true even when comparing with itself (``NAN == NAN`` returns ``false`` and ``NAN != NAN`` returns ``true``). Due to this, you must use :ref:`@GlobalScope.is_nan()` to check whether a number is equal to :ref:`NAN`. - red = Color8(255, 0, 0) +\ **Warning:** "Not a Number" is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer ``0`` by ``0`` will not result in :ref:`NAN` and will result in a run-time error instead. ----- +.. rst-class:: classref-section-separator -.. _class_@GDScript_method_ColorN: +---- -- :ref:`Color` **ColorN** **(** :ref:`String` name, :ref:`float` alpha=1.0 **)** +.. rst-class:: classref-descriptions-group -Returns a color according to the standardized ``name`` with ``alpha`` ranging from 0 to 1. +Annotations +----------- -:: +.. _class_@GDScript_annotation_@abstract: - red = ColorN("red", 1) +.. rst-class:: classref-annotation -Supported color names are the same as the constants defined in :ref:`Color`. +**@abstract**\ (\ ) :ref:`🔗` ----- +Marks a class or a method as abstract. -.. _class_@GDScript_method_abs: +An abstract class is a class that cannot be instantiated directly. Instead, it is meant to be inherited by other classes. Attempting to instantiate an abstract class will result in an error. -- :ref:`float` **abs** **(** :ref:`float` s **)** +An abstract method is a method that has no implementation. Therefore, a newline or a semicolon is expected after the function header. This defines a contract that inheriting classes must conform to, because the method signature must be compatible when overriding. -Returns the absolute value of parameter ``s`` (i.e. unsigned value, works for integer and float). +Inheriting classes must either provide implementations for all abstract methods, or the inheriting class must be marked as abstract. If a class has at least one abstract method (either its own or an unimplemented inherited one), then it must also be marked as abstract. However, the reverse is not true: an abstract class is allowed to have no abstract methods. :: - # a is 1 - a = abs(-1) - ----- - -.. _class_@GDScript_method_acos: - -- :ref:`float` **acos** **(** :ref:`float` s **)** + @abstract class Shape: + @abstract func draw() -Returns the arc cosine of ``s`` in radians. Use to get the angle of cosine ``s``. + class Circle extends Shape: + func draw(): + print("Drawing a circle.") -:: + class Square extends Shape: + func draw(): + print("Drawing a square.") - # c is 0.523599 or 30 degrees if converted with rad2deg(s) - c = acos(0.866025) +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_asin: +.. _class_@GDScript_annotation_@export: -- :ref:`float` **asin** **(** :ref:`float` s **)** +.. rst-class:: classref-annotation -Returns the arc sine of ``s`` in radians. Use to get the angle of sine ``s``. +**@export**\ (\ ) :ref:`🔗` + +Mark the following property as exported (editable in the Inspector dock and saved to disk). To control the type of the exported property, use the type hint notation. :: - # s is 0.523599 or 30 degrees if converted with rad2deg(s) - s = asin(0.5) + extends Node ----- + enum Direction {LEFT, RIGHT, UP, DOWN} -.. _class_@GDScript_method_assert: + # Built-in types. + @export var string = "" + @export var int_number = 5 + @export var float_number: float = 5 -- void **assert** **(** :ref:`bool` condition **)** + # Enums. + @export var type: Variant.Type + @export var format: Image.Format + @export var direction: Direction -Asserts that the ``condition`` is ``true`` . If the ``condition`` is ``false``, an error is generated and the program is halted until you resume it. Only executes in debug builds, or when running the game from the editor. Use it for debugging purposes, to make sure a statement is ``true`` during development. + # Resources. + @export var image: Image + @export var custom_resource: CustomResource -:: + # Nodes. + @export var node: Node + @export var custom_node: CustomNode - # Imagine we always want speed to be between 0 and 20 - speed = -10 - assert(speed < 20) # True, the program will continue - assert(speed >= 0) # False, the program will stop - assert(speed >= 0 && speed < 20) # You can also combine the two conditional statements in one check + # Typed arrays. + @export var int_array: Array[int] + @export var direction_array: Array[Direction] + @export var image_array: Array[Image] + @export var node_array: Array[Node] ----- +\ **Note:** Custom resources and nodes should be registered as global classes using ``class_name``, since the Inspector currently only supports global classes. Otherwise, a less specific type will be exported instead. -.. _class_@GDScript_method_atan: +\ **Note:** Node export is only supported in :ref:`Node`-derived classes and has a number of other limitations. -- :ref:`float` **atan** **(** :ref:`float` s **)** +.. rst-class:: classref-item-separator -Returns the arc tangent of ``s`` in radians. Use it to get the angle from an angle's tangent in trigonometry: ``atan(tan(angle)) == angle``. +---- -The method cannot know in which quadrant the angle should fall. See :ref:`atan2` if you always want an exact angle. +.. _class_@GDScript_annotation_@export_category: -:: +.. rst-class:: classref-annotation - a = atan(0.5) # a is 0.463648 +**@export_category**\ (\ name\: :ref:`String`\ ) :ref:`🔗` ----- +Define a new category for the following exported properties. This helps to organize properties in the Inspector dock. -.. _class_@GDScript_method_atan2: +See also :ref:`@GlobalScope.PROPERTY_USAGE_CATEGORY`. -- :ref:`float` **atan2** **(** :ref:`float` y, :ref:`float` x **)** +:: -Returns the arc tangent of ``y/x`` in radians. Use to get the angle of tangent ``y/x``. To compute the value, the method takes into account the sign of both arguments in order to determine the quadrant. + @export_category("Statistics") + @export var hp = 30 + @export var speed = 1.25 -:: +\ **Note:** Categories in the Inspector dock's list usually divide properties coming from different classes (Node, Node2D, Sprite, etc.). For better clarity, it's recommended to use :ref:`@export_group` and :ref:`@export_subgroup`, instead. - a = atan2(0, -1) # a is 3.141593 +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_bytes2var: +.. _class_@GDScript_annotation_@export_color_no_alpha: -- :ref:`Variant` **bytes2var** **(** :ref:`PackedByteArray` bytes, :ref:`bool` allow_objects=false **)** +.. rst-class:: classref-annotation -Decodes a byte array back to a value. When ``allow_objects`` is ``true`` decoding objects is allowed. +**@export_color_no_alpha**\ (\ ) :ref:`🔗` -**WARNING:** Deserialized object can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats (remote code execution). +Export a :ref:`Color`, :ref:`Array`\ \[:ref:`Color`\ \], or :ref:`PackedColorArray` property without allowing its transparency (:ref:`Color.a`) to be edited. ----- +See also :ref:`@GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA`. -.. _class_@GDScript_method_cartesian2polar: +:: -- :ref:`Vector2` **cartesian2polar** **(** :ref:`float` x, :ref:`float` y **)** + @export_color_no_alpha var dye_color: Color + @export_color_no_alpha var dye_colors: Array[Color] -Converts a 2D point expressed in the cartesian coordinate system (X and Y axis) to the polar coordinate system (a distance from the origin and an angle). +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_ceil: +.. _class_@GDScript_annotation_@export_custom: + +.. rst-class:: classref-annotation -- :ref:`float` **ceil** **(** :ref:`float` s **)** +**@export_custom**\ (\ hint\: :ref:`PropertyHint`, hint_string\: :ref:`String`, usage\: |bitfield|\[:ref:`PropertyUsageFlags`\] = 6\ ) :ref:`🔗` -Rounds ``s`` upward, returning the smallest integral value that is not less than ``s``. +Allows you to set a custom hint, hint string, and usage flags for the exported property. Note that there's no validation done in GDScript, it will just pass the parameters to the editor. :: - i = ceil(1.45) # i is 2 - i = ceil(1.001) # i is 2 + @export_custom(PROPERTY_HINT_NONE, "suffix:m") var suffix: Vector3 + +\ **Note:** Regardless of the ``usage`` value, the :ref:`@GlobalScope.PROPERTY_USAGE_SCRIPT_VARIABLE` flag is always added, as with any explicitly declared script variable. + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_char: +.. _class_@GDScript_annotation_@export_dir: -- :ref:`String` **char** **(** :ref:`int` code **)** +.. rst-class:: classref-annotation -Returns a character as a String of the given Unicode code point (which is compatible with ASCII code). +**@export_dir**\ (\ ) :ref:`🔗` + +Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property as a path to a directory. The path will be limited to the project folder and its subfolders. See :ref:`@export_global_dir` to allow picking from the entire filesystem. + +See also :ref:`@GlobalScope.PROPERTY_HINT_DIR`. :: - a = char(65) # a is "A" - a = char(65 + 32) # a is "a" - a = char(8364) # a is "€" + @export_dir var sprite_folder_path: String + @export_dir var sprite_folder_paths: Array[String] -This is the inverse of :ref:`ord`. +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_clamp: +.. _class_@GDScript_annotation_@export_enum: -- :ref:`float` **clamp** **(** :ref:`float` value, :ref:`float` min, :ref:`float` max **)** +.. rst-class:: classref-annotation -Clamps ``value`` and returns a value not less than ``min`` and not more than ``max``. +**@export_enum**\ (\ names\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` -:: +Export an :ref:`int`, :ref:`String`, :ref:`Array`\ \[:ref:`int`\ \], :ref:`Array`\ \[:ref:`String`\ \], :ref:`PackedByteArray`, :ref:`PackedInt32Array`, :ref:`PackedInt64Array`, or :ref:`PackedStringArray` property as an enumerated list of options (or an array of options). If the property is an :ref:`int`, then the index of the value is stored, in the same order the values are provided. You can add explicit values using a colon. If the property is a :ref:`String`, then the value is stored. - speed = 1000 - # a is 20 - a = clamp(speed, 1, 20) - - speed = -10 - # a is 1 - a = clamp(speed, 1, 20) +See also :ref:`@GlobalScope.PROPERTY_HINT_ENUM`. ----- +:: -.. _class_@GDScript_method_convert: + @export_enum("Warrior", "Magician", "Thief") var character_class: int + @export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int + @export_enum("Rebecca", "Mary", "Leah") var character_name: String -- :ref:`Variant` **convert** **(** :ref:`Variant` what, :ref:`int` type **)** + @export_enum("Sword", "Spear", "Mace") var character_items: Array[int] + @export_enum("double_jump", "climb", "dash") var character_skills: Array[String] -Converts from a type to another in the best way possible. The ``type`` parameter uses the :ref:`Variant.Type` values. +If you want to set an initial value, you must specify it explicitly: :: - a = Vector2(1, 0) - # Prints 1 - print(a.length()) - a = convert(a, TYPE_STRING) - # Prints 6 as "(1, 0)" is 6 characters - print(a.length()) - ----- + @export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca" -.. _class_@GDScript_method_cos: +If you want to use named GDScript enums, then use :ref:`@export` instead: -- :ref:`float` **cos** **(** :ref:`float` s **)** +:: -Returns the cosine of angle ``s`` in radians. + enum CharacterName {REBECCA, MARY, LEAH} + @export var character_name: CharacterName -:: + enum CharacterItem {SWORD, SPEAR, MACE} + @export var character_items: Array[CharacterItem] - # Prints 1 then -1 - print(cos(PI * 2)) - print(cos(PI)) +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_cosh: +.. _class_@GDScript_annotation_@export_exp_easing: -- :ref:`float` **cosh** **(** :ref:`float` s **)** +.. rst-class:: classref-annotation -Returns the hyperbolic cosine of ``s`` in radians. +**@export_exp_easing**\ (\ hints\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` -:: - - # Prints 1.543081 - print(cosh(1)) +Export a floating-point property with an easing editor widget. Additional hints can be provided to adjust the behavior of the widget. ``"attenuation"`` flips the curve, which makes it more intuitive for editing attenuation properties. ``"positive_only"`` limits values to only be greater than or equal to zero. ----- +See also :ref:`@GlobalScope.PROPERTY_HINT_EXP_EASING`. -.. _class_@GDScript_method_db2linear: +:: -- :ref:`float` **db2linear** **(** :ref:`float` db **)** + @export_exp_easing var transition_speed + @export_exp_easing("attenuation") var fading_attenuation + @export_exp_easing("positive_only") var effect_power + @export_exp_easing var speeds: Array[float] -Converts from decibels to linear energy (audio). +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_dectime: +.. _class_@GDScript_annotation_@export_file: -- :ref:`float` **dectime** **(** :ref:`float` value, :ref:`float` amount, :ref:`float` step **)** +.. rst-class:: classref-annotation -Returns the result of ``value`` decreased by ``step`` \* ``amount``. +**@export_file**\ (\ filter\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` -:: - - # a = 59 - a = dectime(60, 10, 0.1)) - ----- - -.. _class_@GDScript_method_deg2rad: +Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property as a path to a file. The path will be limited to the project folder and its subfolders. See :ref:`@export_global_file` to allow picking from the entire filesystem. -- :ref:`float` **deg2rad** **(** :ref:`float` deg **)** +If ``filter`` is provided, only matching files will be available for picking. -Returns degrees converted to radians. +See also :ref:`@GlobalScope.PROPERTY_HINT_FILE`. :: - # r is 3.141593 - r = deg2rad(180) + @export_file var sound_effect_path: String + @export_file("*.txt") var notes_path: String + @export_file var level_paths: Array[String] ----- +\ **Note:** The file will be stored and referenced as UID, if available. This ensures that the reference is valid even when the file is moved. You can use :ref:`ResourceUID` methods to convert it to path. -.. _class_@GDScript_method_dict2inst: +.. rst-class:: classref-item-separator -- :ref:`Object` **dict2inst** **(** :ref:`Dictionary` dict **)** +---- -Converts a previously converted instance to a dictionary, back into an instance. Useful for deserializing. +.. _class_@GDScript_annotation_@export_file_path: ----- +.. rst-class:: classref-annotation -.. _class_@GDScript_method_ease: +**@export_file_path**\ (\ filter\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` -- :ref:`float` **ease** **(** :ref:`float` s, :ref:`float` curve **)** +Same as :ref:`@export_file`, except the file will be stored as a raw path. This means that it may become invalid when the file is moved. If you are exporting a :ref:`Resource` path, consider using :ref:`@export_file` instead. -Easing function, based on exponent. 0 is constant, 1 is linear, 0 to 1 is ease-in, 1+ is ease out. Negative values are in-out/out in. +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_exp: +.. _class_@GDScript_annotation_@export_flags: -- :ref:`float` **exp** **(** :ref:`float` s **)** +.. rst-class:: classref-annotation -The natural exponential function. It raises the mathematical constant **e** to the power of ``s`` and returns it. +**@export_flags**\ (\ names\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` -**e** has an approximate value of 2.71828. +Export an integer property as a bit flag field. This allows to store several "checked" or ``true`` values with one property, and comfortably select them from the Inspector dock. -For exponents to other bases use the method :ref:`pow`. +See also :ref:`@GlobalScope.PROPERTY_HINT_FLAGS`. :: - a = exp(2) # Approximately 7.39 + @export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0 ----- +You can add explicit values using a colon: -.. _class_@GDScript_method_floor: +:: -- :ref:`float` **floor** **(** :ref:`float` s **)** + @export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0 -Rounds ``s`` to the closest smaller integer and returns it. +You can also combine several flags: :: - # a is 2.0 - a = floor(2.99) - # a is -3.0 - a = floor(-2.99) + @export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16") + var spell_targets = 0 -**Note:** This method returns a float. If you need an integer, you can use ``int(s)`` directly. +\ **Note:** A flag value must be at least ``1`` and at most ``2 ** 32 - 1``. ----- +\ **Note:** Unlike :ref:`@export_enum`, the previous explicit value is not taken into account. In the following example, A is 16, B is 2, C is 4. -.. _class_@GDScript_method_fmod: +:: -- :ref:`float` **fmod** **(** :ref:`float` a, :ref:`float` b **)** + @export_flags("A:16", "B", "C") var x -Returns the floating-point remainder of ``a/b``, keeping the sign of ``a``. +You can also use the annotation on :ref:`Array`\ \[:ref:`int`\ \], :ref:`PackedByteArray`, :ref:`PackedInt32Array`, and :ref:`PackedInt64Array`\ :: - # Remainder is 1.5 - var remainder = fmod(7, 5.5) + @export_flags("Fire", "Water", "Earth", "Wind") var phase_elements: Array[int] -For the integer remainder operation, use the % operator. +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_fposmod: +.. _class_@GDScript_annotation_@export_flags_2d_navigation: -- :ref:`float` **fposmod** **(** :ref:`float` a, :ref:`float` b **)** +.. rst-class:: classref-annotation -Returns the floating-point modulus of ``a/b`` that wraps equally in positive and negative. - -:: +**@export_flags_2d_navigation**\ (\ ) :ref:`🔗` - var i = -6 - while i < 5: - prints(i, fposmod(i, 3)) - i += 1 +Export an integer property as a bit flag field for 2D navigation layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/2d_navigation/layer_1`. -Produces: +See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_NAVIGATION`. :: - -6 0 - -5 1 - -4 2 - -3 0 - -2 1 - -1 2 - 0 0 - 1 1 - 2 2 - 3 0 - 4 1 - ----- - -.. _class_@GDScript_method_funcref: - -- :ref:`FuncRef` **funcref** **(** :ref:`Object` instance, :ref:`String` funcname **)** + @export_flags_2d_navigation var navigation_layers: int + @export_flags_2d_navigation var navigation_layers_array: Array[int] -Returns a reference to the specified function ``funcname`` in the ``instance`` node. As functions aren't first-class objects in GDscript, use ``funcref`` to store a :ref:`FuncRef` in a variable and call it later. - -:: - - func foo(): - return("bar") - - a = funcref(self, "foo") - print(a.call_func()) # Prints bar +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_get_stack: +.. _class_@GDScript_annotation_@export_flags_2d_physics: -- :ref:`Array` **get_stack** **(** **)** +.. rst-class:: classref-annotation -Returns an array of dictionaries representing the current call stack. +**@export_flags_2d_physics**\ (\ ) :ref:`🔗` -:: +Export an integer property as a bit flag field for 2D physics layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/2d_physics/layer_1`. - func _ready(): - foo() - - func foo(): - bar() - - func bar(): - print(get_stack()) - -would print +See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_PHYSICS`. :: - [{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}] - ----- - -.. _class_@GDScript_method_hash: - -- :ref:`int` **hash** **(** :ref:`Variant` var **)** + @export_flags_2d_physics var physics_layers: int + @export_flags_2d_physics var physics_layers_array: Array[int] -Returns the integer hash of the variable passed. +.. rst-class:: classref-item-separator -:: +---- - print(hash("a")) # Prints 177670 +.. _class_@GDScript_annotation_@export_flags_2d_render: ----- +.. rst-class:: classref-annotation -.. _class_@GDScript_method_inst2dict: +**@export_flags_2d_render**\ (\ ) :ref:`🔗` -- :ref:`Dictionary` **inst2dict** **(** :ref:`Object` inst **)** +Export an integer property as a bit flag field for 2D render layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/2d_render/layer_1`. -Returns the passed instance converted to a dictionary (useful for serializing). +See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_RENDER`. :: - var foo = "bar" - func _ready(): - var d = inst2dict(self) - print(d.keys()) - print(d.values()) + @export_flags_2d_render var render_layers: int + @export_flags_2d_render var render_layers_array: Array[int] -Prints out: +.. rst-class:: classref-item-separator -:: +---- - [@subpath, @path, foo] - [, res://test.gd, bar] +.. _class_@GDScript_annotation_@export_flags_3d_navigation: ----- +.. rst-class:: classref-annotation -.. _class_@GDScript_method_instance_from_id: +**@export_flags_3d_navigation**\ (\ ) :ref:`🔗` -- :ref:`Object` **instance_from_id** **(** :ref:`int` instance_id **)** +Export an integer property as a bit flag field for 3D navigation layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/3d_navigation/layer_1`. -Returns the Object that corresponds to ``instance_id``. All Objects have a unique instance ID. +See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_NAVIGATION`. :: - var foo = "bar" - func _ready(): - var id = get_instance_id() - var inst = instance_from_id(id) - print(inst.foo) # Prints bar + @export_flags_3d_navigation var navigation_layers: int + @export_flags_3d_navigation var navigation_layers_array: Array[int] ----- +.. rst-class:: classref-item-separator -.. _class_@GDScript_method_inverse_lerp: +---- -- :ref:`float` **inverse_lerp** **(** :ref:`float` from, :ref:`float` to, :ref:`float` weight **)** +.. _class_@GDScript_annotation_@export_flags_3d_physics: -Returns a normalized value considering the given range. This is the opposite of :ref:`lerp`. +.. rst-class:: classref-annotation -:: +**@export_flags_3d_physics**\ (\ ) :ref:`🔗` - var middle = lerp(20, 30, 0.75) - # `middle` is now 27.5. - # Now, we pretend to have forgotten the original ratio and want to get it back. - var ratio = inverse_lerp(20, 30, 27.5) - # `ratio` is now 0.75. +Export an integer property as a bit flag field for 3D physics layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/3d_physics/layer_1`. ----- +See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_PHYSICS`. -.. _class_@GDScript_method_is_equal_approx: +:: -- :ref:`bool` **is_equal_approx** **(** :ref:`float` a, :ref:`float` b **)** + @export_flags_3d_physics var physics_layers: int + @export_flags_3d_physics var physics_layers_array: Array[int] -Returns ``true`` if ``a`` and ``b`` are approximately equal to each other. +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_is_inf: +.. _class_@GDScript_annotation_@export_flags_3d_render: -- :ref:`bool` **is_inf** **(** :ref:`float` s **)** +.. rst-class:: classref-annotation -Returns whether ``s`` is an infinity value (either positive infinity or negative infinity). +**@export_flags_3d_render**\ (\ ) :ref:`🔗` ----- +Export an integer property as a bit flag field for 3D render layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/3d_render/layer_1`. -.. _class_@GDScript_method_is_instance_valid: +See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_RENDER`. + +:: -- :ref:`bool` **is_instance_valid** **(** :ref:`Object` instance **)** + @export_flags_3d_render var render_layers: int + @export_flags_3d_render var render_layers_array: Array[int] -Returns whether ``instance`` is a valid object (e.g. has not been deleted from memory). +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_is_nan: +.. _class_@GDScript_annotation_@export_flags_avoidance: -- :ref:`bool` **is_nan** **(** :ref:`float` s **)** +.. rst-class:: classref-annotation -Returns whether ``s`` is a NaN (Not-A-Number) value. +**@export_flags_avoidance**\ (\ ) :ref:`🔗` ----- +Export an integer property as a bit flag field for navigation avoidance layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/avoidance/layer_1`. + +See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_AVOIDANCE`. -.. _class_@GDScript_method_is_zero_approx: +:: -- :ref:`bool` **is_zero_approx** **(** :ref:`float` s **)** + @export_flags_avoidance var avoidance_layers: int + @export_flags_avoidance var avoidance_layers_array: Array[int] -Returns ``true`` if ``s`` is zero or almost zero. +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_len: +.. _class_@GDScript_annotation_@export_global_dir: + +.. rst-class:: classref-annotation -- :ref:`int` **len** **(** :ref:`Variant` var **)** +**@export_global_dir**\ (\ ) :ref:`🔗` -Returns length of Variant ``var``. Length is the character count of String, element count of Array, size of Dictionary, etc. +Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property as an absolute path to a directory. The path can be picked from the entire filesystem. See :ref:`@export_dir` to limit it to the project folder and its subfolders. -**Note:** Generates a fatal error if Variant can not provide a length. +See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_DIR`. :: - a = [1, 2, 3, 4] - len(a) # Returns 4 + @export_global_dir var sprite_folder_path: String + @export_global_dir var sprite_folder_paths: Array[String] + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_lerp: +.. _class_@GDScript_annotation_@export_global_file: + +.. rst-class:: classref-annotation -- :ref:`Variant` **lerp** **(** :ref:`Variant` from, :ref:`Variant` to, :ref:`float` weight **)** +**@export_global_file**\ (\ filter\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` -Linearly interpolates between two values by a normalized value. This is the opposite of :ref:`inverse_lerp`. +Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property as an absolute path to a file. The path can be picked from the entire filesystem. See :ref:`@export_file` to limit it to the project folder and its subfolders. -If the ``from`` and ``to`` arguments are of type :ref:`int` or :ref:`float`, the return value is a :ref:`float`. +If ``filter`` is provided, only matching files will be available for picking. -If both are of the same vector type (:ref:`Vector2`, :ref:`Vector3` or :ref:`Color`), the return value will be of the same type (``lerp`` then calls the vector type's ``linear_interpolate`` method). +See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_FILE`. :: - lerp(0, 4, 0.75) # Returns 3.0 - lerp(Vector2(1, 5), Vector2(3, 2), 0.5) # Returns Vector2(2, 3.5) + @export_global_file var sound_effect_path: String + @export_global_file("*.txt") var notes_path: String + @export_global_file var multiple_paths: Array[String] + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_lerp_angle: +.. _class_@GDScript_annotation_@export_group: -- :ref:`float` **lerp_angle** **(** :ref:`float` from, :ref:`float` to, :ref:`float` weight **)** +.. rst-class:: classref-annotation -Linearly interpolates between two angles (in radians) by a normalized value. +**@export_group**\ (\ name\: :ref:`String`, prefix\: :ref:`String` = ""\ ) :ref:`🔗` -Similar to :ref:`lerp`, but interpolates correctly when the angles wrap around :ref:`TAU`. +Define a new group for the following exported properties. This helps to organize properties in the Inspector dock. Groups can be added with an optional ``prefix``, which would make group to only consider properties that have this prefix. The grouping will break on the first property that doesn't have a prefix. The prefix is also removed from the property's name in the Inspector dock. -:: +If no ``prefix`` is provided, then every following property will be added to the group. The group ends when then next group or category is defined. You can also force end a group by using this annotation with empty strings for parameters, ``@export_group("", "")``. - extends Sprite - var elapsed = 0.0 - func _process(delta): - var min_angle = deg2rad(0.0) - var max_angle = deg2rad(90.0) - rotation = lerp_angle(min_angle, max_angle, elapsed) - elapsed += delta +Groups cannot be nested, use :ref:`@export_subgroup` to add subgroups within groups. ----- +See also :ref:`@GlobalScope.PROPERTY_USAGE_GROUP`. -.. _class_@GDScript_method_linear2db: +:: -- :ref:`float` **linear2db** **(** :ref:`float` nrg **)** + @export_group("Racer Properties") + @export var nickname = "Nick" + @export var age = 26 -Converts from linear energy to decibels (audio). This can be used to implement volume sliders that behave as expected (since volume isn't linear). Example: + @export_group("Car Properties", "car_") + @export var car_label = "Speedy" + @export var car_number = 3 -:: + @export_group("", "") + @export var ungrouped_number = 3 - # "Slider" refers to a node that inherits Range such as HSlider or VSlider. - # Its range must be configured to go from 0 to 1. - # Change the bus name if you'd like to change the volume of a specific bus only. - AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear2db($Slider.value)) +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_load: +.. _class_@GDScript_annotation_@export_multiline: -- :ref:`Resource` **load** **(** :ref:`String` path **)** +.. rst-class:: classref-annotation -Loads a resource from the filesystem located at ``path``. +**@export_multiline**\ (\ ) :ref:`🔗` -**Note:** Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing **Copy Path**. +Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], :ref:`PackedStringArray`, :ref:`Dictionary` or :ref:`Array`\ \[:ref:`Dictionary`\ \] property with a large :ref:`TextEdit` widget instead of a :ref:`LineEdit`. This adds support for multiline content and makes it easier to edit large amount of text stored in the property. + +See also :ref:`@GlobalScope.PROPERTY_HINT_MULTILINE_TEXT`. :: - # Load a scene called main located in the root of the project directory. - var main = load("res://main.tscn") + @export_multiline var character_biography + @export_multiline var npc_dialogs: Array[String] -**Important:** The path must be absolute, a local path will just return ``null``. +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_log: - -- :ref:`float` **log** **(** :ref:`float` s **)** +.. _class_@GDScript_annotation_@export_node_path: -Natural logarithm. The amount of time needed to reach a certain level of continuous growth. +.. rst-class:: classref-annotation -**Note:** This is not the same as the "log" function on most calculators, which uses a base 10 logarithm. +**@export_node_path**\ (\ type\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` -:: +Export a :ref:`NodePath` or :ref:`Array`\ \[:ref:`NodePath`\ \] property with a filter for allowed node types. - log(10) # Returns 2.302585 +See also :ref:`@GlobalScope.PROPERTY_HINT_NODE_PATH_VALID_TYPES`. ----- +:: -.. _class_@GDScript_method_max: + @export_node_path("Button", "TouchScreenButton") var some_button + @export_node_path("Button", "TouchScreenButton") var many_buttons: Array[NodePath] -- :ref:`float` **max** **(** :ref:`float` a, :ref:`float` b **)** +\ **Note:** The type must be a native class or a globally registered script (using the ``class_name`` keyword) that inherits :ref:`Node`. -Returns the maximum of two values. +.. rst-class:: classref-item-separator -:: +---- - max(1, 2) # Returns 2 - max(-3.99, -4) # Returns -3.99 +.. _class_@GDScript_annotation_@export_placeholder: ----- +.. rst-class:: classref-annotation -.. _class_@GDScript_method_min: +**@export_placeholder**\ (\ placeholder\: :ref:`String`\ ) :ref:`🔗` -- :ref:`float` **min** **(** :ref:`float` a, :ref:`float` b **)** +Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property with a placeholder text displayed in the editor widget when no value is present. -Returns the minimum of two values. +See also :ref:`@GlobalScope.PROPERTY_HINT_PLACEHOLDER_TEXT`. :: - min(1, 2) # Returns 1 - min(-3.99, -4) # Returns -4 + @export_placeholder("Name in lowercase") var character_id: String + @export_placeholder("Name in lowercase") var friend_ids: Array[String] + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_move_toward: +.. _class_@GDScript_annotation_@export_range: -- :ref:`float` **move_toward** **(** :ref:`float` from, :ref:`float` to, :ref:`float` delta **)** +.. rst-class:: classref-annotation -Moves ``from`` toward ``to`` by the ``delta`` value. +**@export_range**\ (\ min\: :ref:`float`, max\: :ref:`float`, step\: :ref:`float` = 1.0, extra_hints\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` -Use a negative ``delta`` value to move away. +Export an :ref:`int`, :ref:`float`, :ref:`Array`\ \[:ref:`int`\ \], :ref:`Array`\ \[:ref:`float`\ \], :ref:`PackedByteArray`, :ref:`PackedInt32Array`, :ref:`PackedInt64Array`, :ref:`PackedFloat32Array`, or :ref:`PackedFloat64Array` property as a range value. The range must be defined by ``min`` and ``max``, as well as an optional ``step`` and a variety of extra hints. The ``step`` defaults to ``1`` for integer properties. For floating-point numbers this value depends on your :ref:`EditorSettings.interface/inspector/default_float_step` setting. -:: +If hints ``"or_greater"`` and ``"or_less"`` are provided, the editor widget will not cap the value at range boundaries. The ``"exp"`` hint will make the edited values on range to change exponentially. The ``"prefer_slider"`` hint will make integer values use the slider instead of arrows for editing, while ``"hide_control"`` will hide the element controlling the value of the editor widget. - move_toward(10, 5, 4) # Returns 6 +Hints also allow to indicate the units for the edited value. Using ``"radians_as_degrees"`` you can specify that the actual value is in radians, but should be displayed in degrees in the Inspector dock (the range values are also in degrees). ``"degrees"`` allows to add a degree sign as a unit suffix (the value is unchanged). Finally, a custom suffix can be provided using ``"suffix:unit"``, where "unit" can be any string. ----- +See also :ref:`@GlobalScope.PROPERTY_HINT_RANGE`. -.. _class_@GDScript_method_nearest_po2: +:: -- :ref:`int` **nearest_po2** **(** :ref:`int` value **)** + @export_range(0, 20) var number + @export_range(-10, 20) var number + @export_range(-10, 20, 0.2) var number: float + @export_range(0, 20) var numbers: Array[float] -Returns the nearest larger power of 2 for integer ``value``. + @export_range(0, 100, 1, "or_greater") var power_percent + @export_range(0, 100, 1, "or_greater", "or_less") var health_delta -:: + @export_range(-180, 180, 0.001, "radians_as_degrees") var angle_radians + @export_range(0, 360, 1, "degrees") var angle_degrees + @export_range(-8, 8, 2, "suffix:px") var target_offset - nearest_po2(3) # Returns 4 - nearest_po2(4) # Returns 4 - nearest_po2(5) # Returns 8 +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_ord: +.. _class_@GDScript_annotation_@export_storage: -- :ref:`int` **ord** **(** :ref:`String` char **)** +.. rst-class:: classref-annotation -Returns an integer representing the Unicode code point of the given Unicode character ``char``. +**@export_storage**\ (\ ) :ref:`🔗` + +Export a property with :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` flag. The property is not displayed in the editor, but it is serialized and stored in the scene or resource file. This can be useful for :ref:`@tool` scripts. Also the property value is copied when :ref:`Resource.duplicate()` or :ref:`Node.duplicate()` is called, unlike non-exported variables. :: - a = ord("A") # a is 65 - a = ord("a") # a is 97 - a = ord("€") # a is 8364 + var a # Not stored in the file, not displayed in the editor. + @export_storage var b # Stored in the file, not displayed in the editor. + @export var c: int # Stored in the file, displayed in the editor. -This is the inverse of :ref:`char`. +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_parse_json: +.. _class_@GDScript_annotation_@export_subgroup: -- :ref:`Variant` **parse_json** **(** :ref:`String` json **)** +.. rst-class:: classref-annotation -Parse JSON text to a Variant (use :ref:`typeof` to check if it is what you expect). +**@export_subgroup**\ (\ name\: :ref:`String`, prefix\: :ref:`String` = ""\ ) :ref:`🔗` -Be aware that the JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to :ref:`float` types. +Define a new subgroup for the following exported properties. This helps to organize properties in the Inspector dock. Subgroups work exactly like groups, except they need a parent group to exist. See :ref:`@export_group`. -Note that JSON objects do not preserve key order like Godot dictionaries, thus you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements: +See also :ref:`@GlobalScope.PROPERTY_USAGE_SUBGROUP`. :: - p = parse_json('["a", "b", "c"]') - if typeof(p) == TYPE_ARRAY: - print(p[0]) # Prints a - else: - print("unexpected results") - ----- - -.. _class_@GDScript_method_polar2cartesian: + @export_group("Racer Properties") + @export var nickname = "Nick" + @export var age = 26 -- :ref:`Vector2` **polar2cartesian** **(** :ref:`float` r, :ref:`float` th **)** + @export_subgroup("Car Properties", "car_") + @export var car_label = "Speedy" + @export var car_number = 3 -Converts a 2D point expressed in the polar coordinate system (a distance from the origin ``r`` and an angle ``th``) to the cartesian coordinate system (X and Y axis). +\ **Note:** Subgroups cannot be nested, but you can use the slash separator (``/``) to achieve the desired effect: ----- - -.. _class_@GDScript_method_posmod: - -- :ref:`int` **posmod** **(** :ref:`int` a, :ref:`int` b **)** +:: -Returns the integer modulus of ``a/b`` that wraps equally in positive and negative. + @export_group("Car Properties") + @export_subgroup("Wheels", "wheel_") + @export_subgroup("Wheels/Front", "front_wheel_") + @export var front_wheel_strength = 10 + @export var front_wheel_mobility = 5 + @export_subgroup("Wheels/Rear", "rear_wheel_") + @export var rear_wheel_strength = 8 + @export var rear_wheel_mobility = 3 + @export_subgroup("Wheels", "wheel_") + @export var wheel_material: PhysicsMaterial -:: +.. rst-class:: classref-item-separator - var i = -6 - while i < 5: - prints(i, posmod(i, 3)) - i += 1 +---- -Produces: +.. _class_@GDScript_annotation_@export_tool_button: -:: +.. rst-class:: classref-annotation - -6 0 - -5 1 - -4 2 - -3 0 - -2 1 - -1 2 - 0 0 - 1 1 - 2 2 - 3 0 - 4 1 +**@export_tool_button**\ (\ text\: :ref:`String`, icon\: :ref:`String` = ""\ ) :ref:`🔗` ----- +Export a :ref:`Callable` property as a clickable button with the label ``text``. When the button is pressed, the callable is called. -.. _class_@GDScript_method_pow: +If ``icon`` is specified, it is used to fetch an icon for the button via :ref:`Control.get_theme_icon()`, from the ``"EditorIcons"`` theme type. If ``icon`` is omitted, the default ``"Callable"`` icon is used instead. -- :ref:`float` **pow** **(** :ref:`float` base, :ref:`float` exp **)** +Consider using the :ref:`EditorUndoRedoManager` to allow the action to be reverted safely. -Returns the result of ``x`` raised to the power of ``y``. +See also :ref:`@GlobalScope.PROPERTY_HINT_TOOL_BUTTON`. :: - pow(2, 5) # Returns 32 + @tool + extends Sprite2D ----- + @export_tool_button("Hello") var hello_action = hello + @export_tool_button("Randomize the color!", "ColorRect") + var randomize_color_action = randomize_color -.. _class_@GDScript_method_preload: + func hello(): + print("Hello world!") -- :ref:`Resource` **preload** **(** :ref:`String` path **)** + func randomize_color(): + var undo_redo = EditorInterface.get_editor_undo_redo() + undo_redo.create_action("Randomized Sprite2D Color") + undo_redo.add_do_property(self, &"self_modulate", Color(randf(), randf(), randf())) + undo_redo.add_undo_property(self, &"self_modulate", self_modulate) + undo_redo.commit_action() -Returns a resource from the filesystem that is loaded during script parsing. +\ **Note:** The property is exported without the :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` flag because a :ref:`Callable` cannot be properly serialized and stored in a file. -**Note:** Resource paths can be obtained by right clicking on a resource in the Assets Panel and choosing "Copy Path". +\ **Note:** In an exported project neither :ref:`EditorInterface` nor :ref:`EditorUndoRedoManager` exist, which may cause some scripts to break. To prevent this, you can use :ref:`Engine.get_singleton()` and omit the static type from the variable declaration: :: - # Load a scene called main located in the root of the project directory. - var main = preload("res://main.tscn") + var undo_redo = Engine.get_singleton(&"EditorInterface").get_editor_undo_redo() + +\ **Note:** Avoid storing lambda callables in member variables of :ref:`RefCounted`-based classes (e.g. resources), as this can lead to memory leaks. Use only method callables and optionally :ref:`Callable.bind()` or :ref:`Callable.unbind()`. + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_print: +.. _class_@GDScript_annotation_@icon: + +.. rst-class:: classref-annotation -- void **print** **(** ... **)** vararg +**@icon**\ (\ icon_path\: :ref:`String`\ ) :ref:`🔗` -Converts one or more arguments to strings in the best way possible and prints them to the console. +Add a custom icon to the current script. The icon specified at ``icon_path`` is displayed in the Scene dock for every node of that class, as well as in various editor dialogs. :: - a = [1, 2, 3] - print("a", "b", a) # Prints ab[1, 2, 3] + @icon("res://path/to/class/icon.svg") ----- +\ **Note:** Only the script can have a custom icon. Inner classes are not supported. -.. _class_@GDScript_method_print_debug: +\ **Note:** As annotations describe their subject, the :ref:`@icon` annotation must be placed before the class definition and inheritance. -- void **print_debug** **(** ... **)** vararg +\ **Note:** Unlike most other annotations, the argument of the :ref:`@icon` annotation must be a string literal (constant expressions are not supported). -Like :ref:`print`, but prints only when used in debug mode. +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_print_stack: +.. _class_@GDScript_annotation_@onready: -- void **print_stack** **(** **)** +.. rst-class:: classref-annotation -Prints a stack track at code location, only works when running with debugger turned on. +**@onready**\ (\ ) :ref:`🔗` -Output in the console would look something like this: +Mark the following property as assigned when the :ref:`Node` is ready. Values for these properties are not assigned immediately when the node is initialized (:ref:`Object._init()`), and instead are computed and stored right before :ref:`Node._ready()`. :: - Frame 0 - res://test.gd:16 in function '_process' + @onready var character_name = $Label + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_printerr: +.. _class_@GDScript_annotation_@rpc: -- void **printerr** **(** ... **)** vararg +.. rst-class:: classref-annotation -Prints one or more arguments to strings in the best way possible to standard error line. +**@rpc**\ (\ mode\: :ref:`String` = "authority", sync\: :ref:`String` = "call_remote", transfer_mode\: :ref:`String` = "unreliable", transfer_channel\: :ref:`int` = 0\ ) :ref:`🔗` -:: +Mark the following method for remote procedure calls. See :doc:`High-level multiplayer <../tutorials/networking/high_level_multiplayer>`. - printerr("prints to stderr") +If ``mode`` is set as ``"any_peer"``, allows any peer to call this RPC function. Otherwise, only the authority peer is allowed to call it and ``mode`` should be kept as ``"authority"``. When configuring functions as RPCs with :ref:`Node.rpc_config()`, each of these modes respectively corresponds to the :ref:`MultiplayerAPI.RPC_MODE_AUTHORITY` and :ref:`MultiplayerAPI.RPC_MODE_ANY_PEER` RPC modes. See :ref:`RPCMode`. If a peer that is not the authority tries to call a function that is only allowed for the authority, the function will not be executed. If the error can be detected locally (when the RPC configuration is consistent between the local and the remote peer), an error message will be displayed on the sender peer. Otherwise, the remote peer will detect the error and print an error there. ----- +If ``sync`` is set as ``"call_remote"``, the function will only be executed on the remote peer, but not locally. To run this function locally too, set ``sync`` to ``"call_local"``. When configuring functions as RPCs with :ref:`Node.rpc_config()`, this is equivalent to setting ``call_local`` to ``true``. -.. _class_@GDScript_method_printraw: +The ``transfer_mode`` accepted values are ``"unreliable"``, ``"unreliable_ordered"``, or ``"reliable"``. It sets the transfer mode of the underlying :ref:`MultiplayerPeer`. See :ref:`MultiplayerPeer.transfer_mode`. -- void **printraw** **(** ... **)** vararg +The ``transfer_channel`` defines the channel of the underlying :ref:`MultiplayerPeer`. See :ref:`MultiplayerPeer.transfer_channel`. -Prints one or more arguments to strings in the best way possible to console. No newline is added at the end. +The order of ``mode``, ``sync`` and ``transfer_mode`` does not matter, but values related to the same argument must not be used more than once. ``transfer_channel`` always has to be the 4th argument (you must specify 3 preceding arguments). :: - printraw("A") - printraw("B") - # Prints AB + @rpc + func fn(): pass -**Note:** Due to limitations with Godot's built-in console, this only prints to the terminal. If you need to print in the editor, use another method, such as :ref:`print`. + @rpc("any_peer", "unreliable_ordered") + func fn_update_pos(): pass ----- + @rpc("authority", "call_remote", "unreliable", 0) # Equivalent to @rpc + func fn_default(): pass -.. _class_@GDScript_method_prints: +\ **Note:** Methods annotated with :ref:`@rpc` cannot receive objects which define required parameters in :ref:`Object._init()`. See :ref:`Object._init()` for more details. -- void **prints** **(** ... **)** vararg +.. rst-class:: classref-item-separator -Prints one or more arguments to the console with a space between each argument. +---- -:: +.. _class_@GDScript_annotation_@static_unload: - prints("A", "B", "C") # Prints A B C +.. rst-class:: classref-annotation ----- +**@static_unload**\ (\ ) :ref:`🔗` -.. _class_@GDScript_method_printt: +Make a script with static variables to not persist after all references are lost. If the script is loaded again the static variables will revert to their default values. -- void **printt** **(** ... **)** vararg +\ **Note:** As annotations describe their subject, the :ref:`@static_unload` annotation must be placed before the class definition and inheritance. -Prints one or more arguments to the console with a tab between each argument. +\ **Warning:** Currently, due to a bug, scripts are never freed, even if :ref:`@static_unload` annotation is used. -:: - - printt("A", "B", "C") # Prints A B C +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_push_error: +.. _class_@GDScript_annotation_@tool: -- void **push_error** **(** :ref:`String` message **)** +.. rst-class:: classref-annotation -Pushes an error message to Godot's built-in debugger and to the OS terminal. +**@tool**\ (\ ) :ref:`🔗` -:: +Mark the current script as a tool script, allowing it to be loaded and executed by the editor. See :doc:`Running code in the editor <../tutorials/plugins/running_code_in_the_editor>`. - push_error("test error") # Prints "test error" to debugger and terminal as error call +:: ----- + @tool + extends Node -.. _class_@GDScript_method_push_warning: +\ **Note:** As annotations describe their subject, the :ref:`@tool` annotation must be placed before the class definition and inheritance. -- void **push_warning** **(** :ref:`String` message **)** +.. rst-class:: classref-item-separator -Pushes a warning message to Godot's built-in debugger and to the OS terminal. +---- -:: +.. _class_@GDScript_annotation_@warning_ignore: - push_warning("test warning") # Prints "test warning" to debugger and terminal as warning call +.. rst-class:: classref-annotation ----- +**@warning_ignore**\ (\ warning\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` -.. _class_@GDScript_method_rad2deg: +Mark the following statement to ignore the specified ``warning``. See :doc:`GDScript warning system <../tutorials/scripting/gdscript/warning_system>`. -- :ref:`float` **rad2deg** **(** :ref:`float` rad **)** +:: -Converts from radians to degrees. + func test(): + print("hello") + return + @warning_ignore("unreachable_code") + print("unreachable") -:: +See also :ref:`@warning_ignore_start` and :ref:`@warning_ignore_restore`. - rad2deg(0.523599) # Returns 30 +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_rand_range: +.. _class_@GDScript_annotation_@warning_ignore_restore: -- :ref:`float` **rand_range** **(** :ref:`float` from, :ref:`float` to **)** +.. rst-class:: classref-annotation -Random range, any floating point value between ``from`` and ``to``. +**@warning_ignore_restore**\ (\ warning\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` -:: +Stops ignoring the listed warning types after :ref:`@warning_ignore_start`. Ignoring the specified warning types will be reset to Project Settings. This annotation can be omitted to ignore the warning types until the end of the file. - prints(rand_range(0, 1), rand_range(0, 1)) # Prints e.g. 0.135591 0.405263 +\ **Note:** Unlike most other annotations, arguments of the :ref:`@warning_ignore_restore` annotation must be string literals (constant expressions are not supported). + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_rand_seed: +.. _class_@GDScript_annotation_@warning_ignore_start: -- :ref:`Array` **rand_seed** **(** :ref:`int` seed **)** +.. rst-class:: classref-annotation -Random from seed: pass a ``seed``, and an array with both number and new seed is returned. "Seed" here refers to the internal state of the pseudo random number generator. The internal state of the current implementation is 64 bits. +**@warning_ignore_start**\ (\ warning\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` ----- +Starts ignoring the listed warning types until the end of the file or the :ref:`@warning_ignore_restore` annotation with the given warning type. -.. _class_@GDScript_method_randf: +:: -- :ref:`float` **randf** **(** **)** + func test(): + var a = 1 # Warning (if enabled in the Project Settings). + @warning_ignore_start("unused_variable") + var b = 2 # No warning. + var c = 3 # No warning. + @warning_ignore_restore("unused_variable") + var d = 4 # Warning (if enabled in the Project Settings). -Returns a random floating point value on the interval ``[0, 1]``. +\ **Note:** To suppress a single warning, use :ref:`@warning_ignore` instead. -:: +\ **Note:** Unlike most other annotations, arguments of the :ref:`@warning_ignore_start` annotation must be string literals (constant expressions are not supported). - randf() # Returns e.g. 0.375671 +.. rst-class:: classref-section-separator ---- -.. _class_@GDScript_method_randi: +.. rst-class:: classref-descriptions-group -- :ref:`int` **randi** **(** **)** +Method Descriptions +------------------- -Returns a random unsigned 32 bit integer. Use remainder to obtain a random value in the interval ``[0, N - 1]`` (where N is smaller than 2^32). +.. _class_@GDScript_method_Color8: -:: +.. rst-class:: classref-method - randi() # Returns random integer between 0 and 2^32 - 1 - randi() % 20 # Returns random integer between 0 and 19 - randi() % 100 # Returns random integer between 0 and 99 - randi() % 100 + 1 # Returns random integer between 1 and 100 +:ref:`Color` **Color8**\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) :ref:`🔗` ----- +**Deprecated:** Use :ref:`Color.from_rgba8()` instead. -.. _class_@GDScript_method_randomize: +Returns a :ref:`Color` constructed from red (``r8``), green (``g8``), blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by ``255.0`` for their final value. Using :ref:`Color8()` instead of the standard :ref:`Color` constructor is useful when you need to match exact color values in an :ref:`Image`. -- void **randomize** **(** **)** +:: -Randomizes the seed (or the internal state) of the random number generator. Current implementation reseeds using a number based on time. + var red = Color8(255, 0, 0) # Same as Color(1, 0, 0). + var dark_blue = Color8(0, 0, 51) # Same as Color(0, 0, 0.2). + var my_color = Color8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4). -:: +\ **Note:** Due to the lower precision of :ref:`Color8()` compared to the standard :ref:`Color` constructor, a color created with :ref:`Color8()` will generally not be equal to the same color created with the standard :ref:`Color` constructor. Use :ref:`Color.is_equal_approx()` for comparisons to avoid issues with floating-point precision error. - func _ready(): - randomize() +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_range: +.. _class_@GDScript_method_assert: -- :ref:`Array` **range** **(** ... **)** vararg +.. rst-class:: classref-method -Returns an array with the given range. Range can be 1 argument N (0 to N-1), two arguments (initial, final-1) or three arguments (initial, final-1, increment). +|void| **assert**\ (\ condition\: :ref:`bool`, message\: :ref:`String` = ""\ ) :ref:`🔗` -:: +Asserts that the ``condition`` is ``true``. If the ``condition`` is ``false``, an error is generated. When running from the editor, the running project will also be paused until you resume it. This can be used as a stronger form of :ref:`@GlobalScope.push_error()` for reporting errors to project developers or add-on users. - for i in range(4): - print(i) - for i in range(2, 5): - print(i) - for i in range(0, 6, 2): - print(i) +An optional ``message`` can be shown in addition to the generic "Assertion failed" message. You can use this to provide additional details about why the assertion failed. -Output: +\ **Warning:** For performance reasons, the code inside :ref:`assert()` is only executed in debug builds or when running the project from the editor. Don't include code that has side effects in an :ref:`assert()` call. Otherwise, the project will behave differently when exported in release mode. :: - 0 - 1 - 2 - 3 - - 2 - 3 - 4 - - 0 - 2 - 4 + # Imagine we always want speed to be between 0 and 20. + var speed = -10 + assert(speed < 20) # True, the program will continue. + assert(speed >= 0) # False, the program will stop. + assert(speed >= 0 and speed < 20) # You can also combine the two conditional statements in one check. + assert(speed < 20, "the speed limit is 20") # Show a message. + +\ **Note:** :ref:`assert()` is a keyword, not a function. So you cannot access it as a :ref:`Callable` or use it inside expressions. + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_range_lerp: +.. _class_@GDScript_method_char: -- :ref:`float` **range_lerp** **(** :ref:`float` value, :ref:`float` istart, :ref:`float` istop, :ref:`float` ostart, :ref:`float` ostop **)** +.. rst-class:: classref-method -Maps a ``value`` from range ``[istart, istop]`` to ``[ostart, ostop]``. +:ref:`String` **char**\ (\ code\: :ref:`int`\ ) :ref:`🔗` + +Returns a single character (as a :ref:`String` of length 1) of the given Unicode code point ``code``. :: - range_lerp(75, 0, 100, -1, 1) # Returns 0.5 + print(char(65)) # Prints "A" + print(char(129302)) # Prints "🤖" (robot face emoji) ----- +This is the inverse of :ref:`ord()`. See also :ref:`String.chr()` and :ref:`String.unicode_at()`. -.. _class_@GDScript_method_round: +.. rst-class:: classref-item-separator -- :ref:`float` **round** **(** :ref:`float` s **)** +---- -Returns the integral value that is nearest to ``s``, with halfway cases rounded away from zero. +.. _class_@GDScript_method_convert: -:: +.. rst-class:: classref-method - round(2.6) # Returns 3 +:ref:`Variant` **convert**\ (\ what\: :ref:`Variant`, type\: :ref:`Variant.Type`\ ) :ref:`🔗` ----- +**Deprecated:** Use :ref:`@GlobalScope.type_convert()` instead. -.. _class_@GDScript_method_seed: +Converts ``what`` to ``type`` in the best way possible. The ``type`` uses the :ref:`Variant.Type` values. -- void **seed** **(** :ref:`int` seed **)** +:: -Sets seed for the random number generator. + var a = [4, 2.5, 1.2] + print(a is Array) # Prints true -:: + var b = convert(a, TYPE_PACKED_BYTE_ARRAY) + print(b) # Prints [4, 2, 1] + print(b is Array) # Prints false - my_seed = "Godot Rocks" - seed(my_seed.hash()) +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_sign: +.. _class_@GDScript_method_dict_to_inst: -- :ref:`float` **sign** **(** :ref:`float` s **)** +.. rst-class:: classref-method -Returns the sign of ``s``: -1 or 1. Returns 0 if ``s`` is 0. +:ref:`Object` **dict_to_inst**\ (\ dictionary\: :ref:`Dictionary`\ ) :ref:`🔗` -:: +**Deprecated:** Consider using :ref:`JSON.to_native()` or :ref:`Object.get_property_list()` instead. - sign(-6) # Returns -1 - sign(0) # Returns 0 - sign(6) # Returns 1 +Converts a ``dictionary`` (created with :ref:`inst_to_dict()`) back to an Object instance. Can be useful for deserializing. + +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_sin: +.. _class_@GDScript_method_get_stack: -- :ref:`float` **sin** **(** :ref:`float` s **)** +.. rst-class:: classref-method -Returns the sine of angle ``s`` in radians. +:ref:`Array` **get_stack**\ (\ ) :ref:`🔗` -:: - - sin(0.523599) # Returns 0.5 +Returns an array of dictionaries representing the current call stack. ----- +:: -.. _class_@GDScript_method_sinh: + func _ready(): + foo() -- :ref:`float` **sinh** **(** :ref:`float` s **)** + func foo(): + bar() -Returns the hyperbolic sine of ``s``. + func bar(): + print(get_stack()) -:: +Starting from ``_ready()``, ``bar()`` would print: - a = log(2.0) # Returns 0.693147 - sinh(a) # Returns 0.75 +.. code:: text ----- + [{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}] -.. _class_@GDScript_method_smoothstep: +See also :ref:`print_debug()`, :ref:`print_stack()`, and :ref:`Engine.capture_script_backtraces()`. -- :ref:`float` **smoothstep** **(** :ref:`float` from, :ref:`float` to, :ref:`float` weight **)** +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks`. -Returns a number smoothly interpolated between the ``from`` and ``to``, based on the ``weight``. Similar to :ref:`lerp`, but interpolates faster at the beginning and slower at the end. +.. rst-class:: classref-item-separator -:: +---- - smoothstep(0, 2, 0.5) # Returns 0.15 - smoothstep(0, 2, 1.0) # Returns 0.5 - smoothstep(0, 2, 2.0) # Returns 1.0 +.. _class_@GDScript_method_inst_to_dict: ----- +.. rst-class:: classref-method -.. _class_@GDScript_method_sqrt: +:ref:`Dictionary` **inst_to_dict**\ (\ instance\: :ref:`Object`\ ) :ref:`🔗` -- :ref:`float` **sqrt** **(** :ref:`float` s **)** +**Deprecated:** Consider using :ref:`JSON.from_native()` or :ref:`Object.get_property_list()` instead. -Returns the square root of ``s``. +Returns the passed ``instance`` converted to a :ref:`Dictionary`. Can be useful for serializing. :: - sqrt(9) # Returns 3 + var foo = "bar" + func _ready(): + var d = inst_to_dict(self) + print(d.keys()) + print(d.values()) ----- +Prints out: -.. _class_@GDScript_method_step_decimals: +.. code:: text -- :ref:`int` **step_decimals** **(** :ref:`float` step **)** + [@subpath, @path, foo] + [, res://test.gd, bar] -Returns the position of the first non-zero digit, after the decimal point. Note that the maximum return value is 10, which is a design decision in the implementation. +\ **Note:** This function can only be used to serialize objects with an attached :ref:`GDScript` stored in a separate file. Objects without an attached script, with a script written in another language, or with a built-in script are not supported. -:: +\ **Note:** This function is not recursive, which means that nested objects will not be represented as dictionaries. Also, properties passed by reference (:ref:`Object`, :ref:`Dictionary`, :ref:`Array`, and packed arrays) are copied by reference, not duplicated. - # n is 0 - n = step_decimals(5) - # n is 4 - n = step_decimals(1.0005) - # n is 9 - n = step_decimals(0.000000005) +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_stepify: +.. _class_@GDScript_method_is_instance_of: -- :ref:`float` **stepify** **(** :ref:`float` s, :ref:`float` step **)** +.. rst-class:: classref-method -Snaps float value ``s`` to a given ``step``. This can also be used to round a floating point number to an arbitrary number of decimals. +:ref:`bool` **is_instance_of**\ (\ value\: :ref:`Variant`, type\: :ref:`Variant`\ ) :ref:`🔗` -:: +Returns ``true`` if ``value`` is an instance of ``type``. The ``type`` value must be one of the following: - stepify(100, 32) # Returns 96 - stepify(3.14159, 0.01) # Returns 3.14 +- A constant from the :ref:`Variant.Type` enumeration, for example :ref:`@GlobalScope.TYPE_INT`. ----- +- An :ref:`Object`-derived class which exists in :ref:`ClassDB`, for example :ref:`Node`. -.. _class_@GDScript_method_str: +- A :ref:`Script` (you can use any class, including inner one). -- :ref:`String` **str** **(** ... **)** vararg +Unlike the right operand of the ``is`` operator, ``type`` can be a non-constant value. The ``is`` operator supports more features (such as typed arrays). Use the operator instead of this method if you do not need to check the type dynamically. -Converts one or more arguments to string in the best way possible. +\ **Examples:**\ :: - var a = [10, 20, 30] - var b = str(a); - len(a) # Returns 3 - len(b) # Returns 12 + print(is_instance_of(a, TYPE_INT)) + print(is_instance_of(a, Node)) + print(is_instance_of(a, MyClass)) + print(is_instance_of(a, MyClass.InnerClass)) ----- +\ **Note:** If ``value`` and/or ``type`` are freed objects (see :ref:`@GlobalScope.is_instance_valid()`), or ``type`` is not one of the above options, this method will raise a runtime error. -.. _class_@GDScript_method_str2var: +See also :ref:`@GlobalScope.typeof()`, :ref:`type_exists()`, :ref:`Array.is_same_typed()` (and other :ref:`Array` methods). -- :ref:`Variant` **str2var** **(** :ref:`String` string **)** +.. rst-class:: classref-item-separator -Converts a formatted string that was returned by :ref:`var2str` to the original value. +---- -:: +.. _class_@GDScript_method_len: - a = '{ "a": 1, "b": 2 }' - b = str2var(a) - print(b["a"]) # Prints 1 +.. rst-class:: classref-method ----- +:ref:`int` **len**\ (\ var\: :ref:`Variant`\ ) :ref:`🔗` -.. _class_@GDScript_method_tan: +Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String` or :ref:`StringName`, the element count of any array type, or the size of a :ref:`Dictionary`. For every other Variant type, a run-time error is generated and execution is stopped. -- :ref:`float` **tan** **(** :ref:`float` s **)** +:: -Returns the tangent of angle ``s`` in radians. + var a = [1, 2, 3, 4] + len(a) # Returns 4 -:: + var b = "Hello!" + len(b) # Returns 6 - tan(deg2rad(45)) # Returns 1 +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_tanh: +.. _class_@GDScript_method_load: -- :ref:`float` **tanh** **(** :ref:`float` s **)** +.. rst-class:: classref-method -Returns the hyperbolic tangent of ``s``. +:ref:`Resource` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` -:: +Returns a :ref:`Resource` from the filesystem located at the absolute ``path``. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use :ref:`preload()`. This method is equivalent of using :ref:`ResourceLoader.load()` with :ref:`ResourceLoader.CACHE_MODE_REUSE`. - a = log(2.0) # Returns 0.693147 - tanh(a) # Returns 0.6 +\ **Note:** Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script. ----- +:: -.. _class_@GDScript_method_to_json: + # Load a scene called "main" located in the root of the project directory and cache it in a variable. + var main = load("res://main.tscn") # main will contain a PackedScene resource. -- :ref:`String` **to_json** **(** :ref:`Variant` var **)** +\ **Important:** Relative paths are *not* relative to the script calling this method, instead it is prefixed with ``"res://"``. Loading from relative paths might not work as expected. -Converts a Variant ``var`` to JSON text and return the result. Useful for serializing data to store or send over the network. +This function is a simplified version of :ref:`ResourceLoader.load()`, which can be used for more advanced scenarios. -:: +\ **Note:** Files have to be imported into the engine first to load them using this function. If you want to load :ref:`Image`\ s at run-time, you may use :ref:`Image.load()`. If you want to import audio files, you can use the snippet described in :ref:`AudioStreamMP3.data`. - a = { "a": 1, "b": 2 } - b = to_json(a) - print(b) # {"a":1, "b":2} +\ **Note:** If :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` is ``true``, :ref:`load()` will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` to ``false``. ----- +.. rst-class:: classref-item-separator -.. _class_@GDScript_method_type_exists: +---- -- :ref:`bool` **type_exists** **(** :ref:`String` type **)** +.. _class_@GDScript_method_ord: -Returns whether the given class exists in :ref:`ClassDB`. +.. rst-class:: classref-method -:: +:ref:`int` **ord**\ (\ char\: :ref:`String`\ ) :ref:`🔗` - type_exists("Sprite") # Returns true - type_exists("Variant") # Returns false +Returns an integer representing the Unicode code point of the given character ``char``, which should be a string of length 1. ----- +:: -.. _class_@GDScript_method_typeof: + print(ord("A")) # Prints 65 + print(ord("🤖")) # Prints 129302 -- :ref:`int` **typeof** **(** :ref:`Variant` what **)** +This is the inverse of :ref:`char()`. See also :ref:`String.chr()` and :ref:`String.unicode_at()`. -Returns the internal type of the given Variant object, using the :ref:`Variant.Type` values. +.. rst-class:: classref-item-separator -:: +---- - p = parse_json('["a", "b", "c"]') - if typeof(p) == TYPE_ARRAY: - print(p[0]) # Prints a - else: - print("unexpected results") +.. _class_@GDScript_method_preload: ----- +.. rst-class:: classref-method -.. _class_@GDScript_method_validate_json: +:ref:`Resource` **preload**\ (\ path\: :ref:`String`\ ) :ref:`🔗` -- :ref:`String` **validate_json** **(** :ref:`String` json **)** +Returns a :ref:`Resource` from the filesystem located at ``path``. During run-time, the resource is loaded when the script is being parsed. This function effectively acts as a reference to that resource. Note that this function requires ``path`` to be a constant :ref:`String`. If you want to load a resource from a dynamic/variable path, use :ref:`load()`. -Checks that ``json`` is valid JSON data. Returns an empty string if valid, or an error message otherwise. +\ **Note:** Resource paths can be obtained by right-clicking on a resource in the Assets Panel and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script. :: - j = to_json([1, 2, 3]) - v = validate_json(j) - if not v: - print("valid") - else: - prints("invalid", v) + # Create instance of a scene. + var diamond = preload("res://diamond.tscn").instantiate() ----- +\ **Note:** :ref:`preload()` is a keyword, not a function. So you cannot access it as a :ref:`Callable`. -.. _class_@GDScript_method_var2bytes: +.. rst-class:: classref-item-separator -- :ref:`PackedByteArray` **var2bytes** **(** :ref:`Variant` var, :ref:`bool` full_objects=false **)** +---- -Encodes a variable value to a byte array. When ``full_objects`` is ``true`` encoding objects is allowed (and can potentially include code). +.. _class_@GDScript_method_print_debug: ----- +.. rst-class:: classref-method -.. _class_@GDScript_method_var2str: +|void| **print_debug**\ (\ ...\ ) |vararg| :ref:`🔗` -- :ref:`String` **var2str** **(** :ref:`Variant` var **)** +Like :ref:`@GlobalScope.print()`, but includes the current stack frame when running with the debugger turned on. -Converts a Variant ``var`` to a formatted string that can later be parsed using :ref:`str2var`. +The output in the console may look like the following: -:: +.. code:: text - a = { "a": 1, "b": 2 } - print(var2str(a)) + Test print + At: res://test.gd:15:_process() -prints +See also :ref:`print_stack()`, :ref:`get_stack()`, and :ref:`Engine.capture_script_backtraces()`. -:: +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks`. - { - "a": 1, - "b": 2 - } +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_weakref: +.. _class_@GDScript_method_print_stack: -- :ref:`WeakRef` **weakref** **(** :ref:`Object` obj **)** +.. rst-class:: classref-method -Returns a weak reference to an object. +|void| **print_stack**\ (\ ) :ref:`🔗` -A weak reference to an object is not enough to keep the object alive: when the only remaining references to a referent are weak references, garbage collection is free to destroy the referent and reuse its memory for something else. However, until the object is actually destroyed the weak reference may return the object even if there are no strong references to it. +Prints a stack trace at the current code location. ----- +The output in the console may look like the following: -.. _class_@GDScript_method_wrapf: +.. code:: text -- :ref:`float` **wrapf** **(** :ref:`float` value, :ref:`float` min, :ref:`float` max **)** + Frame 0 - res://test.gd:16 in function '_process' -Wraps float ``value`` between ``min`` and ``max``. +See also :ref:`print_debug()`, :ref:`get_stack()`, and :ref:`Engine.capture_script_backtraces()`. -Usable for creating loop-alike behavior or infinite surfaces. +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks`. -:: +.. rst-class:: classref-item-separator - # a is 0.5 - a = wrapf(10.5, 0.0, 10.0) +---- -:: +.. _class_@GDScript_method_range: - # a is 9.5 - a = wrapf(-0.5, 0.0, 10.0) +.. rst-class:: classref-method -:: +:ref:`Array` **range**\ (\ ...\ ) |vararg| :ref:`🔗` - # Infinite loop between 0.0 and 0.99 - f = wrapf(f + 0.1, 0.0, 1.0) +Returns an array with the given range. :ref:`range()` can be called in three ways: -:: +\ ``range(n: int)``: Starts from 0, increases by steps of 1, and stops *before* ``n``. The argument ``n`` is **exclusive**. - # Infinite rotation (in radians) - angle = wrapf(angle + 0.1, 0.0, TAU) +\ ``range(b: int, n: int)``: Starts from ``b``, increases by steps of 1, and stops *before* ``n``. The arguments ``b`` and ``n`` are **inclusive** and **exclusive**, respectively. -**Note:** If you just want to wrap between 0.0 and ``n`` (where ``n`` is a positive floating-point value), it is better for performance to use the :ref:`fmod` method like ``fmod(number, n)``. +\ ``range(b: int, n: int, s: int)``: Starts from ``b``, increases/decreases by steps of ``s``, and stops *before* ``n``. The arguments ``b`` and ``n`` are **inclusive** and **exclusive**, respectively. The argument ``s`` **can** be negative, but not ``0``. If ``s`` is ``0``, an error message is printed. -``wrapf`` is more flexible than using the :ref:`fmod` approach by giving the user a simple control over the minimum value. It also fully supports negative numbers, e.g. +\ :ref:`range()` converts all arguments to :ref:`int` before processing. -:: +\ **Note:** Returns an empty array if no value meets the value constraint (e.g. ``range(2, 5, -1)`` or ``range(5, 5, 1)``). - # Infinite rotation (in radians) - angle = wrapf(angle + 0.1, -PI, PI) +\ **Examples:**\ ----- +:: -.. _class_@GDScript_method_wrapi: + print(range(4)) # Prints [0, 1, 2, 3] + print(range(2, 5)) # Prints [2, 3, 4] + print(range(0, 6, 2)) # Prints [0, 2, 4] + print(range(4, 1, -1)) # Prints [4, 3, 2] -- :ref:`int` **wrapi** **(** :ref:`int` value, :ref:`int` min, :ref:`int` max **)** +To iterate over an :ref:`Array` backwards, use: -Wraps integer ``value`` between ``min`` and ``max``. +:: -Usable for creating loop-alike behavior or infinite surfaces. + var array = [3, 6, 9] + for i in range(array.size() - 1, -1, -1): + print(array[i]) -:: +Output: - # a is 0 - a = wrapi(10, 0, 10) +.. code:: text -:: + 9 + 6 + 3 - # a is 9 - a = wrapi(-1, 0, 10) +To iterate over :ref:`float`, convert them in the loop. :: - # Infinite loop between 0 and 9 - frame = wrapi(frame + 1, 0, 10) + for i in range (3, 0, -1): + print(i / 10.0) -**Note:** If you just want to wrap between 0 and ``n`` (where ``n`` is a positive integer value), it is better for performance to use the modulo operator like ``number % n``. +Output: -``wrapi`` is more flexible than using the modulo approach by giving the user a simple control over the minimum value. It also fully supports negative numbers, e.g. +.. code:: text -:: + 0.3 + 0.2 + 0.1 - # result is -2 - var result = wrapi(-6, -5, -1) +.. rst-class:: classref-item-separator ---- -.. _class_@GDScript_method_yield: - -- :ref:`GDScriptFunctionState` **yield** **(** :ref:`Object` object=null, :ref:`String` signal="" **)** - -Stops the function execution and returns the current suspended state to the calling function. +.. _class_@GDScript_method_type_exists: -From the caller, call :ref:`GDScriptFunctionState.resume` on the state to resume execution. This invalidates the state. Within the resumed function, ``yield()`` returns whatever was passed to the ``resume()`` function call. +.. rst-class:: classref-method -If passed an object and a signal, the execution is resumed when the object emits the given signal. In this case, ``yield()`` returns the argument passed to ``emit_signal()`` if the signal takes only one argument, or an array containing all the arguments passed to ``emit_signal()`` if the signal takes multiple arguments. +:ref:`bool` **type_exists**\ (\ type\: :ref:`StringName`\ ) :ref:`🔗` -You can also use ``yield`` to wait for a function to finish: +Returns ``true`` if the given :ref:`Object`-derived class exists in :ref:`ClassDB`. Note that :ref:`Variant` data types are not registered in :ref:`ClassDB`. :: - func _ready(): - yield(countdown(), "completed") # waiting for the countdown() function to complete - print('Ready') - - func countdown(): - yield(get_tree(), "idle_frame") # returns a GDScriptFunctionState object to _ready() - print(3) - yield(get_tree().create_timer(1.0), "timeout") - print(2) - yield(get_tree().create_timer(1.0), "timeout") - print(1) - yield(get_tree().create_timer(1.0), "timeout") - - # prints: - # 3 - # 2 - # 1 - # Ready - -When yielding on a function, the ``completed`` signal will be emitted automatically when the function returns. It can, therefore, be used as the ``signal`` parameter of the ``yield`` method to resume. - -In order to yield on a function, the resulting function should also return a ``GDScriptFunctionState``. Notice ``yield(get_tree(), "idle_frame")`` from the above example. + type_exists("Sprite2D") # Returns true + type_exists("NonExistentClass") # Returns false +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 73577e55d0d..28eec7c17f3 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -1,2467 +1,7622 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the @GlobalScope.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/@GlobalScope.xml. .. _class_@GlobalScope: @GlobalScope ============ -Global scope constants and variables. +Global scope constants and functions. + +.. rst-class:: classref-introduction-group Description ----------- -Global scope constants and variables. This is all that resides in the globals, constants regarding error codes, keycodes, property hints, etc. +A list of global scope enumerated constants and built-in functions. This is all that resides in the globals, constants regarding error codes, keycodes, property hints, etc. Singletons are also documented here, since they can be accessed from anywhere. -Properties ----------- +For the entries that can only be accessed from scripts written in GDScript, see :ref:`@GDScript`. -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`ARVRServer` | :ref:`ARVRServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`AudioServer` | :ref:`AudioServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`CameraServer` | :ref:`CameraServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`ClassDB` | :ref:`ClassDB` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`Engine` | :ref:`Engine` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`Geometry` | :ref:`Geometry` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`GodotSharp` | :ref:`GodotSharp` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`IP` | :ref:`IP` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`Input` | :ref:`Input` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`InputMap` | :ref:`InputMap` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`JSON` | :ref:`JSON` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`JavaClassWrapper` | :ref:`JavaClassWrapper` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`JavaScript` | :ref:`JavaScript` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`Marshalls` | :ref:`Marshalls` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`Navigation2DServer` | :ref:`Navigation2DServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`NavigationMeshGenerator` | :ref:`NavigationMeshGenerator` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`NavigationServer` | :ref:`NavigationServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`OS` | :ref:`OS` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`Performance` | :ref:`Performance` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`Physics2DServer` | :ref:`Physics2DServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`PhysicsServer` | :ref:`PhysicsServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`ProjectSettings` | :ref:`ProjectSettings` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`ResourceLoader` | :ref:`ResourceLoader` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`ResourceSaver` | :ref:`ResourceSaver` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`TranslationServer` | :ref:`TranslationServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`VisualScriptEditor` | :ref:`VisualScriptEditor` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`VisualServer` | :ref:`VisualServer` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ +.. note:: -Enumerations ------------- + There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. -.. _enum_@GlobalScope_Margin: +.. rst-class:: classref-introduction-group -.. _class_@GlobalScope_constant_MARGIN_LEFT: +Tutorials +--------- -.. _class_@GlobalScope_constant_MARGIN_TOP: +- :doc:`Random number generation <../tutorials/math/random_number_generation>` -.. _class_@GlobalScope_constant_MARGIN_RIGHT: +.. rst-class:: classref-reftable-group -.. _class_@GlobalScope_constant_MARGIN_BOTTOM: +Properties +---------- -enum **Margin**: +.. table:: + :widths: auto + + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`AudioServer` | :ref:`AudioServer` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`CameraServer` | :ref:`CameraServer` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`ClassDB` | :ref:`ClassDB` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`DisplayServer` | :ref:`DisplayServer` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`EditorInterface` | :ref:`EditorInterface` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`Engine` | :ref:`Engine` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`EngineDebugger` | :ref:`EngineDebugger` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`GDExtensionManager` | :ref:`GDExtensionManager` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`Geometry2D` | :ref:`Geometry2D` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`Geometry3D` | :ref:`Geometry3D` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`IP` | :ref:`IP` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`Input` | :ref:`Input` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`InputMap` | :ref:`InputMap` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`JavaClassWrapper` | :ref:`JavaClassWrapper` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`JavaScriptBridge` | :ref:`JavaScriptBridge` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`Marshalls` | :ref:`Marshalls` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`NativeMenu` | :ref:`NativeMenu` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`NavigationMeshGenerator` | :ref:`NavigationMeshGenerator` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`NavigationServer2D` | :ref:`NavigationServer2D` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`NavigationServer2DManager` | :ref:`NavigationServer2DManager` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`NavigationServer3D` | :ref:`NavigationServer3D` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`NavigationServer3DManager` | :ref:`NavigationServer3DManager` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`OS` | :ref:`OS` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`Performance` | :ref:`Performance` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`PhysicsServer2D` | :ref:`PhysicsServer2D` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`PhysicsServer2DManager` | :ref:`PhysicsServer2DManager` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`PhysicsServer3D` | :ref:`PhysicsServer3D` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`PhysicsServer3DManager` | :ref:`PhysicsServer3DManager` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`ProjectSettings` | :ref:`ProjectSettings` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`RenderingServer` | :ref:`RenderingServer` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`ResourceLoader` | :ref:`ResourceLoader` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`ResourceSaver` | :ref:`ResourceSaver` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`ResourceUID` | :ref:`ResourceUID` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`TextServerManager` | :ref:`TextServerManager` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`ThemeDB` | :ref:`ThemeDB` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`Time` | :ref:`Time` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`TranslationServer` | :ref:`TranslationServer` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`WorkerThreadPool` | :ref:`WorkerThreadPool` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`XRServer` | :ref:`XRServer` | + +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`abs`\ (\ x\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`absf`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`absi`\ (\ x\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`acos`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`acosh`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`angle_difference`\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`asin`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`asinh`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`atan`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`atan2`\ (\ y\: :ref:`float`, x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`atanh`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`bezier_derivative`\ (\ start\: :ref:`float`, control_1\: :ref:`float`, control_2\: :ref:`float`, end\: :ref:`float`, t\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`bezier_interpolate`\ (\ start\: :ref:`float`, control_1\: :ref:`float`, control_2\: :ref:`float`, end\: :ref:`float`, t\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`bytes_to_var`\ (\ bytes\: :ref:`PackedByteArray`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`bytes_to_var_with_objects`\ (\ bytes\: :ref:`PackedByteArray`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`ceil`\ (\ x\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`ceilf`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`ceili`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`clamp`\ (\ value\: :ref:`Variant`, min\: :ref:`Variant`, max\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`clampf`\ (\ value\: :ref:`float`, min\: :ref:`float`, max\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`clampi`\ (\ value\: :ref:`int`, min\: :ref:`int`, max\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`cos`\ (\ angle_rad\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`cosh`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`cubic_interpolate`\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`cubic_interpolate_angle`\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`cubic_interpolate_angle_in_time`\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`, to_t\: :ref:`float`, pre_t\: :ref:`float`, post_t\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`cubic_interpolate_in_time`\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`, to_t\: :ref:`float`, pre_t\: :ref:`float`, post_t\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`db_to_linear`\ (\ db\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`deg_to_rad`\ (\ deg\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`ease`\ (\ x\: :ref:`float`, curve\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`error_string`\ (\ error\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`exp`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`floor`\ (\ x\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`floorf`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`floori`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`fmod`\ (\ x\: :ref:`float`, y\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`fposmod`\ (\ x\: :ref:`float`, y\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`hash`\ (\ variable\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Object` | :ref:`instance_from_id`\ (\ instance_id\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`inverse_lerp`\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_equal_approx`\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_finite`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_inf`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_instance_id_valid`\ (\ id\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_instance_valid`\ (\ instance\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_nan`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_same`\ (\ a\: :ref:`Variant`, b\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_zero_approx`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`lerp`\ (\ from\: :ref:`Variant`, to\: :ref:`Variant`, weight\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`lerp_angle`\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`lerpf`\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`linear_to_db`\ (\ lin\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`log`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`max`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`maxf`\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`maxi`\ (\ a\: :ref:`int`, b\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`min`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`minf`\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`mini`\ (\ a\: :ref:`int`, b\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`move_toward`\ (\ from\: :ref:`float`, to\: :ref:`float`, delta\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`nearest_po2`\ (\ value\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`pingpong`\ (\ value\: :ref:`float`, length\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`posmod`\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`pow`\ (\ base\: :ref:`float`, exp\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`print`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`print_rich`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`print_verbose`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`printerr`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`printraw`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`prints`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`printt`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`push_error`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`push_warning`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`rad_to_deg`\ (\ rad\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt64Array` | :ref:`rand_from_seed`\ (\ seed\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`randf`\ (\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`randf_range`\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`randfn`\ (\ mean\: :ref:`float`, deviation\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`randi`\ (\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`randi_range`\ (\ from\: :ref:`int`, to\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`randomize`\ (\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`remap`\ (\ value\: :ref:`float`, istart\: :ref:`float`, istop\: :ref:`float`, ostart\: :ref:`float`, ostop\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rid_allocate_id`\ (\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`rid_from_int64`\ (\ base\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`rotate_toward`\ (\ from\: :ref:`float`, to\: :ref:`float`, delta\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`round`\ (\ x\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`roundf`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`roundi`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seed`\ (\ base\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`sign`\ (\ x\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`signf`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`signi`\ (\ x\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`sin`\ (\ angle_rad\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`sinh`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`smoothstep`\ (\ from\: :ref:`float`, to\: :ref:`float`, x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`snapped`\ (\ x\: :ref:`Variant`, step\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`snappedf`\ (\ x\: :ref:`float`, step\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`snappedi`\ (\ x\: :ref:`float`, step\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`sqrt`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`step_decimals`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`str`\ (\ ...\ ) |vararg| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`str_to_var`\ (\ string\: :ref:`String`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`tan`\ (\ angle_rad\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`tanh`\ (\ x\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`type_convert`\ (\ variant\: :ref:`Variant`, type\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`type_string`\ (\ type\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`typeof`\ (\ variable\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedByteArray` | :ref:`var_to_bytes`\ (\ variable\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedByteArray` | :ref:`var_to_bytes_with_objects`\ (\ variable\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`var_to_str`\ (\ variable\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`weakref`\ (\ obj\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`wrap`\ (\ value\: :ref:`Variant`, min\: :ref:`Variant`, max\: :ref:`Variant`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`wrapf`\ (\ value\: :ref:`float`, min\: :ref:`float`, max\: :ref:`float`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`wrapi`\ (\ value\: :ref:`int`, min\: :ref:`int`, max\: :ref:`int`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator -- **MARGIN_LEFT** = **0** --- Left margin, usually used for :ref:`Control` or :ref:`StyleBox`-derived classes. +---- -- **MARGIN_TOP** = **1** --- Top margin, usually used for :ref:`Control` or :ref:`StyleBox`-derived classes. +.. rst-class:: classref-descriptions-group -- **MARGIN_RIGHT** = **2** --- Right margin, usually used for :ref:`Control` or :ref:`StyleBox`-derived classes. +Enumerations +------------ -- **MARGIN_BOTTOM** = **3** --- Bottom margin, usually used for :ref:`Control` or :ref:`StyleBox`-derived classes. +.. _enum_@GlobalScope_Side: ----- +.. rst-class:: classref-enumeration -.. _enum_@GlobalScope_Corner: +enum **Side**: :ref:`🔗` -.. _class_@GlobalScope_constant_CORNER_TOP_LEFT: +.. _class_@GlobalScope_constant_SIDE_LEFT: -.. _class_@GlobalScope_constant_CORNER_TOP_RIGHT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_CORNER_BOTTOM_RIGHT: +:ref:`Side` **SIDE_LEFT** = ``0`` -.. _class_@GlobalScope_constant_CORNER_BOTTOM_LEFT: +Left side, usually used for :ref:`Control` or :ref:`StyleBox`-derived classes. -enum **Corner**: +.. _class_@GlobalScope_constant_SIDE_TOP: -- **CORNER_TOP_LEFT** = **0** --- Top-left corner. +.. rst-class:: classref-enumeration-constant -- **CORNER_TOP_RIGHT** = **1** --- Top-right corner. +:ref:`Side` **SIDE_TOP** = ``1`` -- **CORNER_BOTTOM_RIGHT** = **2** --- Bottom-right corner. +Top side, usually used for :ref:`Control` or :ref:`StyleBox`-derived classes. -- **CORNER_BOTTOM_LEFT** = **3** --- Bottom-left corner. +.. _class_@GlobalScope_constant_SIDE_RIGHT: ----- +.. rst-class:: classref-enumeration-constant -.. _enum_@GlobalScope_Orientation: +:ref:`Side` **SIDE_RIGHT** = ``2`` -.. _class_@GlobalScope_constant_VERTICAL: +Right side, usually used for :ref:`Control` or :ref:`StyleBox`-derived classes. -.. _class_@GlobalScope_constant_HORIZONTAL: +.. _class_@GlobalScope_constant_SIDE_BOTTOM: + +.. rst-class:: classref-enumeration-constant -enum **Orientation**: +:ref:`Side` **SIDE_BOTTOM** = ``3`` -- **VERTICAL** = **1** --- General vertical alignment, usually used for :ref:`Separator`, :ref:`ScrollBar`, :ref:`Slider`, etc. +Bottom side, usually used for :ref:`Control` or :ref:`StyleBox`-derived classes. -- **HORIZONTAL** = **0** --- General horizontal alignment, usually used for :ref:`Separator`, :ref:`ScrollBar`, :ref:`Slider`, etc. +.. rst-class:: classref-item-separator ---- -.. _enum_@GlobalScope_HAlign: +.. _enum_@GlobalScope_Corner: -.. _class_@GlobalScope_constant_HALIGN_LEFT: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_HALIGN_CENTER: +enum **Corner**: :ref:`🔗` -.. _class_@GlobalScope_constant_HALIGN_RIGHT: +.. _class_@GlobalScope_constant_CORNER_TOP_LEFT: -enum **HAlign**: +.. rst-class:: classref-enumeration-constant -- **HALIGN_LEFT** = **0** --- Horizontal left alignment, usually for text-derived classes. +:ref:`Corner` **CORNER_TOP_LEFT** = ``0`` -- **HALIGN_CENTER** = **1** --- Horizontal center alignment, usually for text-derived classes. +Top-left corner. -- **HALIGN_RIGHT** = **2** --- Horizontal right alignment, usually for text-derived classes. +.. _class_@GlobalScope_constant_CORNER_TOP_RIGHT: ----- +.. rst-class:: classref-enumeration-constant -.. _enum_@GlobalScope_VAlign: +:ref:`Corner` **CORNER_TOP_RIGHT** = ``1`` -.. _class_@GlobalScope_constant_VALIGN_TOP: +Top-right corner. -.. _class_@GlobalScope_constant_VALIGN_CENTER: +.. _class_@GlobalScope_constant_CORNER_BOTTOM_RIGHT: -.. _class_@GlobalScope_constant_VALIGN_BOTTOM: +.. rst-class:: classref-enumeration-constant -enum **VAlign**: +:ref:`Corner` **CORNER_BOTTOM_RIGHT** = ``2`` -- **VALIGN_TOP** = **0** --- Vertical top alignment, usually for text-derived classes. +Bottom-right corner. -- **VALIGN_CENTER** = **1** --- Vertical center alignment, usually for text-derived classes. +.. _class_@GlobalScope_constant_CORNER_BOTTOM_LEFT: -- **VALIGN_BOTTOM** = **2** --- Vertical bottom alignment, usually for text-derived classes. +.. rst-class:: classref-enumeration-constant ----- +:ref:`Corner` **CORNER_BOTTOM_LEFT** = ``3`` -.. _enum_@GlobalScope_KeyList: +Bottom-left corner. -.. _class_@GlobalScope_constant_KEY_ESCAPE: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_KEY_TAB: +---- -.. _class_@GlobalScope_constant_KEY_BACKTAB: +.. _enum_@GlobalScope_Orientation: -.. _class_@GlobalScope_constant_KEY_BACKSPACE: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_KEY_ENTER: +enum **Orientation**: :ref:`🔗` -.. _class_@GlobalScope_constant_KEY_KP_ENTER: +.. _class_@GlobalScope_constant_VERTICAL: -.. _class_@GlobalScope_constant_KEY_INSERT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_DELETE: +:ref:`Orientation` **VERTICAL** = ``1`` -.. _class_@GlobalScope_constant_KEY_PAUSE: +General vertical alignment, usually used for :ref:`Separator`, :ref:`ScrollBar`, :ref:`Slider`, etc. -.. _class_@GlobalScope_constant_KEY_PRINT: +.. _class_@GlobalScope_constant_HORIZONTAL: -.. _class_@GlobalScope_constant_KEY_SYSREQ: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_CLEAR: +:ref:`Orientation` **HORIZONTAL** = ``0`` -.. _class_@GlobalScope_constant_KEY_HOME: +General horizontal alignment, usually used for :ref:`Separator`, :ref:`ScrollBar`, :ref:`Slider`, etc. -.. _class_@GlobalScope_constant_KEY_END: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_KEY_LEFT: +---- -.. _class_@GlobalScope_constant_KEY_UP: +.. _enum_@GlobalScope_ClockDirection: -.. _class_@GlobalScope_constant_KEY_RIGHT: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_KEY_DOWN: +enum **ClockDirection**: :ref:`🔗` -.. _class_@GlobalScope_constant_KEY_PAGEUP: +.. _class_@GlobalScope_constant_CLOCKWISE: -.. _class_@GlobalScope_constant_KEY_PAGEDOWN: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_SHIFT: +:ref:`ClockDirection` **CLOCKWISE** = ``0`` -.. _class_@GlobalScope_constant_KEY_CONTROL: +Clockwise rotation. Used by some methods (e.g. :ref:`Image.rotate_90()`). -.. _class_@GlobalScope_constant_KEY_META: +.. _class_@GlobalScope_constant_COUNTERCLOCKWISE: -.. _class_@GlobalScope_constant_KEY_ALT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_CAPSLOCK: +:ref:`ClockDirection` **COUNTERCLOCKWISE** = ``1`` -.. _class_@GlobalScope_constant_KEY_NUMLOCK: +Counter-clockwise rotation. Used by some methods (e.g. :ref:`Image.rotate_90()`). -.. _class_@GlobalScope_constant_KEY_SCROLLLOCK: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_KEY_F1: +---- -.. _class_@GlobalScope_constant_KEY_F2: +.. _enum_@GlobalScope_HorizontalAlignment: -.. _class_@GlobalScope_constant_KEY_F3: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_KEY_F4: +enum **HorizontalAlignment**: :ref:`🔗` -.. _class_@GlobalScope_constant_KEY_F5: +.. _class_@GlobalScope_constant_HORIZONTAL_ALIGNMENT_LEFT: -.. _class_@GlobalScope_constant_KEY_F6: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_F7: +:ref:`HorizontalAlignment` **HORIZONTAL_ALIGNMENT_LEFT** = ``0`` -.. _class_@GlobalScope_constant_KEY_F8: +Horizontal left alignment, usually for text-derived classes. -.. _class_@GlobalScope_constant_KEY_F9: +.. _class_@GlobalScope_constant_HORIZONTAL_ALIGNMENT_CENTER: -.. _class_@GlobalScope_constant_KEY_F10: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_F11: +:ref:`HorizontalAlignment` **HORIZONTAL_ALIGNMENT_CENTER** = ``1`` -.. _class_@GlobalScope_constant_KEY_F12: +Horizontal center alignment, usually for text-derived classes. -.. _class_@GlobalScope_constant_KEY_F13: +.. _class_@GlobalScope_constant_HORIZONTAL_ALIGNMENT_RIGHT: -.. _class_@GlobalScope_constant_KEY_F14: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_F15: +:ref:`HorizontalAlignment` **HORIZONTAL_ALIGNMENT_RIGHT** = ``2`` -.. _class_@GlobalScope_constant_KEY_F16: +Horizontal right alignment, usually for text-derived classes. -.. _class_@GlobalScope_constant_KEY_KP_MULTIPLY: +.. _class_@GlobalScope_constant_HORIZONTAL_ALIGNMENT_FILL: -.. _class_@GlobalScope_constant_KEY_KP_DIVIDE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_KP_SUBTRACT: +:ref:`HorizontalAlignment` **HORIZONTAL_ALIGNMENT_FILL** = ``3`` -.. _class_@GlobalScope_constant_KEY_KP_PERIOD: +Expand row to fit width, usually for text-derived classes. -.. _class_@GlobalScope_constant_KEY_KP_ADD: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_KEY_KP_0: +---- -.. _class_@GlobalScope_constant_KEY_KP_1: +.. _enum_@GlobalScope_VerticalAlignment: -.. _class_@GlobalScope_constant_KEY_KP_2: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_KEY_KP_3: +enum **VerticalAlignment**: :ref:`🔗` -.. _class_@GlobalScope_constant_KEY_KP_4: +.. _class_@GlobalScope_constant_VERTICAL_ALIGNMENT_TOP: -.. _class_@GlobalScope_constant_KEY_KP_5: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_KP_6: +:ref:`VerticalAlignment` **VERTICAL_ALIGNMENT_TOP** = ``0`` -.. _class_@GlobalScope_constant_KEY_KP_7: +Vertical top alignment, usually for text-derived classes. -.. _class_@GlobalScope_constant_KEY_KP_8: +.. _class_@GlobalScope_constant_VERTICAL_ALIGNMENT_CENTER: -.. _class_@GlobalScope_constant_KEY_KP_9: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_SUPER_L: +:ref:`VerticalAlignment` **VERTICAL_ALIGNMENT_CENTER** = ``1`` -.. _class_@GlobalScope_constant_KEY_SUPER_R: +Vertical center alignment, usually for text-derived classes. -.. _class_@GlobalScope_constant_KEY_MENU: +.. _class_@GlobalScope_constant_VERTICAL_ALIGNMENT_BOTTOM: -.. _class_@GlobalScope_constant_KEY_HYPER_L: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_HYPER_R: +:ref:`VerticalAlignment` **VERTICAL_ALIGNMENT_BOTTOM** = ``2`` -.. _class_@GlobalScope_constant_KEY_HELP: +Vertical bottom alignment, usually for text-derived classes. -.. _class_@GlobalScope_constant_KEY_DIRECTION_L: +.. _class_@GlobalScope_constant_VERTICAL_ALIGNMENT_FILL: -.. _class_@GlobalScope_constant_KEY_DIRECTION_R: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_BACK: +:ref:`VerticalAlignment` **VERTICAL_ALIGNMENT_FILL** = ``3`` -.. _class_@GlobalScope_constant_KEY_FORWARD: +Expand rows to fit height, usually for text-derived classes. -.. _class_@GlobalScope_constant_KEY_STOP: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_KEY_REFRESH: +---- -.. _class_@GlobalScope_constant_KEY_VOLUMEDOWN: +.. _enum_@GlobalScope_InlineAlignment: -.. _class_@GlobalScope_constant_KEY_VOLUMEMUTE: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_KEY_VOLUMEUP: +enum **InlineAlignment**: :ref:`🔗` -.. _class_@GlobalScope_constant_KEY_BASSBOOST: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_TOP_TO: -.. _class_@GlobalScope_constant_KEY_BASSUP: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_BASSDOWN: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_TOP_TO** = ``0`` -.. _class_@GlobalScope_constant_KEY_TREBLEUP: +Aligns the top of the inline object (e.g. image, table) to the position of the text specified by ``INLINE_ALIGNMENT_TO_*`` constant. -.. _class_@GlobalScope_constant_KEY_TREBLEDOWN: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_CENTER_TO: -.. _class_@GlobalScope_constant_KEY_MEDIAPLAY: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_MEDIASTOP: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_CENTER_TO** = ``1`` -.. _class_@GlobalScope_constant_KEY_MEDIAPREVIOUS: +Aligns the center of the inline object (e.g. image, table) to the position of the text specified by ``INLINE_ALIGNMENT_TO_*`` constant. -.. _class_@GlobalScope_constant_KEY_MEDIANEXT: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_BASELINE_TO: -.. _class_@GlobalScope_constant_KEY_MEDIARECORD: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_HOMEPAGE: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_BASELINE_TO** = ``3`` -.. _class_@GlobalScope_constant_KEY_FAVORITES: +Aligns the baseline (user defined) of the inline object (e.g. image, table) to the position of the text specified by ``INLINE_ALIGNMENT_TO_*`` constant. -.. _class_@GlobalScope_constant_KEY_SEARCH: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_BOTTOM_TO: -.. _class_@GlobalScope_constant_KEY_STANDBY: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_OPENURL: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_BOTTOM_TO** = ``2`` -.. _class_@GlobalScope_constant_KEY_LAUNCHMAIL: +Aligns the bottom of the inline object (e.g. image, table) to the position of the text specified by ``INLINE_ALIGNMENT_TO_*`` constant. -.. _class_@GlobalScope_constant_KEY_LAUNCHMEDIA: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_TO_TOP: -.. _class_@GlobalScope_constant_KEY_LAUNCH0: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_LAUNCH1: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_TO_TOP** = ``0`` -.. _class_@GlobalScope_constant_KEY_LAUNCH2: +Aligns the position of the inline object (e.g. image, table) specified by ``INLINE_ALIGNMENT_*_TO`` constant to the top of the text. -.. _class_@GlobalScope_constant_KEY_LAUNCH3: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_TO_CENTER: -.. _class_@GlobalScope_constant_KEY_LAUNCH4: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_LAUNCH5: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_TO_CENTER** = ``4`` -.. _class_@GlobalScope_constant_KEY_LAUNCH6: +Aligns the position of the inline object (e.g. image, table) specified by ``INLINE_ALIGNMENT_*_TO`` constant to the center of the text. -.. _class_@GlobalScope_constant_KEY_LAUNCH7: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_TO_BASELINE: -.. _class_@GlobalScope_constant_KEY_LAUNCH8: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_LAUNCH9: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_TO_BASELINE** = ``8`` -.. _class_@GlobalScope_constant_KEY_LAUNCHA: +Aligns the position of the inline object (e.g. image, table) specified by ``INLINE_ALIGNMENT_*_TO`` constant to the baseline of the text. -.. _class_@GlobalScope_constant_KEY_LAUNCHB: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_TO_BOTTOM: -.. _class_@GlobalScope_constant_KEY_LAUNCHC: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_LAUNCHD: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_TO_BOTTOM** = ``12`` -.. _class_@GlobalScope_constant_KEY_LAUNCHE: +Aligns inline object (e.g. image, table) to the bottom of the text. -.. _class_@GlobalScope_constant_KEY_LAUNCHF: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_TOP: -.. _class_@GlobalScope_constant_KEY_UNKNOWN: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_SPACE: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_TOP** = ``0`` -.. _class_@GlobalScope_constant_KEY_EXCLAM: +Aligns top of the inline object (e.g. image, table) to the top of the text. Equivalent to ``INLINE_ALIGNMENT_TOP_TO | INLINE_ALIGNMENT_TO_TOP``. -.. _class_@GlobalScope_constant_KEY_QUOTEDBL: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_CENTER: -.. _class_@GlobalScope_constant_KEY_NUMBERSIGN: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_DOLLAR: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_CENTER** = ``5`` -.. _class_@GlobalScope_constant_KEY_PERCENT: +Aligns center of the inline object (e.g. image, table) to the center of the text. Equivalent to ``INLINE_ALIGNMENT_CENTER_TO | INLINE_ALIGNMENT_TO_CENTER``. -.. _class_@GlobalScope_constant_KEY_AMPERSAND: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_BOTTOM: -.. _class_@GlobalScope_constant_KEY_APOSTROPHE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_PARENLEFT: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_BOTTOM** = ``14`` -.. _class_@GlobalScope_constant_KEY_PARENRIGHT: +Aligns bottom of the inline object (e.g. image, table) to the bottom of the text. Equivalent to ``INLINE_ALIGNMENT_BOTTOM_TO | INLINE_ALIGNMENT_TO_BOTTOM``. -.. _class_@GlobalScope_constant_KEY_ASTERISK: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_IMAGE_MASK: -.. _class_@GlobalScope_constant_KEY_PLUS: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_COMMA: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_IMAGE_MASK** = ``3`` -.. _class_@GlobalScope_constant_KEY_MINUS: +A bit mask for ``INLINE_ALIGNMENT_*_TO`` alignment constants. -.. _class_@GlobalScope_constant_KEY_PERIOD: +.. _class_@GlobalScope_constant_INLINE_ALIGNMENT_TEXT_MASK: -.. _class_@GlobalScope_constant_KEY_SLASH: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_0: +:ref:`InlineAlignment` **INLINE_ALIGNMENT_TEXT_MASK** = ``12`` -.. _class_@GlobalScope_constant_KEY_1: +A bit mask for ``INLINE_ALIGNMENT_TO_*`` alignment constants. -.. _class_@GlobalScope_constant_KEY_2: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_KEY_3: +---- -.. _class_@GlobalScope_constant_KEY_4: +.. _enum_@GlobalScope_EulerOrder: -.. _class_@GlobalScope_constant_KEY_5: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_KEY_6: +enum **EulerOrder**: :ref:`🔗` -.. _class_@GlobalScope_constant_KEY_7: +.. _class_@GlobalScope_constant_EULER_ORDER_XYZ: -.. _class_@GlobalScope_constant_KEY_8: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_9: +:ref:`EulerOrder` **EULER_ORDER_XYZ** = ``0`` -.. _class_@GlobalScope_constant_KEY_COLON: +Specifies that Euler angles should be in XYZ order. When composing, the order is X, Y, Z. When decomposing, the order is reversed, first Z, then Y, and X last. -.. _class_@GlobalScope_constant_KEY_SEMICOLON: +.. _class_@GlobalScope_constant_EULER_ORDER_XZY: -.. _class_@GlobalScope_constant_KEY_LESS: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_EQUAL: +:ref:`EulerOrder` **EULER_ORDER_XZY** = ``1`` -.. _class_@GlobalScope_constant_KEY_GREATER: +Specifies that Euler angles should be in XZY order. When composing, the order is X, Z, Y. When decomposing, the order is reversed, first Y, then Z, and X last. -.. _class_@GlobalScope_constant_KEY_QUESTION: +.. _class_@GlobalScope_constant_EULER_ORDER_YXZ: -.. _class_@GlobalScope_constant_KEY_AT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_A: +:ref:`EulerOrder` **EULER_ORDER_YXZ** = ``2`` -.. _class_@GlobalScope_constant_KEY_B: +Specifies that Euler angles should be in YXZ order. When composing, the order is Y, X, Z. When decomposing, the order is reversed, first Z, then X, and Y last. -.. _class_@GlobalScope_constant_KEY_C: +.. _class_@GlobalScope_constant_EULER_ORDER_YZX: -.. _class_@GlobalScope_constant_KEY_D: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_E: +:ref:`EulerOrder` **EULER_ORDER_YZX** = ``3`` -.. _class_@GlobalScope_constant_KEY_F: +Specifies that Euler angles should be in YZX order. When composing, the order is Y, Z, X. When decomposing, the order is reversed, first X, then Z, and Y last. -.. _class_@GlobalScope_constant_KEY_G: +.. _class_@GlobalScope_constant_EULER_ORDER_ZXY: -.. _class_@GlobalScope_constant_KEY_H: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_I: +:ref:`EulerOrder` **EULER_ORDER_ZXY** = ``4`` -.. _class_@GlobalScope_constant_KEY_J: +Specifies that Euler angles should be in ZXY order. When composing, the order is Z, X, Y. When decomposing, the order is reversed, first Y, then X, and Z last. -.. _class_@GlobalScope_constant_KEY_K: +.. _class_@GlobalScope_constant_EULER_ORDER_ZYX: -.. _class_@GlobalScope_constant_KEY_L: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_M: +:ref:`EulerOrder` **EULER_ORDER_ZYX** = ``5`` -.. _class_@GlobalScope_constant_KEY_N: +Specifies that Euler angles should be in ZYX order. When composing, the order is Z, Y, X. When decomposing, the order is reversed, first X, then Y, and Z last. -.. _class_@GlobalScope_constant_KEY_O: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_KEY_P: +---- -.. _class_@GlobalScope_constant_KEY_Q: +.. _enum_@GlobalScope_Key: -.. _class_@GlobalScope_constant_KEY_R: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_KEY_S: +enum **Key**: :ref:`🔗` -.. _class_@GlobalScope_constant_KEY_T: +.. _class_@GlobalScope_constant_KEY_NONE: -.. _class_@GlobalScope_constant_KEY_U: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_V: +:ref:`Key` **KEY_NONE** = ``0`` -.. _class_@GlobalScope_constant_KEY_W: +Enum value which doesn't correspond to any key. This is used to initialize :ref:`Key` properties with a generic state. -.. _class_@GlobalScope_constant_KEY_X: +.. _class_@GlobalScope_constant_KEY_SPECIAL: -.. _class_@GlobalScope_constant_KEY_Y: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_Z: +:ref:`Key` **KEY_SPECIAL** = ``4194304`` -.. _class_@GlobalScope_constant_KEY_BRACKETLEFT: +Keycodes with this bit applied are non-printable. -.. _class_@GlobalScope_constant_KEY_BACKSLASH: +.. _class_@GlobalScope_constant_KEY_ESCAPE: -.. _class_@GlobalScope_constant_KEY_BRACKETRIGHT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_ASCIICIRCUM: +:ref:`Key` **KEY_ESCAPE** = ``4194305`` -.. _class_@GlobalScope_constant_KEY_UNDERSCORE: +Escape key. -.. _class_@GlobalScope_constant_KEY_QUOTELEFT: +.. _class_@GlobalScope_constant_KEY_TAB: -.. _class_@GlobalScope_constant_KEY_BRACELEFT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_BAR: +:ref:`Key` **KEY_TAB** = ``4194306`` -.. _class_@GlobalScope_constant_KEY_BRACERIGHT: +Tab key. -.. _class_@GlobalScope_constant_KEY_ASCIITILDE: +.. _class_@GlobalScope_constant_KEY_BACKTAB: -.. _class_@GlobalScope_constant_KEY_NOBREAKSPACE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_EXCLAMDOWN: +:ref:`Key` **KEY_BACKTAB** = ``4194307`` -.. _class_@GlobalScope_constant_KEY_CENT: +Shift + Tab key. -.. _class_@GlobalScope_constant_KEY_STERLING: +.. _class_@GlobalScope_constant_KEY_BACKSPACE: -.. _class_@GlobalScope_constant_KEY_CURRENCY: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_YEN: +:ref:`Key` **KEY_BACKSPACE** = ``4194308`` -.. _class_@GlobalScope_constant_KEY_BROKENBAR: +Backspace key. -.. _class_@GlobalScope_constant_KEY_SECTION: +.. _class_@GlobalScope_constant_KEY_ENTER: -.. _class_@GlobalScope_constant_KEY_DIAERESIS: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_COPYRIGHT: +:ref:`Key` **KEY_ENTER** = ``4194309`` -.. _class_@GlobalScope_constant_KEY_ORDFEMININE: +Return key (on the main keyboard). -.. _class_@GlobalScope_constant_KEY_GUILLEMOTLEFT: +.. _class_@GlobalScope_constant_KEY_KP_ENTER: -.. _class_@GlobalScope_constant_KEY_NOTSIGN: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_HYPHEN: +:ref:`Key` **KEY_KP_ENTER** = ``4194310`` -.. _class_@GlobalScope_constant_KEY_REGISTERED: +Enter key on the numeric keypad. -.. _class_@GlobalScope_constant_KEY_MACRON: +.. _class_@GlobalScope_constant_KEY_INSERT: -.. _class_@GlobalScope_constant_KEY_DEGREE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_PLUSMINUS: +:ref:`Key` **KEY_INSERT** = ``4194311`` -.. _class_@GlobalScope_constant_KEY_TWOSUPERIOR: +Insert key. -.. _class_@GlobalScope_constant_KEY_THREESUPERIOR: +.. _class_@GlobalScope_constant_KEY_DELETE: -.. _class_@GlobalScope_constant_KEY_ACUTE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_MU: +:ref:`Key` **KEY_DELETE** = ``4194312`` -.. _class_@GlobalScope_constant_KEY_PARAGRAPH: +Delete key. -.. _class_@GlobalScope_constant_KEY_PERIODCENTERED: +.. _class_@GlobalScope_constant_KEY_PAUSE: -.. _class_@GlobalScope_constant_KEY_CEDILLA: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_ONESUPERIOR: +:ref:`Key` **KEY_PAUSE** = ``4194313`` -.. _class_@GlobalScope_constant_KEY_MASCULINE: +Pause key. -.. _class_@GlobalScope_constant_KEY_GUILLEMOTRIGHT: +.. _class_@GlobalScope_constant_KEY_PRINT: -.. _class_@GlobalScope_constant_KEY_ONEQUARTER: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_ONEHALF: +:ref:`Key` **KEY_PRINT** = ``4194314`` -.. _class_@GlobalScope_constant_KEY_THREEQUARTERS: +Print Screen key. -.. _class_@GlobalScope_constant_KEY_QUESTIONDOWN: +.. _class_@GlobalScope_constant_KEY_SYSREQ: -.. _class_@GlobalScope_constant_KEY_AGRAVE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_AACUTE: +:ref:`Key` **KEY_SYSREQ** = ``4194315`` -.. _class_@GlobalScope_constant_KEY_ACIRCUMFLEX: +System Request key. -.. _class_@GlobalScope_constant_KEY_ATILDE: +.. _class_@GlobalScope_constant_KEY_CLEAR: -.. _class_@GlobalScope_constant_KEY_ADIAERESIS: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_ARING: +:ref:`Key` **KEY_CLEAR** = ``4194316`` -.. _class_@GlobalScope_constant_KEY_AE: +Clear key. -.. _class_@GlobalScope_constant_KEY_CCEDILLA: +.. _class_@GlobalScope_constant_KEY_HOME: -.. _class_@GlobalScope_constant_KEY_EGRAVE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_EACUTE: +:ref:`Key` **KEY_HOME** = ``4194317`` -.. _class_@GlobalScope_constant_KEY_ECIRCUMFLEX: +Home key. -.. _class_@GlobalScope_constant_KEY_EDIAERESIS: +.. _class_@GlobalScope_constant_KEY_END: -.. _class_@GlobalScope_constant_KEY_IGRAVE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_IACUTE: +:ref:`Key` **KEY_END** = ``4194318`` -.. _class_@GlobalScope_constant_KEY_ICIRCUMFLEX: +End key. -.. _class_@GlobalScope_constant_KEY_IDIAERESIS: +.. _class_@GlobalScope_constant_KEY_LEFT: -.. _class_@GlobalScope_constant_KEY_ETH: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_NTILDE: +:ref:`Key` **KEY_LEFT** = ``4194319`` -.. _class_@GlobalScope_constant_KEY_OGRAVE: +Left arrow key. -.. _class_@GlobalScope_constant_KEY_OACUTE: +.. _class_@GlobalScope_constant_KEY_UP: -.. _class_@GlobalScope_constant_KEY_OCIRCUMFLEX: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_OTILDE: +:ref:`Key` **KEY_UP** = ``4194320`` -.. _class_@GlobalScope_constant_KEY_ODIAERESIS: +Up arrow key. -.. _class_@GlobalScope_constant_KEY_MULTIPLY: +.. _class_@GlobalScope_constant_KEY_RIGHT: -.. _class_@GlobalScope_constant_KEY_OOBLIQUE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_UGRAVE: +:ref:`Key` **KEY_RIGHT** = ``4194321`` -.. _class_@GlobalScope_constant_KEY_UACUTE: +Right arrow key. -.. _class_@GlobalScope_constant_KEY_UCIRCUMFLEX: +.. _class_@GlobalScope_constant_KEY_DOWN: -.. _class_@GlobalScope_constant_KEY_UDIAERESIS: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_YACUTE: +:ref:`Key` **KEY_DOWN** = ``4194322`` -.. _class_@GlobalScope_constant_KEY_THORN: +Down arrow key. -.. _class_@GlobalScope_constant_KEY_SSHARP: +.. _class_@GlobalScope_constant_KEY_PAGEUP: -.. _class_@GlobalScope_constant_KEY_DIVISION: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_YDIAERESIS: +:ref:`Key` **KEY_PAGEUP** = ``4194323`` -enum **KeyList**: +Page Up key. -- **KEY_ESCAPE** = **16777217** --- Escape key. +.. _class_@GlobalScope_constant_KEY_PAGEDOWN: -- **KEY_TAB** = **16777218** --- Tab key. +.. rst-class:: classref-enumeration-constant -- **KEY_BACKTAB** = **16777219** --- Shift+Tab key. +:ref:`Key` **KEY_PAGEDOWN** = ``4194324`` -- **KEY_BACKSPACE** = **16777220** --- Backspace key. +Page Down key. -- **KEY_ENTER** = **16777221** --- Return key (on the main keyboard). +.. _class_@GlobalScope_constant_KEY_SHIFT: -- **KEY_KP_ENTER** = **16777222** --- Enter key on the numeric keypad. +.. rst-class:: classref-enumeration-constant -- **KEY_INSERT** = **16777223** --- Insert key. +:ref:`Key` **KEY_SHIFT** = ``4194325`` -- **KEY_DELETE** = **16777224** --- Delete key. +Shift key. -- **KEY_PAUSE** = **16777225** --- Pause key. +.. _class_@GlobalScope_constant_KEY_CTRL: -- **KEY_PRINT** = **16777226** --- Print Screen key. +.. rst-class:: classref-enumeration-constant -- **KEY_SYSREQ** = **16777227** --- System Request key. +:ref:`Key` **KEY_CTRL** = ``4194326`` -- **KEY_CLEAR** = **16777228** --- Clear key. +Control key. -- **KEY_HOME** = **16777229** --- Home key. +.. _class_@GlobalScope_constant_KEY_META: -- **KEY_END** = **16777230** --- End key. +.. rst-class:: classref-enumeration-constant -- **KEY_LEFT** = **16777231** --- Left arrow key. +:ref:`Key` **KEY_META** = ``4194327`` -- **KEY_UP** = **16777232** --- Up arrow key. +Meta key. -- **KEY_RIGHT** = **16777233** --- Right arrow key. +.. _class_@GlobalScope_constant_KEY_ALT: -- **KEY_DOWN** = **16777234** --- Down arrow key. +.. rst-class:: classref-enumeration-constant -- **KEY_PAGEUP** = **16777235** --- Page Up key. +:ref:`Key` **KEY_ALT** = ``4194328`` -- **KEY_PAGEDOWN** = **16777236** --- Page Down key. +Alt key. -- **KEY_SHIFT** = **16777237** --- Shift key. +.. _class_@GlobalScope_constant_KEY_CAPSLOCK: -- **KEY_CONTROL** = **16777238** --- Control key. +.. rst-class:: classref-enumeration-constant -- **KEY_META** = **16777239** --- Meta key. +:ref:`Key` **KEY_CAPSLOCK** = ``4194329`` -- **KEY_ALT** = **16777240** --- Alt key. +Caps Lock key. -- **KEY_CAPSLOCK** = **16777241** --- Caps Lock key. +.. _class_@GlobalScope_constant_KEY_NUMLOCK: -- **KEY_NUMLOCK** = **16777242** --- Num Lock key. +.. rst-class:: classref-enumeration-constant -- **KEY_SCROLLLOCK** = **16777243** --- Scroll Lock key. +:ref:`Key` **KEY_NUMLOCK** = ``4194330`` -- **KEY_F1** = **16777244** --- F1 key. +Num Lock key. -- **KEY_F2** = **16777245** --- F2 key. +.. _class_@GlobalScope_constant_KEY_SCROLLLOCK: -- **KEY_F3** = **16777246** --- F3 key. +.. rst-class:: classref-enumeration-constant -- **KEY_F4** = **16777247** --- F4 key. +:ref:`Key` **KEY_SCROLLLOCK** = ``4194331`` -- **KEY_F5** = **16777248** --- F5 key. +Scroll Lock key. -- **KEY_F6** = **16777249** --- F6 key. +.. _class_@GlobalScope_constant_KEY_F1: -- **KEY_F7** = **16777250** --- F7 key. +.. rst-class:: classref-enumeration-constant -- **KEY_F8** = **16777251** --- F8 key. +:ref:`Key` **KEY_F1** = ``4194332`` -- **KEY_F9** = **16777252** --- F9 key. +F1 key. -- **KEY_F10** = **16777253** --- F10 key. +.. _class_@GlobalScope_constant_KEY_F2: -- **KEY_F11** = **16777254** --- F11 key. +.. rst-class:: classref-enumeration-constant -- **KEY_F12** = **16777255** --- F12 key. +:ref:`Key` **KEY_F2** = ``4194333`` -- **KEY_F13** = **16777256** --- F13 key. +F2 key. -- **KEY_F14** = **16777257** --- F14 key. +.. _class_@GlobalScope_constant_KEY_F3: -- **KEY_F15** = **16777258** --- F15 key. +.. rst-class:: classref-enumeration-constant -- **KEY_F16** = **16777259** --- F16 key. +:ref:`Key` **KEY_F3** = ``4194334`` -- **KEY_KP_MULTIPLY** = **16777345** --- Multiply (\*) key on the numeric keypad. +F3 key. -- **KEY_KP_DIVIDE** = **16777346** --- Divide (/) key on the numeric keypad. +.. _class_@GlobalScope_constant_KEY_F4: -- **KEY_KP_SUBTRACT** = **16777347** --- Subtract (-) key on the numeric keypad. +.. rst-class:: classref-enumeration-constant -- **KEY_KP_PERIOD** = **16777348** --- Period (.) key on the numeric keypad. +:ref:`Key` **KEY_F4** = ``4194335`` -- **KEY_KP_ADD** = **16777349** --- Add (+) key on the numeric keypad. +F4 key. -- **KEY_KP_0** = **16777350** --- Number 0 on the numeric keypad. +.. _class_@GlobalScope_constant_KEY_F5: -- **KEY_KP_1** = **16777351** --- Number 1 on the numeric keypad. +.. rst-class:: classref-enumeration-constant -- **KEY_KP_2** = **16777352** --- Number 2 on the numeric keypad. +:ref:`Key` **KEY_F5** = ``4194336`` -- **KEY_KP_3** = **16777353** --- Number 3 on the numeric keypad. +F5 key. -- **KEY_KP_4** = **16777354** --- Number 4 on the numeric keypad. +.. _class_@GlobalScope_constant_KEY_F6: -- **KEY_KP_5** = **16777355** --- Number 5 on the numeric keypad. +.. rst-class:: classref-enumeration-constant -- **KEY_KP_6** = **16777356** --- Number 6 on the numeric keypad. +:ref:`Key` **KEY_F6** = ``4194337`` -- **KEY_KP_7** = **16777357** --- Number 7 on the numeric keypad. +F6 key. -- **KEY_KP_8** = **16777358** --- Number 8 on the numeric keypad. +.. _class_@GlobalScope_constant_KEY_F7: -- **KEY_KP_9** = **16777359** --- Number 9 on the numeric keypad. +.. rst-class:: classref-enumeration-constant -- **KEY_SUPER_L** = **16777260** --- Left Super key (Windows key). +:ref:`Key` **KEY_F7** = ``4194338`` -- **KEY_SUPER_R** = **16777261** --- Right Super key (Windows key). +F7 key. -- **KEY_MENU** = **16777262** --- Context menu key. +.. _class_@GlobalScope_constant_KEY_F8: -- **KEY_HYPER_L** = **16777263** --- Left Hyper key. +.. rst-class:: classref-enumeration-constant -- **KEY_HYPER_R** = **16777264** --- Right Hyper key. +:ref:`Key` **KEY_F8** = ``4194339`` -- **KEY_HELP** = **16777265** --- Help key. +F8 key. -- **KEY_DIRECTION_L** = **16777266** --- Left Direction key. +.. _class_@GlobalScope_constant_KEY_F9: -- **KEY_DIRECTION_R** = **16777267** --- Right Direction key. +.. rst-class:: classref-enumeration-constant -- **KEY_BACK** = **16777280** --- Back key. +:ref:`Key` **KEY_F9** = ``4194340`` -- **KEY_FORWARD** = **16777281** --- Forward key. +F9 key. -- **KEY_STOP** = **16777282** --- Stop key. +.. _class_@GlobalScope_constant_KEY_F10: -- **KEY_REFRESH** = **16777283** --- Refresh key. +.. rst-class:: classref-enumeration-constant -- **KEY_VOLUMEDOWN** = **16777284** --- Volume down key. +:ref:`Key` **KEY_F10** = ``4194341`` -- **KEY_VOLUMEMUTE** = **16777285** --- Mute volume key. +F10 key. -- **KEY_VOLUMEUP** = **16777286** --- Volume up key. +.. _class_@GlobalScope_constant_KEY_F11: -- **KEY_BASSBOOST** = **16777287** --- Bass Boost key. +.. rst-class:: classref-enumeration-constant -- **KEY_BASSUP** = **16777288** --- Bass up key. +:ref:`Key` **KEY_F11** = ``4194342`` -- **KEY_BASSDOWN** = **16777289** --- Bass down key. +F11 key. -- **KEY_TREBLEUP** = **16777290** --- Treble up key. +.. _class_@GlobalScope_constant_KEY_F12: -- **KEY_TREBLEDOWN** = **16777291** --- Treble down key. +.. rst-class:: classref-enumeration-constant -- **KEY_MEDIAPLAY** = **16777292** --- Media play key. +:ref:`Key` **KEY_F12** = ``4194343`` -- **KEY_MEDIASTOP** = **16777293** --- Media stop key. +F12 key. -- **KEY_MEDIAPREVIOUS** = **16777294** --- Previous song key. +.. _class_@GlobalScope_constant_KEY_F13: -- **KEY_MEDIANEXT** = **16777295** --- Next song key. +.. rst-class:: classref-enumeration-constant -- **KEY_MEDIARECORD** = **16777296** --- Media record key. +:ref:`Key` **KEY_F13** = ``4194344`` -- **KEY_HOMEPAGE** = **16777297** --- Home page key. +F13 key. -- **KEY_FAVORITES** = **16777298** --- Favorites key. +.. _class_@GlobalScope_constant_KEY_F14: -- **KEY_SEARCH** = **16777299** --- Search key. +.. rst-class:: classref-enumeration-constant -- **KEY_STANDBY** = **16777300** --- Standby key. +:ref:`Key` **KEY_F14** = ``4194345`` -- **KEY_OPENURL** = **16777301** --- Open URL / Launch Browser key. +F14 key. -- **KEY_LAUNCHMAIL** = **16777302** --- Launch Mail key. +.. _class_@GlobalScope_constant_KEY_F15: -- **KEY_LAUNCHMEDIA** = **16777303** --- Launch Media key. +.. rst-class:: classref-enumeration-constant -- **KEY_LAUNCH0** = **16777304** --- Launch Shortcut 0 key. +:ref:`Key` **KEY_F15** = ``4194346`` -- **KEY_LAUNCH1** = **16777305** --- Launch Shortcut 1 key. +F15 key. -- **KEY_LAUNCH2** = **16777306** --- Launch Shortcut 2 key. +.. _class_@GlobalScope_constant_KEY_F16: -- **KEY_LAUNCH3** = **16777307** --- Launch Shortcut 3 key. +.. rst-class:: classref-enumeration-constant -- **KEY_LAUNCH4** = **16777308** --- Launch Shortcut 4 key. +:ref:`Key` **KEY_F16** = ``4194347`` -- **KEY_LAUNCH5** = **16777309** --- Launch Shortcut 5 key. +F16 key. -- **KEY_LAUNCH6** = **16777310** --- Launch Shortcut 6 key. +.. _class_@GlobalScope_constant_KEY_F17: -- **KEY_LAUNCH7** = **16777311** --- Launch Shortcut 7 key. +.. rst-class:: classref-enumeration-constant -- **KEY_LAUNCH8** = **16777312** --- Launch Shortcut 8 key. +:ref:`Key` **KEY_F17** = ``4194348`` -- **KEY_LAUNCH9** = **16777313** --- Launch Shortcut 9 key. +F17 key. -- **KEY_LAUNCHA** = **16777314** --- Launch Shortcut A key. +.. _class_@GlobalScope_constant_KEY_F18: -- **KEY_LAUNCHB** = **16777315** --- Launch Shortcut B key. +.. rst-class:: classref-enumeration-constant -- **KEY_LAUNCHC** = **16777316** --- Launch Shortcut C key. +:ref:`Key` **KEY_F18** = ``4194349`` -- **KEY_LAUNCHD** = **16777317** --- Launch Shortcut D key. +F18 key. -- **KEY_LAUNCHE** = **16777318** --- Launch Shortcut E key. +.. _class_@GlobalScope_constant_KEY_F19: -- **KEY_LAUNCHF** = **16777319** --- Launch Shortcut F key. +.. rst-class:: classref-enumeration-constant -- **KEY_UNKNOWN** = **33554431** --- Unknown key. +:ref:`Key` **KEY_F19** = ``4194350`` -- **KEY_SPACE** = **32** --- Space key. +F19 key. -- **KEY_EXCLAM** = **33** --- ! key. +.. _class_@GlobalScope_constant_KEY_F20: -- **KEY_QUOTEDBL** = **34** --- " key. +.. rst-class:: classref-enumeration-constant -- **KEY_NUMBERSIGN** = **35** --- # key. +:ref:`Key` **KEY_F20** = ``4194351`` -- **KEY_DOLLAR** = **36** --- $ key. +F20 key. -- **KEY_PERCENT** = **37** --- % key. +.. _class_@GlobalScope_constant_KEY_F21: -- **KEY_AMPERSAND** = **38** --- & key. +.. rst-class:: classref-enumeration-constant -- **KEY_APOSTROPHE** = **39** --- ' key. +:ref:`Key` **KEY_F21** = ``4194352`` -- **KEY_PARENLEFT** = **40** --- ( key. +F21 key. -- **KEY_PARENRIGHT** = **41** --- ) key. +.. _class_@GlobalScope_constant_KEY_F22: -- **KEY_ASTERISK** = **42** --- \* key. +.. rst-class:: classref-enumeration-constant -- **KEY_PLUS** = **43** --- + key. +:ref:`Key` **KEY_F22** = ``4194353`` -- **KEY_COMMA** = **44** --- , key. +F22 key. -- **KEY_MINUS** = **45** --- - key. +.. _class_@GlobalScope_constant_KEY_F23: -- **KEY_PERIOD** = **46** --- . key. +.. rst-class:: classref-enumeration-constant -- **KEY_SLASH** = **47** --- / key. +:ref:`Key` **KEY_F23** = ``4194354`` -- **KEY_0** = **48** --- Number 0. +F23 key. -- **KEY_1** = **49** --- Number 1. +.. _class_@GlobalScope_constant_KEY_F24: -- **KEY_2** = **50** --- Number 2. +.. rst-class:: classref-enumeration-constant -- **KEY_3** = **51** --- Number 3. +:ref:`Key` **KEY_F24** = ``4194355`` -- **KEY_4** = **52** --- Number 4. +F24 key. -- **KEY_5** = **53** --- Number 5. +.. _class_@GlobalScope_constant_KEY_F25: -- **KEY_6** = **54** --- Number 6. +.. rst-class:: classref-enumeration-constant -- **KEY_7** = **55** --- Number 7. +:ref:`Key` **KEY_F25** = ``4194356`` -- **KEY_8** = **56** --- Number 8. +F25 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_9** = **57** --- Number 9. +.. _class_@GlobalScope_constant_KEY_F26: -- **KEY_COLON** = **58** --- : key. +.. rst-class:: classref-enumeration-constant -- **KEY_SEMICOLON** = **59** --- ; key. +:ref:`Key` **KEY_F26** = ``4194357`` -- **KEY_LESS** = **60** --- < key. +F26 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_EQUAL** = **61** --- = key. +.. _class_@GlobalScope_constant_KEY_F27: -- **KEY_GREATER** = **62** --- > key. +.. rst-class:: classref-enumeration-constant -- **KEY_QUESTION** = **63** --- ? key. +:ref:`Key` **KEY_F27** = ``4194358`` -- **KEY_AT** = **64** --- @ key. +F27 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_A** = **65** --- A key. +.. _class_@GlobalScope_constant_KEY_F28: -- **KEY_B** = **66** --- B key. +.. rst-class:: classref-enumeration-constant -- **KEY_C** = **67** --- C key. +:ref:`Key` **KEY_F28** = ``4194359`` -- **KEY_D** = **68** --- D key. +F28 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_E** = **69** --- E key. +.. _class_@GlobalScope_constant_KEY_F29: -- **KEY_F** = **70** --- F key. +.. rst-class:: classref-enumeration-constant -- **KEY_G** = **71** --- G key. +:ref:`Key` **KEY_F29** = ``4194360`` -- **KEY_H** = **72** --- H key. +F29 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_I** = **73** --- I key. +.. _class_@GlobalScope_constant_KEY_F30: -- **KEY_J** = **74** --- J key. +.. rst-class:: classref-enumeration-constant -- **KEY_K** = **75** --- K key. +:ref:`Key` **KEY_F30** = ``4194361`` -- **KEY_L** = **76** --- L key. +F30 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_M** = **77** --- M key. +.. _class_@GlobalScope_constant_KEY_F31: -- **KEY_N** = **78** --- N key. +.. rst-class:: classref-enumeration-constant -- **KEY_O** = **79** --- O key. +:ref:`Key` **KEY_F31** = ``4194362`` -- **KEY_P** = **80** --- P key. +F31 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_Q** = **81** --- Q key. +.. _class_@GlobalScope_constant_KEY_F32: -- **KEY_R** = **82** --- R key. +.. rst-class:: classref-enumeration-constant -- **KEY_S** = **83** --- S key. +:ref:`Key` **KEY_F32** = ``4194363`` -- **KEY_T** = **84** --- T key. +F32 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_U** = **85** --- U key. +.. _class_@GlobalScope_constant_KEY_F33: -- **KEY_V** = **86** --- V key. +.. rst-class:: classref-enumeration-constant -- **KEY_W** = **87** --- W key. +:ref:`Key` **KEY_F33** = ``4194364`` -- **KEY_X** = **88** --- X key. +F33 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_Y** = **89** --- Y key. +.. _class_@GlobalScope_constant_KEY_F34: -- **KEY_Z** = **90** --- Z key. +.. rst-class:: classref-enumeration-constant -- **KEY_BRACKETLEFT** = **91** --- [ key. +:ref:`Key` **KEY_F34** = ``4194365`` -- **KEY_BACKSLASH** = **92** --- \\ key. +F34 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_BRACKETRIGHT** = **93** --- ] key. +.. _class_@GlobalScope_constant_KEY_F35: -- **KEY_ASCIICIRCUM** = **94** --- ^ key. +.. rst-class:: classref-enumeration-constant -- **KEY_UNDERSCORE** = **95** --- \_ key. +:ref:`Key` **KEY_F35** = ``4194366`` -- **KEY_QUOTELEFT** = **96** --- ` key. +F35 key. Only supported on macOS and Linux due to a Windows limitation. -- **KEY_BRACELEFT** = **123** --- { key. +.. _class_@GlobalScope_constant_KEY_KP_MULTIPLY: -- **KEY_BAR** = **124** --- | key. +.. rst-class:: classref-enumeration-constant -- **KEY_BRACERIGHT** = **125** --- } key. +:ref:`Key` **KEY_KP_MULTIPLY** = ``4194433`` -- **KEY_ASCIITILDE** = **126** --- ~ key. +Multiply (\*) key on the numeric keypad. -- **KEY_NOBREAKSPACE** = **160** --- Non-breakable space key. +.. _class_@GlobalScope_constant_KEY_KP_DIVIDE: -- **KEY_EXCLAMDOWN** = **161** --- ¡ key. +.. rst-class:: classref-enumeration-constant -- **KEY_CENT** = **162** --- ¢ key. +:ref:`Key` **KEY_KP_DIVIDE** = ``4194434`` -- **KEY_STERLING** = **163** --- £ key. +Divide (/) key on the numeric keypad. -- **KEY_CURRENCY** = **164** --- ¤ key. +.. _class_@GlobalScope_constant_KEY_KP_SUBTRACT: -- **KEY_YEN** = **165** --- ¥ key. +.. rst-class:: classref-enumeration-constant -- **KEY_BROKENBAR** = **166** --- ¦ key. +:ref:`Key` **KEY_KP_SUBTRACT** = ``4194435`` -- **KEY_SECTION** = **167** --- § key. +Subtract (-) key on the numeric keypad. -- **KEY_DIAERESIS** = **168** --- ¨ key. +.. _class_@GlobalScope_constant_KEY_KP_PERIOD: -- **KEY_COPYRIGHT** = **169** --- © key. +.. rst-class:: classref-enumeration-constant -- **KEY_ORDFEMININE** = **170** --- ª key. +:ref:`Key` **KEY_KP_PERIOD** = ``4194436`` -- **KEY_GUILLEMOTLEFT** = **171** --- « key. +Period (.) key on the numeric keypad. -- **KEY_NOTSIGN** = **172** --- ¬ key. +.. _class_@GlobalScope_constant_KEY_KP_ADD: -- **KEY_HYPHEN** = **173** --- Soft hyphen key. +.. rst-class:: classref-enumeration-constant -- **KEY_REGISTERED** = **174** --- ® key. +:ref:`Key` **KEY_KP_ADD** = ``4194437`` -- **KEY_MACRON** = **175** --- ¯ key. +Add (+) key on the numeric keypad. -- **KEY_DEGREE** = **176** --- ° key. +.. _class_@GlobalScope_constant_KEY_KP_0: -- **KEY_PLUSMINUS** = **177** --- ± key. +.. rst-class:: classref-enumeration-constant -- **KEY_TWOSUPERIOR** = **178** --- ² key. +:ref:`Key` **KEY_KP_0** = ``4194438`` -- **KEY_THREESUPERIOR** = **179** --- ³ key. +Number 0 on the numeric keypad. -- **KEY_ACUTE** = **180** --- ´ key. +.. _class_@GlobalScope_constant_KEY_KP_1: -- **KEY_MU** = **181** --- µ key. +.. rst-class:: classref-enumeration-constant -- **KEY_PARAGRAPH** = **182** --- ¶ key. +:ref:`Key` **KEY_KP_1** = ``4194439`` -- **KEY_PERIODCENTERED** = **183** --- · key. +Number 1 on the numeric keypad. -- **KEY_CEDILLA** = **184** --- ¸ key. +.. _class_@GlobalScope_constant_KEY_KP_2: -- **KEY_ONESUPERIOR** = **185** --- ¹ key. +.. rst-class:: classref-enumeration-constant -- **KEY_MASCULINE** = **186** --- º key. +:ref:`Key` **KEY_KP_2** = ``4194440`` -- **KEY_GUILLEMOTRIGHT** = **187** --- » key. +Number 2 on the numeric keypad. -- **KEY_ONEQUARTER** = **188** --- ¼ key. +.. _class_@GlobalScope_constant_KEY_KP_3: -- **KEY_ONEHALF** = **189** --- ½ key. +.. rst-class:: classref-enumeration-constant -- **KEY_THREEQUARTERS** = **190** --- ¾ key. +:ref:`Key` **KEY_KP_3** = ``4194441`` -- **KEY_QUESTIONDOWN** = **191** --- ¿ key. +Number 3 on the numeric keypad. -- **KEY_AGRAVE** = **192** --- À key. +.. _class_@GlobalScope_constant_KEY_KP_4: -- **KEY_AACUTE** = **193** --- Á key. +.. rst-class:: classref-enumeration-constant -- **KEY_ACIRCUMFLEX** = **194** --- Â key. +:ref:`Key` **KEY_KP_4** = ``4194442`` -- **KEY_ATILDE** = **195** --- Ã key. +Number 4 on the numeric keypad. -- **KEY_ADIAERESIS** = **196** --- Ä key. +.. _class_@GlobalScope_constant_KEY_KP_5: -- **KEY_ARING** = **197** --- Å key. +.. rst-class:: classref-enumeration-constant -- **KEY_AE** = **198** --- Æ key. +:ref:`Key` **KEY_KP_5** = ``4194443`` -- **KEY_CCEDILLA** = **199** --- Ç key. +Number 5 on the numeric keypad. -- **KEY_EGRAVE** = **200** --- È key. +.. _class_@GlobalScope_constant_KEY_KP_6: -- **KEY_EACUTE** = **201** --- É key. +.. rst-class:: classref-enumeration-constant -- **KEY_ECIRCUMFLEX** = **202** --- Ê key. +:ref:`Key` **KEY_KP_6** = ``4194444`` -- **KEY_EDIAERESIS** = **203** --- Ë key. +Number 6 on the numeric keypad. -- **KEY_IGRAVE** = **204** --- Ì key. +.. _class_@GlobalScope_constant_KEY_KP_7: -- **KEY_IACUTE** = **205** --- Í key. +.. rst-class:: classref-enumeration-constant -- **KEY_ICIRCUMFLEX** = **206** --- Î key. +:ref:`Key` **KEY_KP_7** = ``4194445`` -- **KEY_IDIAERESIS** = **207** --- Ï key. +Number 7 on the numeric keypad. -- **KEY_ETH** = **208** --- Ð key. +.. _class_@GlobalScope_constant_KEY_KP_8: -- **KEY_NTILDE** = **209** --- Ñ key. +.. rst-class:: classref-enumeration-constant -- **KEY_OGRAVE** = **210** --- Ò key. +:ref:`Key` **KEY_KP_8** = ``4194446`` -- **KEY_OACUTE** = **211** --- Ó key. +Number 8 on the numeric keypad. -- **KEY_OCIRCUMFLEX** = **212** --- Ô key. +.. _class_@GlobalScope_constant_KEY_KP_9: -- **KEY_OTILDE** = **213** --- Õ key. +.. rst-class:: classref-enumeration-constant -- **KEY_ODIAERESIS** = **214** --- Ö key. +:ref:`Key` **KEY_KP_9** = ``4194447`` -- **KEY_MULTIPLY** = **215** --- × key. +Number 9 on the numeric keypad. -- **KEY_OOBLIQUE** = **216** --- Ø key. +.. _class_@GlobalScope_constant_KEY_MENU: -- **KEY_UGRAVE** = **217** --- Ù key. +.. rst-class:: classref-enumeration-constant -- **KEY_UACUTE** = **218** --- Ú key. +:ref:`Key` **KEY_MENU** = ``4194370`` -- **KEY_UCIRCUMFLEX** = **219** --- Û key. +Context menu key. -- **KEY_UDIAERESIS** = **220** --- Ü key. +.. _class_@GlobalScope_constant_KEY_HYPER: -- **KEY_YACUTE** = **221** --- Ý key. +.. rst-class:: classref-enumeration-constant -- **KEY_THORN** = **222** --- Þ key. +:ref:`Key` **KEY_HYPER** = ``4194371`` -- **KEY_SSHARP** = **223** --- ß key. +Hyper key. (On Linux/X11 only). -- **KEY_DIVISION** = **247** --- ÷ key. +.. _class_@GlobalScope_constant_KEY_HELP: -- **KEY_YDIAERESIS** = **255** --- ÿ key. +.. rst-class:: classref-enumeration-constant ----- +:ref:`Key` **KEY_HELP** = ``4194373`` -.. _enum_@GlobalScope_KeyModifierMask: +Help key. -.. _class_@GlobalScope_constant_KEY_CODE_MASK: +.. _class_@GlobalScope_constant_KEY_BACK: -.. _class_@GlobalScope_constant_KEY_MODIFIER_MASK: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_MASK_SHIFT: +:ref:`Key` **KEY_BACK** = ``4194376`` -.. _class_@GlobalScope_constant_KEY_MASK_ALT: +Back key. -.. _class_@GlobalScope_constant_KEY_MASK_META: +.. _class_@GlobalScope_constant_KEY_FORWARD: -.. _class_@GlobalScope_constant_KEY_MASK_CTRL: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_KEY_MASK_CMD: +:ref:`Key` **KEY_FORWARD** = ``4194377`` -.. _class_@GlobalScope_constant_KEY_MASK_KPAD: +Forward key. -.. _class_@GlobalScope_constant_KEY_MASK_GROUP_SWITCH: +.. _class_@GlobalScope_constant_KEY_STOP: -enum **KeyModifierMask**: +.. rst-class:: classref-enumeration-constant -- **KEY_CODE_MASK** = **33554431** --- Key Code mask. +:ref:`Key` **KEY_STOP** = ``4194378`` -- **KEY_MODIFIER_MASK** = **-16777216** --- Modifier key mask. +Media stop key. -- **KEY_MASK_SHIFT** = **33554432** --- Shift key mask. +.. _class_@GlobalScope_constant_KEY_REFRESH: -- **KEY_MASK_ALT** = **67108864** --- Alt key mask. +.. rst-class:: classref-enumeration-constant -- **KEY_MASK_META** = **134217728** --- Meta key mask. +:ref:`Key` **KEY_REFRESH** = ``4194379`` -- **KEY_MASK_CTRL** = **268435456** --- Ctrl key mask. +Refresh key. -- **KEY_MASK_CMD** = **268435456** --- Command key mask. On macOS, this is equivalent to :ref:`KEY_MASK_META`. On other platforms, this is equivalent to :ref:`KEY_MASK_CTRL`. This mask should be preferred to :ref:`KEY_MASK_META` or :ref:`KEY_MASK_CTRL` for system shortcuts as it handles all platforms correctly. +.. _class_@GlobalScope_constant_KEY_VOLUMEDOWN: -- **KEY_MASK_KPAD** = **536870912** --- Keypad key mask. +.. rst-class:: classref-enumeration-constant -- **KEY_MASK_GROUP_SWITCH** = **1073741824** --- Group Switch key mask. +:ref:`Key` **KEY_VOLUMEDOWN** = ``4194380`` ----- +Volume down key. -.. _enum_@GlobalScope_ButtonList: +.. _class_@GlobalScope_constant_KEY_VOLUMEMUTE: -.. _class_@GlobalScope_constant_BUTTON_LEFT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_BUTTON_RIGHT: +:ref:`Key` **KEY_VOLUMEMUTE** = ``4194381`` -.. _class_@GlobalScope_constant_BUTTON_MIDDLE: +Mute volume key. -.. _class_@GlobalScope_constant_BUTTON_XBUTTON1: +.. _class_@GlobalScope_constant_KEY_VOLUMEUP: -.. _class_@GlobalScope_constant_BUTTON_XBUTTON2: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_BUTTON_WHEEL_UP: +:ref:`Key` **KEY_VOLUMEUP** = ``4194382`` -.. _class_@GlobalScope_constant_BUTTON_WHEEL_DOWN: +Volume up key. -.. _class_@GlobalScope_constant_BUTTON_WHEEL_LEFT: +.. _class_@GlobalScope_constant_KEY_MEDIAPLAY: -.. _class_@GlobalScope_constant_BUTTON_WHEEL_RIGHT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_BUTTON_MASK_LEFT: +:ref:`Key` **KEY_MEDIAPLAY** = ``4194388`` -.. _class_@GlobalScope_constant_BUTTON_MASK_RIGHT: +Media play key. -.. _class_@GlobalScope_constant_BUTTON_MASK_MIDDLE: +.. _class_@GlobalScope_constant_KEY_MEDIASTOP: -.. _class_@GlobalScope_constant_BUTTON_MASK_XBUTTON1: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_BUTTON_MASK_XBUTTON2: +:ref:`Key` **KEY_MEDIASTOP** = ``4194389`` -enum **ButtonList**: +Media stop key. -- **BUTTON_LEFT** = **1** --- Left mouse button. +.. _class_@GlobalScope_constant_KEY_MEDIAPREVIOUS: -- **BUTTON_RIGHT** = **2** --- Right mouse button. +.. rst-class:: classref-enumeration-constant -- **BUTTON_MIDDLE** = **3** --- Middle mouse button. +:ref:`Key` **KEY_MEDIAPREVIOUS** = ``4194390`` -- **BUTTON_XBUTTON1** = **8** --- Extra mouse button 1 (only present on some mice). +Previous song key. -- **BUTTON_XBUTTON2** = **9** --- Extra mouse button 2 (only present on some mice). +.. _class_@GlobalScope_constant_KEY_MEDIANEXT: -- **BUTTON_WHEEL_UP** = **4** --- Mouse wheel up. +.. rst-class:: classref-enumeration-constant -- **BUTTON_WHEEL_DOWN** = **5** --- Mouse wheel down. +:ref:`Key` **KEY_MEDIANEXT** = ``4194391`` -- **BUTTON_WHEEL_LEFT** = **6** --- Mouse wheel left button (only present on some mice). +Next song key. -- **BUTTON_WHEEL_RIGHT** = **7** --- Mouse wheel right button (only present on some mice). +.. _class_@GlobalScope_constant_KEY_MEDIARECORD: -- **BUTTON_MASK_LEFT** = **1** --- Left mouse button mask. +.. rst-class:: classref-enumeration-constant -- **BUTTON_MASK_RIGHT** = **2** --- Right mouse button mask. +:ref:`Key` **KEY_MEDIARECORD** = ``4194392`` -- **BUTTON_MASK_MIDDLE** = **4** --- Middle mouse button mask. +Media record key. -- **BUTTON_MASK_XBUTTON1** = **128** --- Extra mouse button 1 mask. +.. _class_@GlobalScope_constant_KEY_HOMEPAGE: -- **BUTTON_MASK_XBUTTON2** = **256** --- Extra mouse button 2 mask. +.. rst-class:: classref-enumeration-constant ----- +:ref:`Key` **KEY_HOMEPAGE** = ``4194393`` -.. _enum_@GlobalScope_JoystickList: +Home page key. -.. _class_@GlobalScope_constant_JOY_BUTTON_0: +.. _class_@GlobalScope_constant_KEY_FAVORITES: -.. _class_@GlobalScope_constant_JOY_BUTTON_1: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_BUTTON_2: +:ref:`Key` **KEY_FAVORITES** = ``4194394`` -.. _class_@GlobalScope_constant_JOY_BUTTON_3: +Favorites key. -.. _class_@GlobalScope_constant_JOY_BUTTON_4: +.. _class_@GlobalScope_constant_KEY_SEARCH: -.. _class_@GlobalScope_constant_JOY_BUTTON_5: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_BUTTON_6: +:ref:`Key` **KEY_SEARCH** = ``4194395`` -.. _class_@GlobalScope_constant_JOY_BUTTON_7: +Search key. -.. _class_@GlobalScope_constant_JOY_BUTTON_8: +.. _class_@GlobalScope_constant_KEY_STANDBY: -.. _class_@GlobalScope_constant_JOY_BUTTON_9: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_BUTTON_10: +:ref:`Key` **KEY_STANDBY** = ``4194396`` -.. _class_@GlobalScope_constant_JOY_BUTTON_11: +Standby key. -.. _class_@GlobalScope_constant_JOY_BUTTON_12: +.. _class_@GlobalScope_constant_KEY_OPENURL: -.. _class_@GlobalScope_constant_JOY_BUTTON_13: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_BUTTON_14: +:ref:`Key` **KEY_OPENURL** = ``4194397`` -.. _class_@GlobalScope_constant_JOY_BUTTON_15: +Open URL / Launch Browser key. -.. _class_@GlobalScope_constant_JOY_BUTTON_MAX: +.. _class_@GlobalScope_constant_KEY_LAUNCHMAIL: -.. _class_@GlobalScope_constant_JOY_SONY_CIRCLE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_SONY_X: +:ref:`Key` **KEY_LAUNCHMAIL** = ``4194398`` -.. _class_@GlobalScope_constant_JOY_SONY_SQUARE: +Launch Mail key. -.. _class_@GlobalScope_constant_JOY_SONY_TRIANGLE: +.. _class_@GlobalScope_constant_KEY_LAUNCHMEDIA: -.. _class_@GlobalScope_constant_JOY_XBOX_B: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_XBOX_A: +:ref:`Key` **KEY_LAUNCHMEDIA** = ``4194399`` -.. _class_@GlobalScope_constant_JOY_XBOX_X: +Launch Media key. -.. _class_@GlobalScope_constant_JOY_XBOX_Y: +.. _class_@GlobalScope_constant_KEY_LAUNCH0: -.. _class_@GlobalScope_constant_JOY_DS_A: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_DS_B: +:ref:`Key` **KEY_LAUNCH0** = ``4194400`` -.. _class_@GlobalScope_constant_JOY_DS_X: +Launch Shortcut 0 key. -.. _class_@GlobalScope_constant_JOY_DS_Y: +.. _class_@GlobalScope_constant_KEY_LAUNCH1: -.. _class_@GlobalScope_constant_JOY_VR_GRIP: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_VR_PAD: +:ref:`Key` **KEY_LAUNCH1** = ``4194401`` -.. _class_@GlobalScope_constant_JOY_VR_TRIGGER: +Launch Shortcut 1 key. -.. _class_@GlobalScope_constant_JOY_OCULUS_AX: +.. _class_@GlobalScope_constant_KEY_LAUNCH2: -.. _class_@GlobalScope_constant_JOY_OCULUS_BY: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_OCULUS_MENU: +:ref:`Key` **KEY_LAUNCH2** = ``4194402`` -.. _class_@GlobalScope_constant_JOY_OPENVR_MENU: +Launch Shortcut 2 key. -.. _class_@GlobalScope_constant_JOY_SELECT: +.. _class_@GlobalScope_constant_KEY_LAUNCH3: -.. _class_@GlobalScope_constant_JOY_START: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_DPAD_UP: +:ref:`Key` **KEY_LAUNCH3** = ``4194403`` -.. _class_@GlobalScope_constant_JOY_DPAD_DOWN: +Launch Shortcut 3 key. -.. _class_@GlobalScope_constant_JOY_DPAD_LEFT: +.. _class_@GlobalScope_constant_KEY_LAUNCH4: -.. _class_@GlobalScope_constant_JOY_DPAD_RIGHT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_L: +:ref:`Key` **KEY_LAUNCH4** = ``4194404`` -.. _class_@GlobalScope_constant_JOY_L2: +Launch Shortcut 4 key. -.. _class_@GlobalScope_constant_JOY_L3: +.. _class_@GlobalScope_constant_KEY_LAUNCH5: -.. _class_@GlobalScope_constant_JOY_R: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_R2: +:ref:`Key` **KEY_LAUNCH5** = ``4194405`` -.. _class_@GlobalScope_constant_JOY_R3: +Launch Shortcut 5 key. -.. _class_@GlobalScope_constant_JOY_AXIS_0: +.. _class_@GlobalScope_constant_KEY_LAUNCH6: -.. _class_@GlobalScope_constant_JOY_AXIS_1: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_AXIS_2: +:ref:`Key` **KEY_LAUNCH6** = ``4194406`` -.. _class_@GlobalScope_constant_JOY_AXIS_3: +Launch Shortcut 6 key. -.. _class_@GlobalScope_constant_JOY_AXIS_4: +.. _class_@GlobalScope_constant_KEY_LAUNCH7: -.. _class_@GlobalScope_constant_JOY_AXIS_5: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_AXIS_6: +:ref:`Key` **KEY_LAUNCH7** = ``4194407`` -.. _class_@GlobalScope_constant_JOY_AXIS_7: +Launch Shortcut 7 key. -.. _class_@GlobalScope_constant_JOY_AXIS_8: +.. _class_@GlobalScope_constant_KEY_LAUNCH8: -.. _class_@GlobalScope_constant_JOY_AXIS_9: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_AXIS_MAX: +:ref:`Key` **KEY_LAUNCH8** = ``4194408`` -.. _class_@GlobalScope_constant_JOY_ANALOG_LX: +Launch Shortcut 8 key. -.. _class_@GlobalScope_constant_JOY_ANALOG_LY: +.. _class_@GlobalScope_constant_KEY_LAUNCH9: -.. _class_@GlobalScope_constant_JOY_ANALOG_RX: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_ANALOG_RY: +:ref:`Key` **KEY_LAUNCH9** = ``4194409`` -.. _class_@GlobalScope_constant_JOY_ANALOG_L2: +Launch Shortcut 9 key. -.. _class_@GlobalScope_constant_JOY_ANALOG_R2: +.. _class_@GlobalScope_constant_KEY_LAUNCHA: -.. _class_@GlobalScope_constant_JOY_VR_ANALOG_TRIGGER: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_JOY_VR_ANALOG_GRIP: +:ref:`Key` **KEY_LAUNCHA** = ``4194410`` -.. _class_@GlobalScope_constant_JOY_OPENVR_TOUCHPADX: +Launch Shortcut A key. -.. _class_@GlobalScope_constant_JOY_OPENVR_TOUCHPADY: +.. _class_@GlobalScope_constant_KEY_LAUNCHB: -enum **JoystickList**: +.. rst-class:: classref-enumeration-constant -- **JOY_BUTTON_0** = **0** --- Gamepad button 0. +:ref:`Key` **KEY_LAUNCHB** = ``4194411`` -- **JOY_BUTTON_1** = **1** --- Gamepad button 1. +Launch Shortcut B key. -- **JOY_BUTTON_2** = **2** --- Gamepad button 2. +.. _class_@GlobalScope_constant_KEY_LAUNCHC: -- **JOY_BUTTON_3** = **3** --- Gamepad button 3. +.. rst-class:: classref-enumeration-constant -- **JOY_BUTTON_4** = **4** --- Gamepad button 4. +:ref:`Key` **KEY_LAUNCHC** = ``4194412`` -- **JOY_BUTTON_5** = **5** --- Gamepad button 5. +Launch Shortcut C key. -- **JOY_BUTTON_6** = **6** --- Gamepad button 6. +.. _class_@GlobalScope_constant_KEY_LAUNCHD: -- **JOY_BUTTON_7** = **7** --- Gamepad button 7. +.. rst-class:: classref-enumeration-constant -- **JOY_BUTTON_8** = **8** --- Gamepad button 8. +:ref:`Key` **KEY_LAUNCHD** = ``4194413`` -- **JOY_BUTTON_9** = **9** --- Gamepad button 9. +Launch Shortcut D key. -- **JOY_BUTTON_10** = **10** --- Gamepad button 10. +.. _class_@GlobalScope_constant_KEY_LAUNCHE: -- **JOY_BUTTON_11** = **11** --- Gamepad button 11. +.. rst-class:: classref-enumeration-constant -- **JOY_BUTTON_12** = **12** --- Gamepad button 12. +:ref:`Key` **KEY_LAUNCHE** = ``4194414`` -- **JOY_BUTTON_13** = **13** --- Gamepad button 13. +Launch Shortcut E key. -- **JOY_BUTTON_14** = **14** --- Gamepad button 14. +.. _class_@GlobalScope_constant_KEY_LAUNCHF: -- **JOY_BUTTON_15** = **15** --- Gamepad button 15. +.. rst-class:: classref-enumeration-constant -- **JOY_BUTTON_MAX** = **16** --- Represents the maximum number of joystick buttons supported. +:ref:`Key` **KEY_LAUNCHF** = ``4194415`` -- **JOY_SONY_CIRCLE** = **1** --- DualShock circle button. +Launch Shortcut F key. -- **JOY_SONY_X** = **0** --- DualShock X button. +.. _class_@GlobalScope_constant_KEY_GLOBE: -- **JOY_SONY_SQUARE** = **2** --- DualShock square button. +.. rst-class:: classref-enumeration-constant -- **JOY_SONY_TRIANGLE** = **3** --- DualShock triangle button. +:ref:`Key` **KEY_GLOBE** = ``4194416`` -- **JOY_XBOX_B** = **1** --- Xbox controller B button. +"Globe" key on Mac / iPad keyboard. -- **JOY_XBOX_A** = **0** --- Xbox controller A button. +.. _class_@GlobalScope_constant_KEY_KEYBOARD: -- **JOY_XBOX_X** = **2** --- Xbox controller X button. +.. rst-class:: classref-enumeration-constant -- **JOY_XBOX_Y** = **3** --- Xbox controller Y button. +:ref:`Key` **KEY_KEYBOARD** = ``4194417`` -- **JOY_DS_A** = **1** --- Nintendo controller A button. +"On-screen keyboard" key on iPad keyboard. -- **JOY_DS_B** = **0** --- Nintendo controller B button. +.. _class_@GlobalScope_constant_KEY_JIS_EISU: -- **JOY_DS_X** = **3** --- Nintendo controller X button. +.. rst-class:: classref-enumeration-constant -- **JOY_DS_Y** = **2** --- Nintendo controller Y button. +:ref:`Key` **KEY_JIS_EISU** = ``4194418`` -- **JOY_VR_GRIP** = **2** --- Grip (side) buttons on a VR controller. +英数 key on Mac keyboard. -- **JOY_VR_PAD** = **14** --- Push down on the touchpad or main joystick on a VR controller. +.. _class_@GlobalScope_constant_KEY_JIS_KANA: -- **JOY_VR_TRIGGER** = **15** --- Trigger on a VR controller. +.. rst-class:: classref-enumeration-constant -- **JOY_OCULUS_AX** = **7** --- A button on the right Oculus Touch controller, X button on the left controller (also when used in OpenVR). +:ref:`Key` **KEY_JIS_KANA** = ``4194419`` -- **JOY_OCULUS_BY** = **1** --- B button on the right Oculus Touch controller, Y button on the left controller (also when used in OpenVR). +かな key on Mac keyboard. -- **JOY_OCULUS_MENU** = **3** --- Menu button on either Oculus Touch controller. +.. _class_@GlobalScope_constant_KEY_UNKNOWN: -- **JOY_OPENVR_MENU** = **1** --- Menu button in OpenVR (Except when Oculus Touch controllers are used). +.. rst-class:: classref-enumeration-constant -- **JOY_SELECT** = **10** --- Gamepad button Select. +:ref:`Key` **KEY_UNKNOWN** = ``8388607`` -- **JOY_START** = **11** --- Gamepad button Start. +Unknown key. -- **JOY_DPAD_UP** = **12** --- Gamepad DPad up. +.. _class_@GlobalScope_constant_KEY_SPACE: -- **JOY_DPAD_DOWN** = **13** --- Gamepad DPad down. +.. rst-class:: classref-enumeration-constant -- **JOY_DPAD_LEFT** = **14** --- Gamepad DPad left. +:ref:`Key` **KEY_SPACE** = ``32`` -- **JOY_DPAD_RIGHT** = **15** --- Gamepad DPad right. +Space key. -- **JOY_L** = **4** --- Gamepad left Shoulder button. +.. _class_@GlobalScope_constant_KEY_EXCLAM: -- **JOY_L2** = **6** --- Gamepad left trigger. +.. rst-class:: classref-enumeration-constant -- **JOY_L3** = **8** --- Gamepad left stick click. +:ref:`Key` **KEY_EXCLAM** = ``33`` -- **JOY_R** = **5** --- Gamepad right Shoulder button. +Exclamation mark (``!``) key. -- **JOY_R2** = **7** --- Gamepad right trigger. +.. _class_@GlobalScope_constant_KEY_QUOTEDBL: -- **JOY_R3** = **9** --- Gamepad right stick click. +.. rst-class:: classref-enumeration-constant -- **JOY_AXIS_0** = **0** --- Gamepad left stick horizontal axis. +:ref:`Key` **KEY_QUOTEDBL** = ``34`` -- **JOY_AXIS_1** = **1** --- Gamepad left stick vertical axis. +Double quotation mark (``"``) key. -- **JOY_AXIS_2** = **2** --- Gamepad right stick horizontal axis. +.. _class_@GlobalScope_constant_KEY_NUMBERSIGN: -- **JOY_AXIS_3** = **3** --- Gamepad right stick vertical axis. +.. rst-class:: classref-enumeration-constant -- **JOY_AXIS_4** = **4** --- Generic gamepad axis 4. +:ref:`Key` **KEY_NUMBERSIGN** = ``35`` -- **JOY_AXIS_5** = **5** --- Generic gamepad axis 5. +Number sign or *hash* (``#``) key. -- **JOY_AXIS_6** = **6** --- Gamepad left trigger analog axis. +.. _class_@GlobalScope_constant_KEY_DOLLAR: -- **JOY_AXIS_7** = **7** --- Gamepad right trigger analog axis. +.. rst-class:: classref-enumeration-constant -- **JOY_AXIS_8** = **8** --- Generic gamepad axis 8. +:ref:`Key` **KEY_DOLLAR** = ``36`` -- **JOY_AXIS_9** = **9** --- Generic gamepad axis 9. +Dollar sign (``$``) key. -- **JOY_AXIS_MAX** = **10** --- Represents the maximum number of joystick axes supported. +.. _class_@GlobalScope_constant_KEY_PERCENT: -- **JOY_ANALOG_LX** = **0** --- Gamepad left stick horizontal axis. +.. rst-class:: classref-enumeration-constant -- **JOY_ANALOG_LY** = **1** --- Gamepad left stick vertical axis. +:ref:`Key` **KEY_PERCENT** = ``37`` -- **JOY_ANALOG_RX** = **2** --- Gamepad right stick horizontal axis. +Percent sign (``%``) key. -- **JOY_ANALOG_RY** = **3** --- Gamepad right stick vertical axis. +.. _class_@GlobalScope_constant_KEY_AMPERSAND: -- **JOY_ANALOG_L2** = **6** --- Gamepad left analog trigger. +.. rst-class:: classref-enumeration-constant -- **JOY_ANALOG_R2** = **7** --- Gamepad right analog trigger. +:ref:`Key` **KEY_AMPERSAND** = ``38`` -- **JOY_VR_ANALOG_TRIGGER** = **2** --- VR Controller analog trigger. +Ampersand (``&``) key. -- **JOY_VR_ANALOG_GRIP** = **4** --- VR Controller analog grip (side buttons). +.. _class_@GlobalScope_constant_KEY_APOSTROPHE: -- **JOY_OPENVR_TOUCHPADX** = **0** --- OpenVR touchpad X axis (Joystick axis on Oculus Touch and Windows MR controllers). +.. rst-class:: classref-enumeration-constant -- **JOY_OPENVR_TOUCHPADY** = **1** --- OpenVR touchpad Y axis (Joystick axis on Oculus Touch and Windows MR controllers). +:ref:`Key` **KEY_APOSTROPHE** = ``39`` ----- +Apostrophe (``'``) key. -.. _enum_@GlobalScope_MidiMessageList: +.. _class_@GlobalScope_constant_KEY_PARENLEFT: -.. _class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_OFF: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_ON: +:ref:`Key` **KEY_PARENLEFT** = ``40`` -.. _class_@GlobalScope_constant_MIDI_MESSAGE_AFTERTOUCH: +Left parenthesis (``(``) key. -.. _class_@GlobalScope_constant_MIDI_MESSAGE_CONTROL_CHANGE: +.. _class_@GlobalScope_constant_KEY_PARENRIGHT: -.. _class_@GlobalScope_constant_MIDI_MESSAGE_PROGRAM_CHANGE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_MIDI_MESSAGE_CHANNEL_PRESSURE: +:ref:`Key` **KEY_PARENRIGHT** = ``41`` -.. _class_@GlobalScope_constant_MIDI_MESSAGE_PITCH_BEND: +Right parenthesis (``)``) key. -enum **MidiMessageList**: +.. _class_@GlobalScope_constant_KEY_ASTERISK: -- **MIDI_MESSAGE_NOTE_OFF** = **8** --- MIDI note OFF message. +.. rst-class:: classref-enumeration-constant -- **MIDI_MESSAGE_NOTE_ON** = **9** --- MIDI note ON message. +:ref:`Key` **KEY_ASTERISK** = ``42`` -- **MIDI_MESSAGE_AFTERTOUCH** = **10** --- MIDI aftertouch message. +Asterisk (``*``) key. -- **MIDI_MESSAGE_CONTROL_CHANGE** = **11** --- MIDI control change message. +.. _class_@GlobalScope_constant_KEY_PLUS: -- **MIDI_MESSAGE_PROGRAM_CHANGE** = **12** --- MIDI program change message. +.. rst-class:: classref-enumeration-constant -- **MIDI_MESSAGE_CHANNEL_PRESSURE** = **13** --- MIDI channel pressure message. +:ref:`Key` **KEY_PLUS** = ``43`` -- **MIDI_MESSAGE_PITCH_BEND** = **14** --- MIDI pitch bend message. +Plus (``+``) key. ----- +.. _class_@GlobalScope_constant_KEY_COMMA: -.. _enum_@GlobalScope_Error: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_OK: +:ref:`Key` **KEY_COMMA** = ``44`` -.. _class_@GlobalScope_constant_FAILED: +Comma (``,``) key. -.. _class_@GlobalScope_constant_ERR_UNAVAILABLE: +.. _class_@GlobalScope_constant_KEY_MINUS: -.. _class_@GlobalScope_constant_ERR_UNCONFIGURED: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_UNAUTHORIZED: +:ref:`Key` **KEY_MINUS** = ``45`` -.. _class_@GlobalScope_constant_ERR_PARAMETER_RANGE_ERROR: +Minus (``-``) key. -.. _class_@GlobalScope_constant_ERR_OUT_OF_MEMORY: +.. _class_@GlobalScope_constant_KEY_PERIOD: -.. _class_@GlobalScope_constant_ERR_FILE_NOT_FOUND: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_FILE_BAD_DRIVE: +:ref:`Key` **KEY_PERIOD** = ``46`` -.. _class_@GlobalScope_constant_ERR_FILE_BAD_PATH: +Period (``.``) key. -.. _class_@GlobalScope_constant_ERR_FILE_NO_PERMISSION: +.. _class_@GlobalScope_constant_KEY_SLASH: -.. _class_@GlobalScope_constant_ERR_FILE_ALREADY_IN_USE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_FILE_CANT_OPEN: +:ref:`Key` **KEY_SLASH** = ``47`` -.. _class_@GlobalScope_constant_ERR_FILE_CANT_WRITE: +Slash (``/``) key. -.. _class_@GlobalScope_constant_ERR_FILE_CANT_READ: +.. _class_@GlobalScope_constant_KEY_0: -.. _class_@GlobalScope_constant_ERR_FILE_UNRECOGNIZED: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_FILE_CORRUPT: +:ref:`Key` **KEY_0** = ``48`` -.. _class_@GlobalScope_constant_ERR_FILE_MISSING_DEPENDENCIES: +Number 0 key. -.. _class_@GlobalScope_constant_ERR_FILE_EOF: +.. _class_@GlobalScope_constant_KEY_1: -.. _class_@GlobalScope_constant_ERR_CANT_OPEN: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_CANT_CREATE: +:ref:`Key` **KEY_1** = ``49`` -.. _class_@GlobalScope_constant_ERR_QUERY_FAILED: +Number 1 key. -.. _class_@GlobalScope_constant_ERR_ALREADY_IN_USE: +.. _class_@GlobalScope_constant_KEY_2: -.. _class_@GlobalScope_constant_ERR_LOCKED: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_TIMEOUT: +:ref:`Key` **KEY_2** = ``50`` -.. _class_@GlobalScope_constant_ERR_CANT_CONNECT: +Number 2 key. -.. _class_@GlobalScope_constant_ERR_CANT_RESOLVE: +.. _class_@GlobalScope_constant_KEY_3: -.. _class_@GlobalScope_constant_ERR_CONNECTION_ERROR: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_CANT_ACQUIRE_RESOURCE: +:ref:`Key` **KEY_3** = ``51`` -.. _class_@GlobalScope_constant_ERR_CANT_FORK: +Number 3 key. -.. _class_@GlobalScope_constant_ERR_INVALID_DATA: +.. _class_@GlobalScope_constant_KEY_4: -.. _class_@GlobalScope_constant_ERR_INVALID_PARAMETER: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_ALREADY_EXISTS: +:ref:`Key` **KEY_4** = ``52`` -.. _class_@GlobalScope_constant_ERR_DOES_NOT_EXIST: +Number 4 key. -.. _class_@GlobalScope_constant_ERR_DATABASE_CANT_READ: +.. _class_@GlobalScope_constant_KEY_5: -.. _class_@GlobalScope_constant_ERR_DATABASE_CANT_WRITE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_COMPILATION_FAILED: +:ref:`Key` **KEY_5** = ``53`` -.. _class_@GlobalScope_constant_ERR_METHOD_NOT_FOUND: +Number 5 key. -.. _class_@GlobalScope_constant_ERR_LINK_FAILED: +.. _class_@GlobalScope_constant_KEY_6: -.. _class_@GlobalScope_constant_ERR_SCRIPT_FAILED: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_CYCLIC_LINK: +:ref:`Key` **KEY_6** = ``54`` -.. _class_@GlobalScope_constant_ERR_INVALID_DECLARATION: +Number 6 key. -.. _class_@GlobalScope_constant_ERR_DUPLICATE_SYMBOL: +.. _class_@GlobalScope_constant_KEY_7: -.. _class_@GlobalScope_constant_ERR_PARSE_ERROR: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_BUSY: +:ref:`Key` **KEY_7** = ``55`` -.. _class_@GlobalScope_constant_ERR_SKIP: +Number 7 key. -.. _class_@GlobalScope_constant_ERR_HELP: +.. _class_@GlobalScope_constant_KEY_8: -.. _class_@GlobalScope_constant_ERR_BUG: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_ERR_PRINTER_ON_FIRE: +:ref:`Key` **KEY_8** = ``56`` -enum **Error**: +Number 8 key. -- **OK** = **0** --- Methods that return :ref:`Error` return :ref:`OK` when no error occurred. Note that many functions don't return an error code but will print error messages to standard output. +.. _class_@GlobalScope_constant_KEY_9: -Since :ref:`OK` has value 0, and all other failure codes are positive integers, it can also be used in boolean checks, e.g.: +.. rst-class:: classref-enumeration-constant -:: +:ref:`Key` **KEY_9** = ``57`` - var err = method_that_returns_error() - if err != OK: - print("Failure!) - # Or, equivalent: - if err: - print("Still failing!) +Number 9 key. -- **FAILED** = **1** --- Generic error. +.. _class_@GlobalScope_constant_KEY_COLON: -- **ERR_UNAVAILABLE** = **2** --- Unavailable error. +.. rst-class:: classref-enumeration-constant -- **ERR_UNCONFIGURED** = **3** --- Unconfigured error. +:ref:`Key` **KEY_COLON** = ``58`` -- **ERR_UNAUTHORIZED** = **4** --- Unauthorized error. +Colon (``:``) key. -- **ERR_PARAMETER_RANGE_ERROR** = **5** --- Parameter range error. +.. _class_@GlobalScope_constant_KEY_SEMICOLON: -- **ERR_OUT_OF_MEMORY** = **6** --- Out of memory (OOM) error. +.. rst-class:: classref-enumeration-constant -- **ERR_FILE_NOT_FOUND** = **7** --- File: Not found error. +:ref:`Key` **KEY_SEMICOLON** = ``59`` -- **ERR_FILE_BAD_DRIVE** = **8** --- File: Bad drive error. +Semicolon (``;``) key. -- **ERR_FILE_BAD_PATH** = **9** --- File: Bad path error. +.. _class_@GlobalScope_constant_KEY_LESS: -- **ERR_FILE_NO_PERMISSION** = **10** --- File: No permission error. +.. rst-class:: classref-enumeration-constant -- **ERR_FILE_ALREADY_IN_USE** = **11** --- File: Already in use error. +:ref:`Key` **KEY_LESS** = ``60`` -- **ERR_FILE_CANT_OPEN** = **12** --- File: Can't open error. +Less-than sign (``<``) key. -- **ERR_FILE_CANT_WRITE** = **13** --- File: Can't write error. +.. _class_@GlobalScope_constant_KEY_EQUAL: -- **ERR_FILE_CANT_READ** = **14** --- File: Can't read error. +.. rst-class:: classref-enumeration-constant -- **ERR_FILE_UNRECOGNIZED** = **15** --- File: Unrecognized error. +:ref:`Key` **KEY_EQUAL** = ``61`` -- **ERR_FILE_CORRUPT** = **16** --- File: Corrupt error. +Equal sign (``=``) key. -- **ERR_FILE_MISSING_DEPENDENCIES** = **17** --- File: Missing dependencies error. +.. _class_@GlobalScope_constant_KEY_GREATER: -- **ERR_FILE_EOF** = **18** --- File: End of file (EOF) error. +.. rst-class:: classref-enumeration-constant -- **ERR_CANT_OPEN** = **19** --- Can't open error. +:ref:`Key` **KEY_GREATER** = ``62`` -- **ERR_CANT_CREATE** = **20** --- Can't create error. +Greater-than sign (``>``) key. -- **ERR_QUERY_FAILED** = **21** --- Query failed error. +.. _class_@GlobalScope_constant_KEY_QUESTION: -- **ERR_ALREADY_IN_USE** = **22** --- Already in use error. +.. rst-class:: classref-enumeration-constant -- **ERR_LOCKED** = **23** --- Locked error. +:ref:`Key` **KEY_QUESTION** = ``63`` -- **ERR_TIMEOUT** = **24** --- Timeout error. +Question mark (``?``) key. -- **ERR_CANT_CONNECT** = **25** --- Can't connect error. +.. _class_@GlobalScope_constant_KEY_AT: -- **ERR_CANT_RESOLVE** = **26** --- Can't resolve error. +.. rst-class:: classref-enumeration-constant -- **ERR_CONNECTION_ERROR** = **27** --- Connection error. +:ref:`Key` **KEY_AT** = ``64`` -- **ERR_CANT_ACQUIRE_RESOURCE** = **28** --- Can't acquire resource error. +At sign (``@``) key. -- **ERR_CANT_FORK** = **29** --- Can't fork process error. +.. _class_@GlobalScope_constant_KEY_A: -- **ERR_INVALID_DATA** = **30** --- Invalid data error. +.. rst-class:: classref-enumeration-constant -- **ERR_INVALID_PARAMETER** = **31** --- Invalid parameter error. +:ref:`Key` **KEY_A** = ``65`` -- **ERR_ALREADY_EXISTS** = **32** --- Already exists error. +A key. -- **ERR_DOES_NOT_EXIST** = **33** --- Does not exist error. +.. _class_@GlobalScope_constant_KEY_B: -- **ERR_DATABASE_CANT_READ** = **34** --- Database: Read error. +.. rst-class:: classref-enumeration-constant -- **ERR_DATABASE_CANT_WRITE** = **35** --- Database: Write error. +:ref:`Key` **KEY_B** = ``66`` -- **ERR_COMPILATION_FAILED** = **36** --- Compilation failed error. +B key. -- **ERR_METHOD_NOT_FOUND** = **37** --- Method not found error. +.. _class_@GlobalScope_constant_KEY_C: -- **ERR_LINK_FAILED** = **38** --- Linking failed error. +.. rst-class:: classref-enumeration-constant -- **ERR_SCRIPT_FAILED** = **39** --- Script failed error. +:ref:`Key` **KEY_C** = ``67`` -- **ERR_CYCLIC_LINK** = **40** --- Cycling link (import cycle) error. +C key. -- **ERR_INVALID_DECLARATION** = **41** --- Invalid declaration error. +.. _class_@GlobalScope_constant_KEY_D: -- **ERR_DUPLICATE_SYMBOL** = **42** --- Duplicate symbol error. +.. rst-class:: classref-enumeration-constant -- **ERR_PARSE_ERROR** = **43** --- Parse error. +:ref:`Key` **KEY_D** = ``68`` -- **ERR_BUSY** = **44** --- Busy error. +D key. -- **ERR_SKIP** = **45** --- Skip error. +.. _class_@GlobalScope_constant_KEY_E: -- **ERR_HELP** = **46** --- Help error. +.. rst-class:: classref-enumeration-constant -- **ERR_BUG** = **47** --- Bug error. +:ref:`Key` **KEY_E** = ``69`` -- **ERR_PRINTER_ON_FIRE** = **48** --- Printer on fire error. (This is an easter egg, no engine methods return this error code.) +E key. ----- +.. _class_@GlobalScope_constant_KEY_F: -.. _enum_@GlobalScope_PropertyHint: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_HINT_NONE: +:ref:`Key` **KEY_F** = ``70`` -.. _class_@GlobalScope_constant_PROPERTY_HINT_RANGE: +F key. -.. _class_@GlobalScope_constant_PROPERTY_HINT_EXP_RANGE: +.. _class_@GlobalScope_constant_KEY_G: -.. _class_@GlobalScope_constant_PROPERTY_HINT_ENUM: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_HINT_EXP_EASING: +:ref:`Key` **KEY_G** = ``71`` -.. _class_@GlobalScope_constant_PROPERTY_HINT_LENGTH: +G key. -.. _class_@GlobalScope_constant_PROPERTY_HINT_KEY_ACCEL: +.. _class_@GlobalScope_constant_KEY_H: -.. _class_@GlobalScope_constant_PROPERTY_HINT_FLAGS: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_RENDER: +:ref:`Key` **KEY_H** = ``72`` -.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_PHYSICS: +H key. -.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_RENDER: +.. _class_@GlobalScope_constant_KEY_I: -.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_PHYSICS: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_HINT_FILE: +:ref:`Key` **KEY_I** = ``73`` -.. _class_@GlobalScope_constant_PROPERTY_HINT_DIR: +I key. -.. _class_@GlobalScope_constant_PROPERTY_HINT_GLOBAL_FILE: +.. _class_@GlobalScope_constant_KEY_J: -.. _class_@GlobalScope_constant_PROPERTY_HINT_GLOBAL_DIR: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_HINT_RESOURCE_TYPE: +:ref:`Key` **KEY_J** = ``74`` -.. _class_@GlobalScope_constant_PROPERTY_HINT_MULTILINE_TEXT: +J key. -.. _class_@GlobalScope_constant_PROPERTY_HINT_PLACEHOLDER_TEXT: +.. _class_@GlobalScope_constant_KEY_K: -.. _class_@GlobalScope_constant_PROPERTY_HINT_COLOR_NO_ALPHA: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_HINT_IMAGE_COMPRESS_LOSSY: +:ref:`Key` **KEY_K** = ``75`` -.. _class_@GlobalScope_constant_PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS: +K key. -enum **PropertyHint**: +.. _class_@GlobalScope_constant_KEY_L: -- **PROPERTY_HINT_NONE** = **0** --- No hint for the edited property. +.. rst-class:: classref-enumeration-constant -- **PROPERTY_HINT_RANGE** = **1** --- Hints that an integer or float property should be within a range specified via the hint string ``"min,max"`` or ``"min,max,step"``. The hint string can optionally include ``"or_greater"`` and/or ``"or_lesser"`` to allow manual input going respectively above the max or below the min values. Example: ``"-360,360,1,or_greater,or_lesser"``. +:ref:`Key` **KEY_L** = ``76`` -- **PROPERTY_HINT_EXP_RANGE** = **2** --- Hints that an integer or float property should be within an exponential range specified via the hint string ``"min,max"`` or ``"min,max,step"``. The hint string can optionally include ``"or_greater"`` and/or ``"or_lesser"`` to allow manual input going respectively above the max or below the min values. Example: ``"0.01,100,0.01,or_greater"``. +L key. -- **PROPERTY_HINT_ENUM** = **3** --- Hints that an integer, float or string property is an enumerated value to pick in a list specified via a hint string such as ``"Hello,Something,Else"``. +.. _class_@GlobalScope_constant_KEY_M: -- **PROPERTY_HINT_EXP_EASING** = **4** --- Hints that a float property should be edited via an exponential easing function. The hint string can include ``"attenuation"`` to flip the curve horizontally and/or ``"inout"`` to also include in/out easing. +.. rst-class:: classref-enumeration-constant -- **PROPERTY_HINT_LENGTH** = **5** --- Deprecated hint, unused. +:ref:`Key` **KEY_M** = ``77`` -- **PROPERTY_HINT_KEY_ACCEL** = **7** --- Deprecated hint, unused. +M key. -- **PROPERTY_HINT_FLAGS** = **8** --- Hints that an integer property is a bitmask with named bit flags. For example, to allow toggling bits 0, 1, 2 and 4, the hint could be something like ``"Bit0,Bit1,Bit2,,Bit4"``. +.. _class_@GlobalScope_constant_KEY_N: -- **PROPERTY_HINT_LAYERS_2D_RENDER** = **9** --- Hints that an integer property is a bitmask using the optionally named 2D render layers. +.. rst-class:: classref-enumeration-constant -- **PROPERTY_HINT_LAYERS_2D_PHYSICS** = **10** --- Hints that an integer property is a bitmask using the optionally named 2D physics layers. +:ref:`Key` **KEY_N** = ``78`` -- **PROPERTY_HINT_LAYERS_3D_RENDER** = **11** --- Hints that an integer property is a bitmask using the optionally named 3D render layers. +N key. -- **PROPERTY_HINT_LAYERS_3D_PHYSICS** = **12** --- Hints that an integer property is a bitmask using the optionally named 3D physics layers. +.. _class_@GlobalScope_constant_KEY_O: -- **PROPERTY_HINT_FILE** = **13** --- Hints that a string property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. +.. rst-class:: classref-enumeration-constant -- **PROPERTY_HINT_DIR** = **14** --- Hints that a string property is a path to a directory. Editing it will show a file dialog for picking the path. +:ref:`Key` **KEY_O** = ``79`` -- **PROPERTY_HINT_GLOBAL_FILE** = **15** --- Hints that a string property is an absolute path to a file outside the project folder. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. +O key. -- **PROPERTY_HINT_GLOBAL_DIR** = **16** --- Hints that a string property is an absolute path to a directory outside the project folder. Editing it will show a file dialog for picking the path. +.. _class_@GlobalScope_constant_KEY_P: -- **PROPERTY_HINT_RESOURCE_TYPE** = **17** --- Hints that a property is an instance of a :ref:`Resource`-derived type, optionally specified via the hint string (e.g. ``"Texture2D"``). Editing it will show a popup menu of valid resource types to instantiate. +.. rst-class:: classref-enumeration-constant -- **PROPERTY_HINT_MULTILINE_TEXT** = **18** --- Hints that a string property is text with line breaks. Editing it will show a text input field where line breaks can be typed. +:ref:`Key` **KEY_P** = ``80`` -- **PROPERTY_HINT_PLACEHOLDER_TEXT** = **19** --- Hints that a string property should have a placeholder text visible on its input field, whenever the property is empty. The hint string is the placeholder text to use. +P key. -- **PROPERTY_HINT_COLOR_NO_ALPHA** = **20** --- Hints that a color property should be edited without changing its alpha component, i.e. only R, G and B channels are edited. +.. _class_@GlobalScope_constant_KEY_Q: -- **PROPERTY_HINT_IMAGE_COMPRESS_LOSSY** = **21** --- Hints that an image is compressed using lossy compression. +.. rst-class:: classref-enumeration-constant -- **PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS** = **22** --- Hints that an image is compressed using lossless compression. +:ref:`Key` **KEY_Q** = ``81`` ----- +Q key. -.. _enum_@GlobalScope_PropertyUsageFlags: +.. _class_@GlobalScope_constant_KEY_R: -.. _class_@GlobalScope_constant_PROPERTY_USAGE_STORAGE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR: +:ref:`Key` **KEY_R** = ``82`` -.. _class_@GlobalScope_constant_PROPERTY_USAGE_NETWORK: +R key. -.. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR_HELPER: +.. _class_@GlobalScope_constant_KEY_S: -.. _class_@GlobalScope_constant_PROPERTY_USAGE_CHECKABLE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_USAGE_CHECKED: +:ref:`Key` **KEY_S** = ``83`` -.. _class_@GlobalScope_constant_PROPERTY_USAGE_INTERNATIONALIZED: +S key. -.. _class_@GlobalScope_constant_PROPERTY_USAGE_GROUP: +.. _class_@GlobalScope_constant_KEY_T: -.. _class_@GlobalScope_constant_PROPERTY_USAGE_CATEGORY: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_USAGE_NO_INSTANCE_STATE: +:ref:`Key` **KEY_T** = ``84`` -.. _class_@GlobalScope_constant_PROPERTY_USAGE_RESTART_IF_CHANGED: +T key. -.. _class_@GlobalScope_constant_PROPERTY_USAGE_SCRIPT_VARIABLE: +.. _class_@GlobalScope_constant_KEY_U: -.. _class_@GlobalScope_constant_PROPERTY_USAGE_DEFAULT: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_PROPERTY_USAGE_DEFAULT_INTL: +:ref:`Key` **KEY_U** = ``85`` -.. _class_@GlobalScope_constant_PROPERTY_USAGE_NOEDITOR: +U key. -enum **PropertyUsageFlags**: +.. _class_@GlobalScope_constant_KEY_V: -- **PROPERTY_USAGE_STORAGE** = **1** --- The property is serialized and saved in the scene file (default). +.. rst-class:: classref-enumeration-constant -- **PROPERTY_USAGE_EDITOR** = **2** --- The property is shown in the editor inspector (default). +:ref:`Key` **KEY_V** = ``86`` -- **PROPERTY_USAGE_NETWORK** = **4** --- Deprecated usage flag, unused. +V key. -- **PROPERTY_USAGE_EDITOR_HELPER** = **8** --- Deprecated usage flag, unused. +.. _class_@GlobalScope_constant_KEY_W: -- **PROPERTY_USAGE_CHECKABLE** = **16** --- The property can be checked in the editor inspector. +.. rst-class:: classref-enumeration-constant -- **PROPERTY_USAGE_CHECKED** = **32** --- The property is checked in the editor inspector. +:ref:`Key` **KEY_W** = ``87`` -- **PROPERTY_USAGE_INTERNATIONALIZED** = **64** --- The property is a translatable string. +W key. -- **PROPERTY_USAGE_GROUP** = **128** --- Used to group properties together in the editor. +.. _class_@GlobalScope_constant_KEY_X: -- **PROPERTY_USAGE_CATEGORY** = **256** --- Used to categorize properties together in the editor. +.. rst-class:: classref-enumeration-constant -- **PROPERTY_USAGE_NO_INSTANCE_STATE** = **2048** --- The property does not save its state in :ref:`PackedScene`. +:ref:`Key` **KEY_X** = ``88`` -- **PROPERTY_USAGE_RESTART_IF_CHANGED** = **4096** --- Editing the property prompts the user for restarting the editor. +X key. -- **PROPERTY_USAGE_SCRIPT_VARIABLE** = **8192** --- The property is a script variable which should be serialized and saved in the scene file. +.. _class_@GlobalScope_constant_KEY_Y: -- **PROPERTY_USAGE_DEFAULT** = **7** --- Default usage (storage, editor and network). +.. rst-class:: classref-enumeration-constant -- **PROPERTY_USAGE_DEFAULT_INTL** = **71** --- Default usage for translatable strings (storage, editor, network and internationalized). +:ref:`Key` **KEY_Y** = ``89`` -- **PROPERTY_USAGE_NOEDITOR** = **5** --- Default usage but without showing the property in the editor (storage, network). +Y key. ----- +.. _class_@GlobalScope_constant_KEY_Z: -.. _enum_@GlobalScope_MethodFlags: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_METHOD_FLAG_NORMAL: +:ref:`Key` **KEY_Z** = ``90`` -.. _class_@GlobalScope_constant_METHOD_FLAG_EDITOR: +Z key. -.. _class_@GlobalScope_constant_METHOD_FLAG_NOSCRIPT: +.. _class_@GlobalScope_constant_KEY_BRACKETLEFT: -.. _class_@GlobalScope_constant_METHOD_FLAG_CONST: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_METHOD_FLAG_REVERSE: +:ref:`Key` **KEY_BRACKETLEFT** = ``91`` -.. _class_@GlobalScope_constant_METHOD_FLAG_VIRTUAL: +Left bracket (``[lb]``) key. -.. _class_@GlobalScope_constant_METHOD_FLAG_FROM_SCRIPT: +.. _class_@GlobalScope_constant_KEY_BACKSLASH: -.. _class_@GlobalScope_constant_METHOD_FLAGS_DEFAULT: +.. rst-class:: classref-enumeration-constant -enum **MethodFlags**: +:ref:`Key` **KEY_BACKSLASH** = ``92`` -- **METHOD_FLAG_NORMAL** = **1** --- Flag for a normal method. +Backslash (``\``) key. -- **METHOD_FLAG_EDITOR** = **2** --- Flag for an editor method. +.. _class_@GlobalScope_constant_KEY_BRACKETRIGHT: -- **METHOD_FLAG_NOSCRIPT** = **4** --- Deprecated method flag, unused. +.. rst-class:: classref-enumeration-constant -- **METHOD_FLAG_CONST** = **8** --- Flag for a constant method. +:ref:`Key` **KEY_BRACKETRIGHT** = ``93`` -- **METHOD_FLAG_REVERSE** = **16** --- Deprecated method flag, unused. +Right bracket (``[rb]``) key. -- **METHOD_FLAG_VIRTUAL** = **32** --- Flag for a virtual method. +.. _class_@GlobalScope_constant_KEY_ASCIICIRCUM: -- **METHOD_FLAG_FROM_SCRIPT** = **64** --- Deprecated method flag, unused. +.. rst-class:: classref-enumeration-constant -- **METHOD_FLAGS_DEFAULT** = **1** --- Default method flags. +:ref:`Key` **KEY_ASCIICIRCUM** = ``94`` ----- +Caret (``^``) key. -.. _enum_@GlobalScope_Variant.Type: +.. _class_@GlobalScope_constant_KEY_UNDERSCORE: -.. _class_@GlobalScope_constant_TYPE_NIL: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_TYPE_BOOL: +:ref:`Key` **KEY_UNDERSCORE** = ``95`` -.. _class_@GlobalScope_constant_TYPE_INT: +Underscore (``_``) key. -.. _class_@GlobalScope_constant_TYPE_REAL: +.. _class_@GlobalScope_constant_KEY_QUOTELEFT: -.. _class_@GlobalScope_constant_TYPE_STRING: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_TYPE_VECTOR2: +:ref:`Key` **KEY_QUOTELEFT** = ``96`` -.. _class_@GlobalScope_constant_TYPE_VECTOR2I: +Backtick (`````) key. -.. _class_@GlobalScope_constant_TYPE_RECT2: +.. _class_@GlobalScope_constant_KEY_BRACELEFT: -.. _class_@GlobalScope_constant_TYPE_RECT2I: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_TYPE_VECTOR3: +:ref:`Key` **KEY_BRACELEFT** = ``123`` -.. _class_@GlobalScope_constant_TYPE_VECTOR3I: +Left brace (``{``) key. -.. _class_@GlobalScope_constant_TYPE_TRANSFORM2D: +.. _class_@GlobalScope_constant_KEY_BAR: -.. _class_@GlobalScope_constant_TYPE_PLANE: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_TYPE_QUAT: +:ref:`Key` **KEY_BAR** = ``124`` -.. _class_@GlobalScope_constant_TYPE_AABB: +Vertical bar or *pipe* (``|``) key. -.. _class_@GlobalScope_constant_TYPE_BASIS: +.. _class_@GlobalScope_constant_KEY_BRACERIGHT: -.. _class_@GlobalScope_constant_TYPE_TRANSFORM: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_TYPE_COLOR: +:ref:`Key` **KEY_BRACERIGHT** = ``125`` -.. _class_@GlobalScope_constant_TYPE_STRING_NAME: +Right brace (``}``) key. -.. _class_@GlobalScope_constant_TYPE_NODE_PATH: +.. _class_@GlobalScope_constant_KEY_ASCIITILDE: -.. _class_@GlobalScope_constant_TYPE_RID: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_TYPE_OBJECT: +:ref:`Key` **KEY_ASCIITILDE** = ``126`` -.. _class_@GlobalScope_constant_TYPE_CALLABLE: +Tilde (``~``) key. -.. _class_@GlobalScope_constant_TYPE_SIGNAL: +.. _class_@GlobalScope_constant_KEY_YEN: -.. _class_@GlobalScope_constant_TYPE_DICTIONARY: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_TYPE_ARRAY: +:ref:`Key` **KEY_YEN** = ``165`` -.. _class_@GlobalScope_constant_TYPE_RAW_ARRAY: +Yen symbol (``¥``) key. -.. _class_@GlobalScope_constant_TYPE_INT32_ARRAY: +.. _class_@GlobalScope_constant_KEY_SECTION: -.. _class_@GlobalScope_constant_TYPE_INT64_ARRAY: +.. rst-class:: classref-enumeration-constant -.. _class_@GlobalScope_constant_TYPE_FLOAT32_ARRAY: +:ref:`Key` **KEY_SECTION** = ``167`` -.. _class_@GlobalScope_constant_TYPE_FLOAT64_ARRAY: +Section sign (``§``) key. -.. _class_@GlobalScope_constant_TYPE_STRING_ARRAY: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_TYPE_VECTOR2_ARRAY: +---- -.. _class_@GlobalScope_constant_TYPE_VECTOR3_ARRAY: +.. _enum_@GlobalScope_KeyModifierMask: -.. _class_@GlobalScope_constant_TYPE_COLOR_ARRAY: +.. rst-class:: classref-enumeration -.. _class_@GlobalScope_constant_TYPE_MAX: +flags **KeyModifierMask**: :ref:`🔗` -enum **Variant.Type**: +.. _class_@GlobalScope_constant_KEY_CODE_MASK: -- **TYPE_NIL** = **0** --- Variable is ``null``. +.. rst-class:: classref-enumeration-constant -- **TYPE_BOOL** = **1** --- Variable is of type :ref:`bool`. +:ref:`KeyModifierMask` **KEY_CODE_MASK** = ``8388607`` -- **TYPE_INT** = **2** --- Variable is of type :ref:`int`. +Key Code mask. -- **TYPE_REAL** = **3** --- Variable is of type :ref:`float` (real). +.. _class_@GlobalScope_constant_KEY_MODIFIER_MASK: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyModifierMask` **KEY_MODIFIER_MASK** = ``2130706432`` + +Modifier key mask. + +.. _class_@GlobalScope_constant_KEY_MASK_CMD_OR_CTRL: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyModifierMask` **KEY_MASK_CMD_OR_CTRL** = ``16777216`` + +Automatically remapped to :ref:`KEY_META` on macOS and :ref:`KEY_CTRL` on other platforms, this mask is never set in the actual events, and should be used for key mapping only. + +.. _class_@GlobalScope_constant_KEY_MASK_SHIFT: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyModifierMask` **KEY_MASK_SHIFT** = ``33554432`` + +Shift key mask. + +.. _class_@GlobalScope_constant_KEY_MASK_ALT: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyModifierMask` **KEY_MASK_ALT** = ``67108864`` + +Alt or Option (on macOS) key mask. + +.. _class_@GlobalScope_constant_KEY_MASK_META: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyModifierMask` **KEY_MASK_META** = ``134217728`` + +Command (on macOS) or Meta/Windows key mask. + +.. _class_@GlobalScope_constant_KEY_MASK_CTRL: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyModifierMask` **KEY_MASK_CTRL** = ``268435456`` + +Control key mask. + +.. _class_@GlobalScope_constant_KEY_MASK_KPAD: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyModifierMask` **KEY_MASK_KPAD** = ``536870912`` + +Keypad key mask. + +.. _class_@GlobalScope_constant_KEY_MASK_GROUP_SWITCH: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyModifierMask` **KEY_MASK_GROUP_SWITCH** = ``1073741824`` + +Group Switch key mask. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_KeyLocation: + +.. rst-class:: classref-enumeration + +enum **KeyLocation**: :ref:`🔗` + +.. _class_@GlobalScope_constant_KEY_LOCATION_UNSPECIFIED: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyLocation` **KEY_LOCATION_UNSPECIFIED** = ``0`` + +Used for keys which only appear once, or when a comparison doesn't need to differentiate the ``LEFT`` and ``RIGHT`` versions. + +For example, when using :ref:`InputEvent.is_match()`, an event which has :ref:`KEY_LOCATION_UNSPECIFIED` will match any :ref:`KeyLocation` on the passed event. + +.. _class_@GlobalScope_constant_KEY_LOCATION_LEFT: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyLocation` **KEY_LOCATION_LEFT** = ``1`` + +A key which is to the left of its twin. + +.. _class_@GlobalScope_constant_KEY_LOCATION_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeyLocation` **KEY_LOCATION_RIGHT** = ``2`` + +A key which is to the right of its twin. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_MouseButton: + +.. rst-class:: classref-enumeration + +enum **MouseButton**: :ref:`🔗` + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_NONE** = ``0`` + +Enum value which doesn't correspond to any mouse button. This is used to initialize :ref:`MouseButton` properties with a generic state. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_LEFT: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_LEFT** = ``1`` + +Primary mouse button, usually assigned to the left button. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_RIGHT** = ``2`` + +Secondary mouse button, usually assigned to the right button. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_MIDDLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_MIDDLE** = ``3`` + +Middle mouse button. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_WHEEL_UP: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_WHEEL_UP** = ``4`` + +Mouse wheel scrolling up. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_WHEEL_DOWN: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_WHEEL_DOWN** = ``5`` + +Mouse wheel scrolling down. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_WHEEL_LEFT: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_WHEEL_LEFT** = ``6`` + +Mouse wheel left button (only present on some mice). + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_WHEEL_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_WHEEL_RIGHT** = ``7`` + +Mouse wheel right button (only present on some mice). + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_XBUTTON1: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_XBUTTON1** = ``8`` + +Extra mouse button 1. This is sometimes present, usually to the sides of the mouse. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_XBUTTON2: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButton` **MOUSE_BUTTON_XBUTTON2** = ``9`` + +Extra mouse button 2. This is sometimes present, usually to the sides of the mouse. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_MouseButtonMask: + +.. rst-class:: classref-enumeration + +flags **MouseButtonMask**: :ref:`🔗` + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_MASK_LEFT: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButtonMask` **MOUSE_BUTTON_MASK_LEFT** = ``1`` + +Primary mouse button mask, usually for the left button. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_MASK_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButtonMask` **MOUSE_BUTTON_MASK_RIGHT** = ``2`` + +Secondary mouse button mask, usually for the right button. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_MASK_MIDDLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButtonMask` **MOUSE_BUTTON_MASK_MIDDLE** = ``4`` + +Middle mouse button mask. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_MASK_MB_XBUTTON1: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButtonMask` **MOUSE_BUTTON_MASK_MB_XBUTTON1** = ``128`` + +Extra mouse button 1 mask. + +.. _class_@GlobalScope_constant_MOUSE_BUTTON_MASK_MB_XBUTTON2: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseButtonMask` **MOUSE_BUTTON_MASK_MB_XBUTTON2** = ``256`` + +Extra mouse button 2 mask. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_JoyButton: + +.. rst-class:: classref-enumeration + +enum **JoyButton**: :ref:`🔗` + +.. _class_@GlobalScope_constant_JOY_BUTTON_INVALID: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_INVALID** = ``-1`` + +An invalid game controller button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_A: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_A** = ``0`` + +Game controller SDL button A. Corresponds to the bottom action button: Sony Cross, Xbox A, Nintendo B. + +.. _class_@GlobalScope_constant_JOY_BUTTON_B: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_B** = ``1`` + +Game controller SDL button B. Corresponds to the right action button: Sony Circle, Xbox B, Nintendo A. + +.. _class_@GlobalScope_constant_JOY_BUTTON_X: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_X** = ``2`` + +Game controller SDL button X. Corresponds to the left action button: Sony Square, Xbox X, Nintendo Y. + +.. _class_@GlobalScope_constant_JOY_BUTTON_Y: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_Y** = ``3`` + +Game controller SDL button Y. Corresponds to the top action button: Sony Triangle, Xbox Y, Nintendo X. + +.. _class_@GlobalScope_constant_JOY_BUTTON_BACK: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_BACK** = ``4`` + +Game controller SDL back button. Corresponds to the Sony Select, Xbox Back, Nintendo - button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_GUIDE: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_GUIDE** = ``5`` + +Game controller SDL guide button. Corresponds to the Sony PS, Xbox Home button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_START: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_START** = ``6`` + +Game controller SDL start button. Corresponds to the Sony Options, Xbox Menu, Nintendo + button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_LEFT_STICK: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_LEFT_STICK** = ``7`` + +Game controller SDL left stick button. Corresponds to the Sony L3, Xbox L/LS button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_RIGHT_STICK: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_RIGHT_STICK** = ``8`` + +Game controller SDL right stick button. Corresponds to the Sony R3, Xbox R/RS button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_LEFT_SHOULDER: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_LEFT_SHOULDER** = ``9`` + +Game controller SDL left shoulder button. Corresponds to the Sony L1, Xbox LB button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_RIGHT_SHOULDER: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_RIGHT_SHOULDER** = ``10`` + +Game controller SDL right shoulder button. Corresponds to the Sony R1, Xbox RB button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_DPAD_UP: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_DPAD_UP** = ``11`` + +Game controller D-pad up button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_DPAD_DOWN: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_DPAD_DOWN** = ``12`` + +Game controller D-pad down button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_DPAD_LEFT: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_DPAD_LEFT** = ``13`` + +Game controller D-pad left button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_DPAD_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_DPAD_RIGHT** = ``14`` + +Game controller D-pad right button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_MISC1: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_MISC1** = ``15`` + +Game controller SDL miscellaneous button. Corresponds to Xbox share button, PS5 microphone button, Nintendo Switch capture button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_PADDLE1: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_PADDLE1** = ``16`` + +Game controller SDL paddle 1 button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_PADDLE2: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_PADDLE2** = ``17`` + +Game controller SDL paddle 2 button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_PADDLE3: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_PADDLE3** = ``18`` + +Game controller SDL paddle 3 button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_PADDLE4: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_PADDLE4** = ``19`` + +Game controller SDL paddle 4 button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_TOUCHPAD: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_TOUCHPAD** = ``20`` + +Game controller SDL touchpad button. + +.. _class_@GlobalScope_constant_JOY_BUTTON_SDL_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_SDL_MAX** = ``21`` + +The number of SDL game controller buttons. + +.. _class_@GlobalScope_constant_JOY_BUTTON_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyButton` **JOY_BUTTON_MAX** = ``128`` + +The maximum number of game controller buttons supported by the engine. The actual limit may be lower on specific platforms: + +- **Android:** Up to 36 buttons. + +- **Linux:** Up to 80 buttons. + +- **Windows** and **macOS:** Up to 128 buttons. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_JoyAxis: + +.. rst-class:: classref-enumeration + +enum **JoyAxis**: :ref:`🔗` + +.. _class_@GlobalScope_constant_JOY_AXIS_INVALID: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_INVALID** = ``-1`` + +An invalid game controller axis. + +.. _class_@GlobalScope_constant_JOY_AXIS_LEFT_X: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_LEFT_X** = ``0`` + +Game controller left joystick x-axis. + +.. _class_@GlobalScope_constant_JOY_AXIS_LEFT_Y: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_LEFT_Y** = ``1`` + +Game controller left joystick y-axis. + +.. _class_@GlobalScope_constant_JOY_AXIS_RIGHT_X: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_RIGHT_X** = ``2`` + +Game controller right joystick x-axis. + +.. _class_@GlobalScope_constant_JOY_AXIS_RIGHT_Y: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_RIGHT_Y** = ``3`` + +Game controller right joystick y-axis. + +.. _class_@GlobalScope_constant_JOY_AXIS_TRIGGER_LEFT: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_TRIGGER_LEFT** = ``4`` + +Game controller left trigger axis. + +.. _class_@GlobalScope_constant_JOY_AXIS_TRIGGER_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_TRIGGER_RIGHT** = ``5`` + +Game controller right trigger axis. + +.. _class_@GlobalScope_constant_JOY_AXIS_SDL_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_SDL_MAX** = ``6`` + +The number of SDL game controller axes. + +.. _class_@GlobalScope_constant_JOY_AXIS_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`JoyAxis` **JOY_AXIS_MAX** = ``10`` + +The maximum number of game controller axes: OpenVR supports up to 5 Joysticks making a total of 10 axes. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_MIDIMessage: + +.. rst-class:: classref-enumeration + +enum **MIDIMessage**: :ref:`🔗` + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_NONE** = ``0`` + +Does not correspond to any MIDI message. This is the default value of :ref:`InputEventMIDI.message`. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_OFF: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_NOTE_OFF** = ``8`` + +MIDI message sent when a note is released. + +\ **Note:** Not all MIDI devices send this message; some may send :ref:`MIDI_MESSAGE_NOTE_ON` with :ref:`InputEventMIDI.velocity` set to ``0``. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_ON: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_NOTE_ON** = ``9`` + +MIDI message sent when a note is pressed. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_AFTERTOUCH: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_AFTERTOUCH** = ``10`` + +MIDI message sent to indicate a change in pressure while a note is being pressed down, also called aftertouch. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_CONTROL_CHANGE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_CONTROL_CHANGE** = ``11`` + +MIDI message sent when a controller value changes. In a MIDI device, a controller is any input that doesn't play notes. These may include sliders for volume, balance, and panning, as well as switches and pedals. See the `General MIDI specification `__ for a small list. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_PROGRAM_CHANGE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_PROGRAM_CHANGE** = ``12`` + +MIDI message sent when the MIDI device changes its current instrument (also called *program* or *preset*). + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_CHANNEL_PRESSURE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_CHANNEL_PRESSURE** = ``13`` + +MIDI message sent to indicate a change in pressure for the whole channel. Some MIDI devices may send this instead of :ref:`MIDI_MESSAGE_AFTERTOUCH`. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_PITCH_BEND: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_PITCH_BEND** = ``14`` + +MIDI message sent when the value of the pitch bender changes, usually a wheel on the MIDI device. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_SYSTEM_EXCLUSIVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_SYSTEM_EXCLUSIVE** = ``240`` + +MIDI system exclusive (SysEx) message. This type of message is not standardized and it's highly dependent on the MIDI device sending it. + +\ **Note:** Getting this message's data from :ref:`InputEventMIDI` is not implemented. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_QUARTER_FRAME: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_QUARTER_FRAME** = ``241`` + +MIDI message sent every quarter frame to keep connected MIDI devices synchronized. Related to :ref:`MIDI_MESSAGE_TIMING_CLOCK`. + +\ **Note:** Getting this message's data from :ref:`InputEventMIDI` is not implemented. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_SONG_POSITION_POINTER: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_SONG_POSITION_POINTER** = ``242`` + +MIDI message sent to jump onto a new position in the current sequence or song. + +\ **Note:** Getting this message's data from :ref:`InputEventMIDI` is not implemented. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_SONG_SELECT: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_SONG_SELECT** = ``243`` + +MIDI message sent to select a sequence or song to play. + +\ **Note:** Getting this message's data from :ref:`InputEventMIDI` is not implemented. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_TUNE_REQUEST: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_TUNE_REQUEST** = ``246`` + +MIDI message sent to request a tuning calibration. Used on analog synthesizers. Most modern MIDI devices do not need this message. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_TIMING_CLOCK: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_TIMING_CLOCK** = ``248`` + +MIDI message sent 24 times after :ref:`MIDI_MESSAGE_QUARTER_FRAME`, to keep connected MIDI devices synchronized. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_START: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_START** = ``250`` + +MIDI message sent to start the current sequence or song from the beginning. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_CONTINUE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_CONTINUE** = ``251`` + +MIDI message sent to resume from the point the current sequence or song was paused. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_STOP: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_STOP** = ``252`` + +MIDI message sent to pause the current sequence or song. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_ACTIVE_SENSING: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_ACTIVE_SENSING** = ``254`` + +MIDI message sent repeatedly while the MIDI device is idle, to tell the receiver that the connection is alive. Most MIDI devices do not send this message. + +.. _class_@GlobalScope_constant_MIDI_MESSAGE_SYSTEM_RESET: + +.. rst-class:: classref-enumeration-constant + +:ref:`MIDIMessage` **MIDI_MESSAGE_SYSTEM_RESET** = ``255`` + +MIDI message sent to reset a MIDI device to its default state, as if it was just turned on. It should not be sent when the MIDI device is being turned on. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_Error: + +.. rst-class:: classref-enumeration + +enum **Error**: :ref:`🔗` + +.. _class_@GlobalScope_constant_OK: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **OK** = ``0`` + +Methods that return :ref:`Error` return :ref:`OK` when no error occurred. + +Since :ref:`OK` has value ``0``, and all other error constants are positive integers, it can also be used in boolean checks. + +:: + + var error = method_that_returns_error() + if error != OK: + printerr("Failure!") + + # Or, alternatively: + if error: + printerr("Still failing!") + +\ **Note:** Many functions do not return an error code, but will print error messages to standard output. + +.. _class_@GlobalScope_constant_FAILED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **FAILED** = ``1`` + +Generic error. + +.. _class_@GlobalScope_constant_ERR_UNAVAILABLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_UNAVAILABLE** = ``2`` + +Unavailable error. + +.. _class_@GlobalScope_constant_ERR_UNCONFIGURED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_UNCONFIGURED** = ``3`` + +Unconfigured error. + +.. _class_@GlobalScope_constant_ERR_UNAUTHORIZED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_UNAUTHORIZED** = ``4`` + +Unauthorized error. + +.. _class_@GlobalScope_constant_ERR_PARAMETER_RANGE_ERROR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_PARAMETER_RANGE_ERROR** = ``5`` + +Parameter range error. + +.. _class_@GlobalScope_constant_ERR_OUT_OF_MEMORY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_OUT_OF_MEMORY** = ``6`` + +Out of memory (OOM) error. + +.. _class_@GlobalScope_constant_ERR_FILE_NOT_FOUND: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_NOT_FOUND** = ``7`` + +File: Not found error. + +.. _class_@GlobalScope_constant_ERR_FILE_BAD_DRIVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_BAD_DRIVE** = ``8`` + +File: Bad drive error. + +.. _class_@GlobalScope_constant_ERR_FILE_BAD_PATH: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_BAD_PATH** = ``9`` + +File: Bad path error. + +.. _class_@GlobalScope_constant_ERR_FILE_NO_PERMISSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_NO_PERMISSION** = ``10`` + +File: No permission error. + +.. _class_@GlobalScope_constant_ERR_FILE_ALREADY_IN_USE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_ALREADY_IN_USE** = ``11`` + +File: Already in use error. + +.. _class_@GlobalScope_constant_ERR_FILE_CANT_OPEN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_CANT_OPEN** = ``12`` + +File: Can't open error. + +.. _class_@GlobalScope_constant_ERR_FILE_CANT_WRITE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_CANT_WRITE** = ``13`` + +File: Can't write error. + +.. _class_@GlobalScope_constant_ERR_FILE_CANT_READ: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_CANT_READ** = ``14`` + +File: Can't read error. + +.. _class_@GlobalScope_constant_ERR_FILE_UNRECOGNIZED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_UNRECOGNIZED** = ``15`` + +File: Unrecognized error. + +.. _class_@GlobalScope_constant_ERR_FILE_CORRUPT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_CORRUPT** = ``16`` + +File: Corrupt error. + +.. _class_@GlobalScope_constant_ERR_FILE_MISSING_DEPENDENCIES: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_MISSING_DEPENDENCIES** = ``17`` + +File: Missing dependencies error. + +.. _class_@GlobalScope_constant_ERR_FILE_EOF: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_FILE_EOF** = ``18`` + +File: End of file (EOF) error. + +.. _class_@GlobalScope_constant_ERR_CANT_OPEN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_CANT_OPEN** = ``19`` + +Can't open error. + +.. _class_@GlobalScope_constant_ERR_CANT_CREATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_CANT_CREATE** = ``20`` + +Can't create error. + +.. _class_@GlobalScope_constant_ERR_QUERY_FAILED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_QUERY_FAILED** = ``21`` + +Query failed error. + +.. _class_@GlobalScope_constant_ERR_ALREADY_IN_USE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_ALREADY_IN_USE** = ``22`` + +Already in use error. + +.. _class_@GlobalScope_constant_ERR_LOCKED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_LOCKED** = ``23`` + +Locked error. + +.. _class_@GlobalScope_constant_ERR_TIMEOUT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_TIMEOUT** = ``24`` + +Timeout error. + +.. _class_@GlobalScope_constant_ERR_CANT_CONNECT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_CANT_CONNECT** = ``25`` + +Can't connect error. + +.. _class_@GlobalScope_constant_ERR_CANT_RESOLVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_CANT_RESOLVE** = ``26`` + +Can't resolve error. + +.. _class_@GlobalScope_constant_ERR_CONNECTION_ERROR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_CONNECTION_ERROR** = ``27`` + +Connection error. + +.. _class_@GlobalScope_constant_ERR_CANT_ACQUIRE_RESOURCE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_CANT_ACQUIRE_RESOURCE** = ``28`` + +Can't acquire resource error. + +.. _class_@GlobalScope_constant_ERR_CANT_FORK: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_CANT_FORK** = ``29`` + +Can't fork process error. + +.. _class_@GlobalScope_constant_ERR_INVALID_DATA: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_INVALID_DATA** = ``30`` + +Invalid data error. + +.. _class_@GlobalScope_constant_ERR_INVALID_PARAMETER: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_INVALID_PARAMETER** = ``31`` + +Invalid parameter error. + +.. _class_@GlobalScope_constant_ERR_ALREADY_EXISTS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_ALREADY_EXISTS** = ``32`` + +Already exists error. + +.. _class_@GlobalScope_constant_ERR_DOES_NOT_EXIST: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_DOES_NOT_EXIST** = ``33`` + +Does not exist error. + +.. _class_@GlobalScope_constant_ERR_DATABASE_CANT_READ: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_DATABASE_CANT_READ** = ``34`` + +Database: Read error. + +.. _class_@GlobalScope_constant_ERR_DATABASE_CANT_WRITE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_DATABASE_CANT_WRITE** = ``35`` + +Database: Write error. + +.. _class_@GlobalScope_constant_ERR_COMPILATION_FAILED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_COMPILATION_FAILED** = ``36`` + +Compilation failed error. + +.. _class_@GlobalScope_constant_ERR_METHOD_NOT_FOUND: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_METHOD_NOT_FOUND** = ``37`` + +Method not found error. + +.. _class_@GlobalScope_constant_ERR_LINK_FAILED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_LINK_FAILED** = ``38`` + +Linking failed error. + +.. _class_@GlobalScope_constant_ERR_SCRIPT_FAILED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_SCRIPT_FAILED** = ``39`` + +Script failed error. + +.. _class_@GlobalScope_constant_ERR_CYCLIC_LINK: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_CYCLIC_LINK** = ``40`` + +Cycling link (import cycle) error. + +.. _class_@GlobalScope_constant_ERR_INVALID_DECLARATION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_INVALID_DECLARATION** = ``41`` + +Invalid declaration error. + +.. _class_@GlobalScope_constant_ERR_DUPLICATE_SYMBOL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_DUPLICATE_SYMBOL** = ``42`` + +Duplicate symbol error. + +.. _class_@GlobalScope_constant_ERR_PARSE_ERROR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_PARSE_ERROR** = ``43`` + +Parse error. + +.. _class_@GlobalScope_constant_ERR_BUSY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_BUSY** = ``44`` + +Busy error. + +.. _class_@GlobalScope_constant_ERR_SKIP: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_SKIP** = ``45`` + +Skip error. + +.. _class_@GlobalScope_constant_ERR_HELP: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_HELP** = ``46`` + +Help error. Used internally when passing ``--version`` or ``--help`` as executable options. + +.. _class_@GlobalScope_constant_ERR_BUG: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_BUG** = ``47`` + +Bug error, caused by an implementation issue in the method. + +\ **Note:** If a built-in method returns this code, please open an issue on `the GitHub Issue Tracker `__. + +.. _class_@GlobalScope_constant_ERR_PRINTER_ON_FIRE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Error` **ERR_PRINTER_ON_FIRE** = ``48`` + +Printer on fire error (This is an easter egg, no built-in methods return this error code). + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_PropertyHint: + +.. rst-class:: classref-enumeration + +enum **PropertyHint**: :ref:`🔗` + +.. _class_@GlobalScope_constant_PROPERTY_HINT_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_NONE** = ``0`` + +The property has no hint for the editor. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_RANGE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_RANGE** = ``1`` + +Hints that an :ref:`int` or :ref:`float` property should be within a range specified via the hint string ``"min,max"`` or ``"min,max,step"``. The hint string can optionally include ``"or_greater"`` and/or ``"or_less"`` to allow manual input going respectively above the max or below the min values. + +\ **Example:** ``"-360,360,1,or_greater,or_less"``. + +Additionally, other keywords can be included: ``"exp"`` for exponential range editing, ``"radians_as_degrees"`` for editing radian angles in degrees (the range values are also in degrees), ``"degrees"`` to hint at an angle, ``"prefer_slider"`` to show the slider for integers, and ``"hide_control"`` to hide the slider or up-down arrows. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_ENUM: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_ENUM** = ``2`` + +Hints that an :ref:`int`, :ref:`String`, or :ref:`StringName` property is an enumerated value to pick in a list specified via a hint string. + +The hint string is a comma separated list of names such as ``"Hello,Something,Else"``. Whitespace is **not** removed from either end of a name. For integer properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"Zero,One,Three:3,Four,Six:6"``. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_ENUM_SUGGESTION: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_ENUM_SUGGESTION** = ``3`` + +Hints that a :ref:`String` or :ref:`StringName` property can be an enumerated value to pick in a list specified via a hint string such as ``"Hello,Something,Else"``. See :ref:`PROPERTY_HINT_ENUM` for details. + +Unlike :ref:`PROPERTY_HINT_ENUM`, a property with this hint still accepts arbitrary values and can be empty. The list of values serves to suggest possible values. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_EXP_EASING: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_EXP_EASING** = ``4`` + +Hints that a :ref:`float` property should be edited via an exponential easing function. The hint string can include ``"attenuation"`` to flip the curve horizontally and/or ``"positive_only"`` to exclude in/out easing and limit values to be greater than or equal to zero. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LINK: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LINK** = ``5`` + +Hints that a vector property should allow its components to be linked. For example, this allows :ref:`Vector2.x` and :ref:`Vector2.y` to be edited together. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_FLAGS: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_FLAGS** = ``6`` + +Hints that an :ref:`int` property is a bitmask with named bit flags. + +The hint string is a comma separated list of names such as ``"Bit0,Bit1,Bit2,Bit3"``. Whitespace is **not** removed from either end of a name. The first name in the list has value 1, the next 2, then 4, 8, 16 and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"A:4,B:8,C:16"``. You can also combine several flags (``"A:4,B:8,AB:12,C:16"``). + +\ **Note:** A flag value must be at least ``1`` and at most ``2 ** 32 - 1``. + +\ **Note:** Unlike :ref:`PROPERTY_HINT_ENUM`, the previous explicit value is not taken into account. For the hint ``"A:16,B,C"``, A is 16, B is 2, C is 4. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_RENDER: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LAYERS_2D_RENDER** = ``7`` + +Hints that an :ref:`int` property is a bitmask using the optionally named 2D render layers. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_PHYSICS: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LAYERS_2D_PHYSICS** = ``8`` + +Hints that an :ref:`int` property is a bitmask using the optionally named 2D physics layers. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_NAVIGATION: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LAYERS_2D_NAVIGATION** = ``9`` + +Hints that an :ref:`int` property is a bitmask using the optionally named 2D navigation layers. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_RENDER: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LAYERS_3D_RENDER** = ``10`` + +Hints that an :ref:`int` property is a bitmask using the optionally named 3D render layers. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_PHYSICS: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LAYERS_3D_PHYSICS** = ``11`` + +Hints that an :ref:`int` property is a bitmask using the optionally named 3D physics layers. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_NAVIGATION: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LAYERS_3D_NAVIGATION** = ``12`` + +Hints that an :ref:`int` property is a bitmask using the optionally named 3D navigation layers. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_AVOIDANCE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LAYERS_AVOIDANCE** = ``37`` + +Hints that an integer property is a bitmask using the optionally named avoidance layers. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_FILE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_FILE** = ``13`` + +Hints that a :ref:`String` property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. By default the file will be stored as UID whenever available. You can use :ref:`ResourceUID` methods to convert it back to path. For storing a raw path, use :ref:`PROPERTY_HINT_FILE_PATH`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_DIR: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_DIR** = ``14`` + +Hints that a :ref:`String` property is a path to a directory. Editing it will show a file dialog for picking the path. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_GLOBAL_FILE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_GLOBAL_FILE** = ``15`` + +Hints that a :ref:`String` property is an absolute path to a file outside the project folder. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards, like ``"*.png,*.jpg"``. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_GLOBAL_DIR: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_GLOBAL_DIR** = ``16`` + +Hints that a :ref:`String` property is an absolute path to a directory outside the project folder. Editing it will show a file dialog for picking the path. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_RESOURCE_TYPE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_RESOURCE_TYPE** = ``17`` + +Hints that a property is an instance of a :ref:`Resource`-derived type, optionally specified via the hint string (e.g. ``"Texture2D"``). Editing it will show a popup menu of valid resource types to instantiate. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_MULTILINE_TEXT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_MULTILINE_TEXT** = ``18`` + +Hints that a :ref:`String` property is text with line breaks. Editing it will show a text input field where line breaks can be typed. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_EXPRESSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_EXPRESSION** = ``19`` + +Hints that a :ref:`String` property is an :ref:`Expression`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_PLACEHOLDER_TEXT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_PLACEHOLDER_TEXT** = ``20`` + +Hints that a :ref:`String` property should show a placeholder text on its input field, if empty. The hint string is the placeholder text to use. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_COLOR_NO_ALPHA: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_COLOR_NO_ALPHA** = ``21`` + +Hints that a :ref:`Color` property should be edited without affecting its transparency (:ref:`Color.a` is not editable). + +.. _class_@GlobalScope_constant_PROPERTY_HINT_OBJECT_ID: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_OBJECT_ID** = ``22`` + +Hints that the property's value is an object encoded as object ID, with its type specified in the hint string. Used by the debugger. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_TYPE_STRING: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_TYPE_STRING** = ``23`` + +If a property is :ref:`String`, hints that the property represents a particular type (class). This allows to select a type from the create dialog. The property will store the selected type as a string. + +If a property is :ref:`Array`, hints the editor how to show elements. The ``hint_string`` must encode nested types using ``":"`` and ``"/"``. + +If a property is :ref:`Dictionary`, hints the editor how to show elements. The ``hint_string`` is the same as :ref:`Array`, with a ``";"`` separating the key and value. + + +.. tabs:: + + .. code-tab:: gdscript + + # Array of elem_type. + hint_string = "%d:" % [elem_type] + hint_string = "%d/%d:%s" % [elem_type, elem_hint, elem_hint_string] + # Two-dimensional array of elem_type (array of arrays of elem_type). + hint_string = "%d:%d:" % [TYPE_ARRAY, elem_type] + hint_string = "%d:%d/%d:%s" % [TYPE_ARRAY, elem_type, elem_hint, elem_hint_string] + # Three-dimensional array of elem_type (array of arrays of arrays of elem_type). + hint_string = "%d:%d:%d:" % [TYPE_ARRAY, TYPE_ARRAY, elem_type] + hint_string = "%d:%d:%d/%d:%s" % [TYPE_ARRAY, TYPE_ARRAY, elem_type, elem_hint, elem_hint_string] + + .. code-tab:: csharp + + // Array of elemType. + hintString = $"{elemType:D}:"; + hintString = $"{elemType:}/{elemHint:D}:{elemHintString}"; + // Two-dimensional array of elemType (array of arrays of elemType). + hintString = $"{Variant.Type.Array:D}:{elemType:D}:"; + hintString = $"{Variant.Type.Array:D}:{elemType:D}/{elemHint:D}:{elemHintString}"; + // Three-dimensional array of elemType (array of arrays of arrays of elemType). + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Array:D}:{elemType:D}:"; + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Array:D}:{elemType:D}/{elemHint:D}:{elemHintString}"; + + + +\ **Examples:**\ + + +.. tabs:: + + .. code-tab:: gdscript + + hint_string = "%d:" % [TYPE_INT] # Array of integers. + hint_string = "%d/%d:1,10,1" % [TYPE_INT, PROPERTY_HINT_RANGE] # Array of integers (in range from 1 to 10). + hint_string = "%d/%d:Zero,One,Two" % [TYPE_INT, PROPERTY_HINT_ENUM] # Array of integers (an enum). + hint_string = "%d/%d:Zero,One,Three:3,Six:6" % [TYPE_INT, PROPERTY_HINT_ENUM] # Array of integers (an enum). + hint_string = "%d/%d:*.png" % [TYPE_STRING, PROPERTY_HINT_FILE] # Array of strings (file paths). + hint_string = "%d/%d:Texture2D" % [TYPE_OBJECT, PROPERTY_HINT_RESOURCE_TYPE] # Array of textures. + + hint_string = "%d:%d:" % [TYPE_ARRAY, TYPE_FLOAT] # Two-dimensional array of floats. + hint_string = "%d:%d/%d:" % [TYPE_ARRAY, TYPE_STRING, PROPERTY_HINT_MULTILINE_TEXT] # Two-dimensional array of multiline strings. + hint_string = "%d:%d/%d:-1,1,0.1" % [TYPE_ARRAY, TYPE_FLOAT, PROPERTY_HINT_RANGE] # Two-dimensional array of floats (in range from -1 to 1). + hint_string = "%d:%d/%d:Texture2D" % [TYPE_ARRAY, TYPE_OBJECT, PROPERTY_HINT_RESOURCE_TYPE] # Two-dimensional array of textures. + + .. code-tab:: csharp + + hintString = $"{Variant.Type.Int:D}/{PropertyHint.Range:D}:1,10,1"; // Array of integers (in range from 1 to 10). + hintString = $"{Variant.Type.Int:D}/{PropertyHint.Enum:D}:Zero,One,Two"; // Array of integers (an enum). + hintString = $"{Variant.Type.Int:D}/{PropertyHint.Enum:D}:Zero,One,Three:3,Six:6"; // Array of integers (an enum). + hintString = $"{Variant.Type.String:D}/{PropertyHint.File:D}:*.png"; // Array of strings (file paths). + hintString = $"{Variant.Type.Object:D}/{PropertyHint.ResourceType:D}:Texture2D"; // Array of textures. + + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Float:D}:"; // Two-dimensional array of floats. + hintString = $"{Variant.Type.Array:D}:{Variant.Type.String:D}/{PropertyHint.MultilineText:D}:"; // Two-dimensional array of multiline strings. + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Float:D}/{PropertyHint.Range:D}:-1,1,0.1"; // Two-dimensional array of floats (in range from -1 to 1). + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Object:D}/{PropertyHint.ResourceType:D}:Texture2D"; // Two-dimensional array of textures. + + + +\ **Note:** The trailing colon is required for properly detecting built-in types. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE** = ``24`` + +**Deprecated:** This hint is not used by the engine. + + + +.. _class_@GlobalScope_constant_PROPERTY_HINT_OBJECT_TOO_BIG: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_OBJECT_TOO_BIG** = ``25`` + +Hints that an object is too big to be sent via the debugger. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_VALID_TYPES: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_NODE_PATH_VALID_TYPES** = ``26`` + +Hints that the hint string specifies valid node types for property of type :ref:`NodePath`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_SAVE_FILE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_SAVE_FILE** = ``27`` + +Hints that a :ref:`String` property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the project's directory. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. See also :ref:`FileDialog.filters`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_GLOBAL_SAVE_FILE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_GLOBAL_SAVE_FILE** = ``28`` + +Hints that a :ref:`String` property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the entire filesystem. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. See also :ref:`FileDialog.filters`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_INT_IS_OBJECTID: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_INT_IS_OBJECTID** = ``29`` + +**Deprecated:** This hint is not used by the engine. + + + +.. _class_@GlobalScope_constant_PROPERTY_HINT_INT_IS_POINTER: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_INT_IS_POINTER** = ``30`` + +Hints that an :ref:`int` property is a pointer. Used by GDExtension. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_ARRAY_TYPE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_ARRAY_TYPE** = ``31`` + +Hints that a property is an :ref:`Array` with the stored type specified in the hint string. The hint string contains the type of the array (e.g. ``"String"``). + +Use the hint string format from :ref:`PROPERTY_HINT_TYPE_STRING` for more control over the stored type. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_DICTIONARY_TYPE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_DICTIONARY_TYPE** = ``38`` + +Hints that a property is a :ref:`Dictionary` with the stored types specified in the hint string. The hint string contains the key and value types separated by a semicolon (e.g. ``"int;String"``). + +Use the hint string format from :ref:`PROPERTY_HINT_TYPE_STRING` for more control over the stored types. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LOCALE_ID: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LOCALE_ID** = ``32`` + +Hints that a string property is a locale code. Editing it will show a locale dialog for picking language and country. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_LOCALIZABLE_STRING: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_LOCALIZABLE_STRING** = ``33`` + +Hints that a dictionary property is string translation map. Dictionary keys are locale codes and, values are translated strings. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_NODE_TYPE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_NODE_TYPE** = ``34`` + +Hints that a property is an instance of a :ref:`Node`-derived type, optionally specified via the hint string (e.g. ``"Node2D"``). Editing it will show a dialog for picking a node from the scene. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_HIDE_QUATERNION_EDIT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_HIDE_QUATERNION_EDIT** = ``35`` + +Hints that a quaternion property should disable the temporary euler editor. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_PASSWORD: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_PASSWORD** = ``36`` + +Hints that a string property is a password, and every character is replaced with the secret character. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_TOOL_BUTTON: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_TOOL_BUTTON** = ``39`` + +Hints that a :ref:`Callable` property should be displayed as a clickable button. When the button is pressed, the callable is called. The hint string specifies the button text and optionally an icon from the ``"EditorIcons"`` theme type. + +.. code:: text + + "Click me!" - A button with the text "Click me!" and the default "Callable" icon. + "Click me!,ColorRect" - A button with the text "Click me!" and the "ColorRect" icon. + +\ **Note:** A :ref:`Callable` cannot be properly serialized and stored in a file, so it is recommended to use :ref:`PROPERTY_USAGE_EDITOR` instead of :ref:`PROPERTY_USAGE_DEFAULT`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_ONESHOT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_ONESHOT** = ``40`` + +Hints that a property will be changed on its own after setting, such as :ref:`AudioStreamPlayer.playing` or :ref:`GPUParticles3D.emitting`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_GROUP_ENABLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_GROUP_ENABLE** = ``42`` + +Hints that a boolean property will enable the feature associated with the group that it occurs in. The property will be displayed as a checkbox on the group header. Only works within a group or subgroup. + +By default, disabling the property hides all properties in the group. Use the optional hint string ``"checkbox_only"`` to disable this behavior. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_INPUT_NAME: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_INPUT_NAME** = ``43`` + +Hints that a :ref:`String` or :ref:`StringName` property is the name of an input action. This allows the selection of any action name from the Input Map in the Project Settings. The hint string may contain two options separated by commas: + +- If it contains ``"show_builtin"``, built-in input actions are included in the selection. + +- If it contains ``"loose_mode"``, loose mode is enabled. This allows inserting any action name even if it's not present in the input map. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_FILE_PATH: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_FILE_PATH** = ``44`` + +Like :ref:`PROPERTY_HINT_FILE`, but the property is stored as a raw path, not UID. That means the reference will be broken if you move the file. Consider using :ref:`PROPERTY_HINT_FILE` when possible. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_MAX** = ``45`` + +Represents the size of the :ref:`PropertyHint` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_PropertyUsageFlags: + +.. rst-class:: classref-enumeration + +flags **PropertyUsageFlags**: :ref:`🔗` + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_NONE** = ``0`` + +The property is not stored, and does not display in the editor. This is the default for non-exported properties. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_STORAGE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_STORAGE** = ``2`` + +The property is serialized and saved in the scene file (default for exported properties). + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_EDITOR** = ``4`` + +The property is shown in the :ref:`EditorInspector` (default for exported properties). + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_INTERNAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_INTERNAL** = ``8`` + +The property is excluded from the class reference. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_CHECKABLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_CHECKABLE** = ``16`` + +The property can be checked in the :ref:`EditorInspector`. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_CHECKED: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_CHECKED** = ``32`` + +The property is checked in the :ref:`EditorInspector`. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_GROUP: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_GROUP** = ``64`` + +Used to group properties together in the editor. See :ref:`EditorInspector`. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_CATEGORY: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_CATEGORY** = ``128`` + +Used to categorize properties together in the editor. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_SUBGROUP: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_SUBGROUP** = ``256`` + +Used to group properties together in the editor in a subgroup (under a group). See :ref:`EditorInspector`. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_CLASS_IS_BITFIELD: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_CLASS_IS_BITFIELD** = ``512`` + +The property is a bitfield, i.e. it contains multiple flags represented as bits. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_NO_INSTANCE_STATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_NO_INSTANCE_STATE** = ``1024`` + +The property does not save its state in :ref:`PackedScene`. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_RESTART_IF_CHANGED: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_RESTART_IF_CHANGED** = ``2048`` + +Editing the property prompts the user for restarting the editor. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_SCRIPT_VARIABLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_SCRIPT_VARIABLE** = ``4096`` + +The property is a script variable. :ref:`PROPERTY_USAGE_SCRIPT_VARIABLE` can be used to distinguish between exported script variables from built-in variables (which don't have this usage flag). By default, :ref:`PROPERTY_USAGE_SCRIPT_VARIABLE` is **not** applied to variables that are created by overriding :ref:`Object._get_property_list()` in a script. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_STORE_IF_NULL: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_STORE_IF_NULL** = ``8192`` + +The property value of type :ref:`Object` will be stored even if its value is ``null``. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED** = ``16384`` + +If this property is modified, all inspector fields will be refreshed. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE** = ``32768`` + +**Deprecated:** This flag is not used by the engine. + + + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_CLASS_IS_ENUM: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_CLASS_IS_ENUM** = ``65536`` + +The property is a variable of enum type, i.e. it only takes named integer constants from its associated enumeration. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_NIL_IS_VARIANT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_NIL_IS_VARIANT** = ``131072`` + +If property has ``nil`` as default value, its type will be :ref:`Variant`. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_ARRAY** = ``262144`` + +The property is the element count of a property array, i.e. a list of groups of related properties. Properties defined with this usage also need a specific ``class_name`` field in the form of ``label,prefix``. The field may also include additional comma-separated options: + +- ``page_size=N``: Overrides :ref:`EditorSettings.interface/inspector/max_array_dictionary_items_per_page` for this array. + +- ``add_button_text=text``: The text displayed by the "Add Element" button. + +- ``static``: The elements can't be re-arranged. + +- ``const``: New elements can't be added. + +- ``numbered``: An index will appear next to each element. + +- ``unfoldable``: The array can't be folded. + +- ``swap_method=method_name``: The method that will be called when two elements switch places. The method should take 2 :ref:`int` parameters, which will be indices of the elements being swapped. + +Note that making a full-fledged property array requires boilerplate code involving :ref:`Object._get_property_list()`. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_ALWAYS_DUPLICATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_ALWAYS_DUPLICATE** = ``524288`` + +When duplicating a resource with :ref:`Resource.duplicate()`, and this flag is set on a property of that resource, the property should always be duplicated, regardless of the ``subresources`` bool parameter. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_NEVER_DUPLICATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_NEVER_DUPLICATE** = ``1048576`` + +When duplicating a resource with :ref:`Resource.duplicate()`, and this flag is set on a property of that resource, the property should never be duplicated, regardless of the ``subresources`` bool parameter. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_HIGH_END_GFX: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_HIGH_END_GFX** = ``2097152`` + +The property is only shown in the editor if modern renderers are supported (the Compatibility rendering method is excluded). + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT** = ``4194304`` + +The :ref:`NodePath` property will always be relative to the scene's root. Mostly useful for local resources. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT** = ``8388608`` + +Use when a resource is created on the fly, i.e. the getter will always return a different instance. :ref:`ResourceSaver` needs this information to properly save such resources. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_KEYING_INCREMENTS: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_KEYING_INCREMENTS** = ``16777216`` + +Inserting an animation key frame of this property will automatically increment the value, allowing to easily keyframe multiple values in a row. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_DEFERRED_SET_RESOURCE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_DEFERRED_SET_RESOURCE** = ``33554432`` + +**Deprecated:** This flag is not used by the engine. + + + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT** = ``67108864`` + +When this property is a :ref:`Resource` and base object is a :ref:`Node`, a resource instance will be automatically created whenever the node is created in the editor. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR_BASIC_SETTING: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_EDITOR_BASIC_SETTING** = ``134217728`` + +The property is considered a basic setting and will appear even when advanced mode is disabled. Used for project settings. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_READ_ONLY: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_READ_ONLY** = ``268435456`` + +The property is read-only in the :ref:`EditorInspector`. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_SECRET: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_SECRET** = ``536870912`` + +An export preset property with this flag contains confidential information and is stored separately from the rest of the export preset configuration. + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_DEFAULT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_DEFAULT** = ``6`` + +Default usage (storage and editor). + +.. _class_@GlobalScope_constant_PROPERTY_USAGE_NO_EDITOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyUsageFlags` **PROPERTY_USAGE_NO_EDITOR** = ``2`` + +Default usage but without showing the property in the editor (storage). + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_MethodFlags: + +.. rst-class:: classref-enumeration + +flags **MethodFlags**: :ref:`🔗` + +.. _class_@GlobalScope_constant_METHOD_FLAG_NORMAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_NORMAL** = ``1`` + +Flag for a normal method. + +.. _class_@GlobalScope_constant_METHOD_FLAG_EDITOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_EDITOR** = ``2`` + +Flag for an editor method. + +.. _class_@GlobalScope_constant_METHOD_FLAG_CONST: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_CONST** = ``4`` + +Flag for a constant method. + +.. _class_@GlobalScope_constant_METHOD_FLAG_VIRTUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_VIRTUAL** = ``8`` + +Flag for a virtual method. + +.. _class_@GlobalScope_constant_METHOD_FLAG_VARARG: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_VARARG** = ``16`` + +Flag for a method with a variable number of arguments. + +.. _class_@GlobalScope_constant_METHOD_FLAG_STATIC: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_STATIC** = ``32`` + +Flag for a static method. + +.. _class_@GlobalScope_constant_METHOD_FLAG_OBJECT_CORE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_OBJECT_CORE** = ``64`` + +Used internally. Allows to not dump core virtual methods (such as :ref:`Object._notification()`) to the JSON API. + +.. _class_@GlobalScope_constant_METHOD_FLAG_VIRTUAL_REQUIRED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_VIRTUAL_REQUIRED** = ``128`` + +Flag for a virtual method that is required. In GDScript, this flag is set for abstract functions. + +.. _class_@GlobalScope_constant_METHOD_FLAGS_DEFAULT: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAGS_DEFAULT** = ``1`` + +Default method flags (normal). + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_Variant.Type: + +.. rst-class:: classref-enumeration + +enum **Variant.Type**: :ref:`🔗` + +.. _class_@GlobalScope_constant_TYPE_NIL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_NIL** = ``0`` + +Variable is ``null``. + +.. _class_@GlobalScope_constant_TYPE_BOOL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_BOOL** = ``1`` + +Variable is of type :ref:`bool`. + +.. _class_@GlobalScope_constant_TYPE_INT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_INT** = ``2`` + +Variable is of type :ref:`int`. + +.. _class_@GlobalScope_constant_TYPE_FLOAT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_FLOAT** = ``3`` + +Variable is of type :ref:`float`. + +.. _class_@GlobalScope_constant_TYPE_STRING: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_STRING** = ``4`` + +Variable is of type :ref:`String`. + +.. _class_@GlobalScope_constant_TYPE_VECTOR2: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_VECTOR2** = ``5`` + +Variable is of type :ref:`Vector2`. + +.. _class_@GlobalScope_constant_TYPE_VECTOR2I: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_VECTOR2I** = ``6`` + +Variable is of type :ref:`Vector2i`. + +.. _class_@GlobalScope_constant_TYPE_RECT2: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_RECT2** = ``7`` + +Variable is of type :ref:`Rect2`. + +.. _class_@GlobalScope_constant_TYPE_RECT2I: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_RECT2I** = ``8`` + +Variable is of type :ref:`Rect2i`. + +.. _class_@GlobalScope_constant_TYPE_VECTOR3: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_VECTOR3** = ``9`` + +Variable is of type :ref:`Vector3`. + +.. _class_@GlobalScope_constant_TYPE_VECTOR3I: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_VECTOR3I** = ``10`` + +Variable is of type :ref:`Vector3i`. + +.. _class_@GlobalScope_constant_TYPE_TRANSFORM2D: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_TRANSFORM2D** = ``11`` + +Variable is of type :ref:`Transform2D`. + +.. _class_@GlobalScope_constant_TYPE_VECTOR4: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_VECTOR4** = ``12`` + +Variable is of type :ref:`Vector4`. + +.. _class_@GlobalScope_constant_TYPE_VECTOR4I: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_VECTOR4I** = ``13`` + +Variable is of type :ref:`Vector4i`. + +.. _class_@GlobalScope_constant_TYPE_PLANE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PLANE** = ``14`` + +Variable is of type :ref:`Plane`. + +.. _class_@GlobalScope_constant_TYPE_QUATERNION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_QUATERNION** = ``15`` + +Variable is of type :ref:`Quaternion`. + +.. _class_@GlobalScope_constant_TYPE_AABB: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_AABB** = ``16`` + +Variable is of type :ref:`AABB`. + +.. _class_@GlobalScope_constant_TYPE_BASIS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_BASIS** = ``17`` + +Variable is of type :ref:`Basis`. + +.. _class_@GlobalScope_constant_TYPE_TRANSFORM3D: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_TRANSFORM3D** = ``18`` + +Variable is of type :ref:`Transform3D`. + +.. _class_@GlobalScope_constant_TYPE_PROJECTION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PROJECTION** = ``19`` + +Variable is of type :ref:`Projection`. + +.. _class_@GlobalScope_constant_TYPE_COLOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_COLOR** = ``20`` + +Variable is of type :ref:`Color`. + +.. _class_@GlobalScope_constant_TYPE_STRING_NAME: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_STRING_NAME** = ``21`` + +Variable is of type :ref:`StringName`. + +.. _class_@GlobalScope_constant_TYPE_NODE_PATH: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_NODE_PATH** = ``22`` + +Variable is of type :ref:`NodePath`. + +.. _class_@GlobalScope_constant_TYPE_RID: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_RID** = ``23`` + +Variable is of type :ref:`RID`. + +.. _class_@GlobalScope_constant_TYPE_OBJECT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_OBJECT** = ``24`` + +Variable is of type :ref:`Object`. + +.. _class_@GlobalScope_constant_TYPE_CALLABLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_CALLABLE** = ``25`` + +Variable is of type :ref:`Callable`. + +.. _class_@GlobalScope_constant_TYPE_SIGNAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_SIGNAL** = ``26`` + +Variable is of type :ref:`Signal`. + +.. _class_@GlobalScope_constant_TYPE_DICTIONARY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_DICTIONARY** = ``27`` + +Variable is of type :ref:`Dictionary`. + +.. _class_@GlobalScope_constant_TYPE_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_ARRAY** = ``28`` + +Variable is of type :ref:`Array`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_BYTE_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_BYTE_ARRAY** = ``29`` + +Variable is of type :ref:`PackedByteArray`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_INT32_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_INT32_ARRAY** = ``30`` + +Variable is of type :ref:`PackedInt32Array`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_INT64_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_INT64_ARRAY** = ``31`` + +Variable is of type :ref:`PackedInt64Array`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_FLOAT32_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_FLOAT32_ARRAY** = ``32`` + +Variable is of type :ref:`PackedFloat32Array`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_FLOAT64_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_FLOAT64_ARRAY** = ``33`` + +Variable is of type :ref:`PackedFloat64Array`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_STRING_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_STRING_ARRAY** = ``34`` + +Variable is of type :ref:`PackedStringArray`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_VECTOR2_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_VECTOR2_ARRAY** = ``35`` + +Variable is of type :ref:`PackedVector2Array`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_VECTOR3_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_VECTOR3_ARRAY** = ``36`` + +Variable is of type :ref:`PackedVector3Array`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_COLOR_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_COLOR_ARRAY** = ``37`` + +Variable is of type :ref:`PackedColorArray`. + +.. _class_@GlobalScope_constant_TYPE_PACKED_VECTOR4_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_VECTOR4_ARRAY** = ``38`` + +Variable is of type :ref:`PackedVector4Array`. + +.. _class_@GlobalScope_constant_TYPE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_MAX** = ``39`` + +Represents the size of the :ref:`Variant.Type` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_@GlobalScope_Variant.Operator: + +.. rst-class:: classref-enumeration + +enum **Variant.Operator**: :ref:`🔗` + +.. _class_@GlobalScope_constant_OP_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_EQUAL** = ``0`` + +Equality operator (``==``). + +.. _class_@GlobalScope_constant_OP_NOT_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_NOT_EQUAL** = ``1`` + +Inequality operator (``!=``). + +.. _class_@GlobalScope_constant_OP_LESS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_LESS** = ``2`` + +Less than operator (``<``). + +.. _class_@GlobalScope_constant_OP_LESS_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_LESS_EQUAL** = ``3`` + +Less than or equal operator (``<=``). + +.. _class_@GlobalScope_constant_OP_GREATER: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_GREATER** = ``4`` + +Greater than operator (``>``). + +.. _class_@GlobalScope_constant_OP_GREATER_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_GREATER_EQUAL** = ``5`` + +Greater than or equal operator (``>=``). + +.. _class_@GlobalScope_constant_OP_ADD: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_ADD** = ``6`` + +Addition operator (``+``). + +.. _class_@GlobalScope_constant_OP_SUBTRACT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_SUBTRACT** = ``7`` + +Subtraction operator (``-``). + +.. _class_@GlobalScope_constant_OP_MULTIPLY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_MULTIPLY** = ``8`` + +Multiplication operator (``*``). + +.. _class_@GlobalScope_constant_OP_DIVIDE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_DIVIDE** = ``9`` + +Division operator (``/``). + +.. _class_@GlobalScope_constant_OP_NEGATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_NEGATE** = ``10`` + +Unary negation operator (``-``). + +.. _class_@GlobalScope_constant_OP_POSITIVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_POSITIVE** = ``11`` + +Unary plus operator (``+``). + +.. _class_@GlobalScope_constant_OP_MODULE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_MODULE** = ``12`` + +Remainder/modulo operator (``%``). + +.. _class_@GlobalScope_constant_OP_POWER: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_POWER** = ``13`` + +Power operator (``**``). + +.. _class_@GlobalScope_constant_OP_SHIFT_LEFT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_SHIFT_LEFT** = ``14`` + +Left shift operator (``<<``). + +.. _class_@GlobalScope_constant_OP_SHIFT_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_SHIFT_RIGHT** = ``15`` + +Right shift operator (``>>``). + +.. _class_@GlobalScope_constant_OP_BIT_AND: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_BIT_AND** = ``16`` + +Bitwise AND operator (``&``). + +.. _class_@GlobalScope_constant_OP_BIT_OR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_BIT_OR** = ``17`` + +Bitwise OR operator (``|``). + +.. _class_@GlobalScope_constant_OP_BIT_XOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_BIT_XOR** = ``18`` + +Bitwise XOR operator (``^``). + +.. _class_@GlobalScope_constant_OP_BIT_NEGATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_BIT_NEGATE** = ``19`` + +Bitwise NOT operator (``~``). + +.. _class_@GlobalScope_constant_OP_AND: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_AND** = ``20`` + +Logical AND operator (``and`` or ``&&``). + +.. _class_@GlobalScope_constant_OP_OR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_OR** = ``21`` + +Logical OR operator (``or`` or ``||``). + +.. _class_@GlobalScope_constant_OP_XOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_XOR** = ``22`` + +Logical XOR operator (not implemented in GDScript). + +.. _class_@GlobalScope_constant_OP_NOT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_NOT** = ``23`` + +Logical NOT operator (``not`` or ``!``). + +.. _class_@GlobalScope_constant_OP_IN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_IN** = ``24`` + +Logical IN operator (``in``). + +.. _class_@GlobalScope_constant_OP_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Operator` **OP_MAX** = ``25`` + +Represents the size of the :ref:`Variant.Operator` enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_@GlobalScope_property_AudioServer: + +.. rst-class:: classref-property + +:ref:`AudioServer` **AudioServer** :ref:`🔗` + +The :ref:`AudioServer` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_CameraServer: + +.. rst-class:: classref-property + +:ref:`CameraServer` **CameraServer** :ref:`🔗` + +The :ref:`CameraServer` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_ClassDB: + +.. rst-class:: classref-property + +:ref:`ClassDB` **ClassDB** :ref:`🔗` + +The :ref:`ClassDB` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_DisplayServer: + +.. rst-class:: classref-property + +:ref:`DisplayServer` **DisplayServer** :ref:`🔗` + +The :ref:`DisplayServer` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_EditorInterface: + +.. rst-class:: classref-property + +:ref:`EditorInterface` **EditorInterface** :ref:`🔗` + +The :ref:`EditorInterface` singleton. + +\ **Note:** Only available in editor builds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_Engine: + +.. rst-class:: classref-property + +:ref:`Engine` **Engine** :ref:`🔗` + +The :ref:`Engine` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_EngineDebugger: + +.. rst-class:: classref-property + +:ref:`EngineDebugger` **EngineDebugger** :ref:`🔗` + +The :ref:`EngineDebugger` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_GDExtensionManager: + +.. rst-class:: classref-property + +:ref:`GDExtensionManager` **GDExtensionManager** :ref:`🔗` + +The :ref:`GDExtensionManager` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_Geometry2D: + +.. rst-class:: classref-property + +:ref:`Geometry2D` **Geometry2D** :ref:`🔗` + +The :ref:`Geometry2D` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_Geometry3D: + +.. rst-class:: classref-property + +:ref:`Geometry3D` **Geometry3D** :ref:`🔗` + +The :ref:`Geometry3D` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_IP: + +.. rst-class:: classref-property + +:ref:`IP` **IP** :ref:`🔗` + +The :ref:`IP` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_Input: + +.. rst-class:: classref-property + +:ref:`Input` **Input** :ref:`🔗` + +The :ref:`Input` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_InputMap: + +.. rst-class:: classref-property + +:ref:`InputMap` **InputMap** :ref:`🔗` + +The :ref:`InputMap` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_JavaClassWrapper: + +.. rst-class:: classref-property + +:ref:`JavaClassWrapper` **JavaClassWrapper** :ref:`🔗` + +The :ref:`JavaClassWrapper` singleton. + +\ **Note:** Only implemented on Android. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_JavaScriptBridge: + +.. rst-class:: classref-property + +:ref:`JavaScriptBridge` **JavaScriptBridge** :ref:`🔗` + +The :ref:`JavaScriptBridge` singleton. + +\ **Note:** Only implemented on the Web platform. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_Marshalls: + +.. rst-class:: classref-property + +:ref:`Marshalls` **Marshalls** :ref:`🔗` + +The :ref:`Marshalls` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_NativeMenu: + +.. rst-class:: classref-property + +:ref:`NativeMenu` **NativeMenu** :ref:`🔗` + +The :ref:`NativeMenu` singleton. + +\ **Note:** Only implemented on macOS. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_NavigationMeshGenerator: + +.. rst-class:: classref-property + +:ref:`NavigationMeshGenerator` **NavigationMeshGenerator** :ref:`🔗` + +The :ref:`NavigationMeshGenerator` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_NavigationServer2D: + +.. rst-class:: classref-property + +:ref:`NavigationServer2D` **NavigationServer2D** :ref:`🔗` + +The :ref:`NavigationServer2D` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_NavigationServer2DManager: + +.. rst-class:: classref-property + +:ref:`NavigationServer2DManager` **NavigationServer2DManager** :ref:`🔗` + +The :ref:`NavigationServer2DManager` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_NavigationServer3D: + +.. rst-class:: classref-property + +:ref:`NavigationServer3D` **NavigationServer3D** :ref:`🔗` + +The :ref:`NavigationServer3D` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_NavigationServer3DManager: + +.. rst-class:: classref-property + +:ref:`NavigationServer3DManager` **NavigationServer3DManager** :ref:`🔗` + +The :ref:`NavigationServer3DManager` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_OS: + +.. rst-class:: classref-property + +:ref:`OS` **OS** :ref:`🔗` + +The :ref:`OS` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_Performance: + +.. rst-class:: classref-property + +:ref:`Performance` **Performance** :ref:`🔗` + +The :ref:`Performance` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_PhysicsServer2D: + +.. rst-class:: classref-property + +:ref:`PhysicsServer2D` **PhysicsServer2D** :ref:`🔗` + +The :ref:`PhysicsServer2D` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_PhysicsServer2DManager: + +.. rst-class:: classref-property + +:ref:`PhysicsServer2DManager` **PhysicsServer2DManager** :ref:`🔗` + +The :ref:`PhysicsServer2DManager` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_PhysicsServer3D: + +.. rst-class:: classref-property + +:ref:`PhysicsServer3D` **PhysicsServer3D** :ref:`🔗` + +The :ref:`PhysicsServer3D` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_PhysicsServer3DManager: + +.. rst-class:: classref-property + +:ref:`PhysicsServer3DManager` **PhysicsServer3DManager** :ref:`🔗` + +The :ref:`PhysicsServer3DManager` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_ProjectSettings: + +.. rst-class:: classref-property + +:ref:`ProjectSettings` **ProjectSettings** :ref:`🔗` + +The :ref:`ProjectSettings` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_RenderingServer: + +.. rst-class:: classref-property + +:ref:`RenderingServer` **RenderingServer** :ref:`🔗` + +The :ref:`RenderingServer` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_ResourceLoader: + +.. rst-class:: classref-property + +:ref:`ResourceLoader` **ResourceLoader** :ref:`🔗` + +The :ref:`ResourceLoader` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_ResourceSaver: + +.. rst-class:: classref-property + +:ref:`ResourceSaver` **ResourceSaver** :ref:`🔗` + +The :ref:`ResourceSaver` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_ResourceUID: + +.. rst-class:: classref-property + +:ref:`ResourceUID` **ResourceUID** :ref:`🔗` + +The :ref:`ResourceUID` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_TextServerManager: + +.. rst-class:: classref-property + +:ref:`TextServerManager` **TextServerManager** :ref:`🔗` + +The :ref:`TextServerManager` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_ThemeDB: + +.. rst-class:: classref-property + +:ref:`ThemeDB` **ThemeDB** :ref:`🔗` + +The :ref:`ThemeDB` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_Time: + +.. rst-class:: classref-property + +:ref:`Time` **Time** :ref:`🔗` + +The :ref:`Time` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_TranslationServer: + +.. rst-class:: classref-property + +:ref:`TranslationServer` **TranslationServer** :ref:`🔗` + +The :ref:`TranslationServer` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_WorkerThreadPool: + +.. rst-class:: classref-property + +:ref:`WorkerThreadPool` **WorkerThreadPool** :ref:`🔗` + +The :ref:`WorkerThreadPool` singleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_property_XRServer: + +.. rst-class:: classref-property + +:ref:`XRServer` **XRServer** :ref:`🔗` + +The :ref:`XRServer` singleton. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_@GlobalScope_method_abs: + +.. rst-class:: classref-method + +:ref:`Variant` **abs**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` + +Returns the absolute value of a :ref:`Variant` parameter ``x`` (i.e. non-negative value). Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. + +:: + + var a = abs(-1) + # a is 1 + + var b = abs(-1.2) + # b is 1.2 + + var c = abs(Vector2(-3.5, -4)) + # c is (3.5, 4) + + var d = abs(Vector2i(-5, -6)) + # d is (5, 6) + + var e = abs(Vector3(-7, 8.5, -3.8)) + # e is (7, 8.5, 3.8) + + var f = abs(Vector3i(-7, -8, -9)) + # f is (7, 8, 9) + +\ **Note:** For better type safety, use :ref:`absf()`, :ref:`absi()`, :ref:`Vector2.abs()`, :ref:`Vector2i.abs()`, :ref:`Vector3.abs()`, :ref:`Vector3i.abs()`, :ref:`Vector4.abs()`, or :ref:`Vector4i.abs()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_absf: + +.. rst-class:: classref-method + +:ref:`float` **absf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the absolute value of float parameter ``x`` (i.e. positive value). + +:: + + # a is 1.2 + var a = absf(-1.2) + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_absi: + +.. rst-class:: classref-method + +:ref:`int` **absi**\ (\ x\: :ref:`int`\ ) :ref:`🔗` + +Returns the absolute value of int parameter ``x`` (i.e. positive value). + +:: + + # a is 1 + var a = absi(-1) + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_acos: + +.. rst-class:: classref-method + +:ref:`float` **acos**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the arc cosine of ``x`` in radians. Use to get the angle of cosine ``x``. ``x`` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent :ref:`acos()` from returning :ref:`@GDScript.NAN`. + +:: + + # c is 0.523599 or 30 degrees if converted with rad_to_deg(c) + var c = acos(0.866025) + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_acosh: + +.. rst-class:: classref-method + +:ref:`float` **acosh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the hyperbolic arc (also called inverse) cosine of ``x``, returning a value in radians. Use it to get the angle from an angle's cosine in hyperbolic space if ``x`` is larger or equal to 1. For values of ``x`` lower than 1, it will return 0, in order to prevent :ref:`acosh()` from returning :ref:`@GDScript.NAN`. + +:: + + var a = acosh(2) # Returns 1.31695789692482 + cosh(a) # Returns 2 + + var b = acosh(-1) # Returns 0 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_angle_difference: + +.. rst-class:: classref-method + +:ref:`float` **angle_difference**\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) :ref:`🔗` + +Returns the difference between the two angles (in radians), in the range of ``[-PI, +PI]``. When ``from`` and ``to`` are opposite, returns ``-PI`` if ``from`` is smaller than ``to``, or ``PI`` otherwise. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_asin: + +.. rst-class:: classref-method + +:ref:`float` **asin**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the arc sine of ``x`` in radians. Use to get the angle of sine ``x``. ``x`` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent :ref:`asin()` from returning :ref:`@GDScript.NAN`. + +:: + + # s is 0.523599 or 30 degrees if converted with rad_to_deg(s) + var s = asin(0.5) + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_asinh: + +.. rst-class:: classref-method + +:ref:`float` **asinh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the hyperbolic arc (also called inverse) sine of ``x``, returning a value in radians. Use it to get the angle from an angle's sine in hyperbolic space. + +:: + + var a = asinh(0.9) # Returns 0.8088669356527824 + sinh(a) # Returns 0.9 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_atan: + +.. rst-class:: classref-method + +:ref:`float` **atan**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the arc tangent of ``x`` in radians. Use it to get the angle from an angle's tangent in trigonometry. + +The method cannot know in which quadrant the angle should fall. See :ref:`atan2()` if you have both ``y`` and ``x``. + +:: + + var a = atan(0.5) # a is 0.463648 + +If ``x`` is between ``-PI / 2`` and ``PI / 2`` (inclusive), ``atan(tan(x))`` is equal to ``x``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_atan2: + +.. rst-class:: classref-method + +:ref:`float` **atan2**\ (\ y\: :ref:`float`, x\: :ref:`float`\ ) :ref:`🔗` + +Returns the arc tangent of ``y/x`` in radians. Use to get the angle of tangent ``y/x``. To compute the value, the method takes into account the sign of both arguments in order to determine the quadrant. + +Important note: The Y coordinate comes first, by convention. + +:: + + var a = atan2(0, -1) # a is 3.141593 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_atanh: + +.. rst-class:: classref-method + +:ref:`float` **atanh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the hyperbolic arc (also called inverse) tangent of ``x``, returning a value in radians. Use it to get the angle from an angle's tangent in hyperbolic space if ``x`` is between -1 and 1 (non-inclusive). + +In mathematics, the inverse hyperbolic tangent is only defined for -1 < ``x`` < 1 in the real set, so values equal or lower to -1 for ``x`` return negative :ref:`@GDScript.INF` and values equal or higher than 1 return positive :ref:`@GDScript.INF` in order to prevent :ref:`atanh()` from returning :ref:`@GDScript.NAN`. + +:: + + var a = atanh(0.9) # Returns 1.47221948958322 + tanh(a) # Returns 0.9 + + var b = atanh(-2) # Returns -inf + tanh(b) # Returns -1 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_bezier_derivative: + +.. rst-class:: classref-method + +:ref:`float` **bezier_derivative**\ (\ start\: :ref:`float`, control_1\: :ref:`float`, control_2\: :ref:`float`, end\: :ref:`float`, t\: :ref:`float`\ ) :ref:`🔗` + +Returns the derivative at the given ``t`` on a one-dimensional `Bézier curve `__ defined by the given ``control_1``, ``control_2``, and ``end`` points. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_bezier_interpolate: + +.. rst-class:: classref-method + +:ref:`float` **bezier_interpolate**\ (\ start\: :ref:`float`, control_1\: :ref:`float`, control_2\: :ref:`float`, end\: :ref:`float`, t\: :ref:`float`\ ) :ref:`🔗` + +Returns the point at the given ``t`` on a one-dimensional `Bézier curve `__ defined by the given ``control_1``, ``control_2``, and ``end`` points. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_bytes_to_var: + +.. rst-class:: classref-method + +:ref:`Variant` **bytes_to_var**\ (\ bytes\: :ref:`PackedByteArray`\ ) :ref:`🔗` + +Decodes a byte array back to a :ref:`Variant` value, without decoding objects. + +\ **Note:** If you need object deserialization, see :ref:`bytes_to_var_with_objects()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_bytes_to_var_with_objects: + +.. rst-class:: classref-method + +:ref:`Variant` **bytes_to_var_with_objects**\ (\ bytes\: :ref:`PackedByteArray`\ ) :ref:`🔗` + +Decodes a byte array back to a :ref:`Variant` value. Decoding objects is allowed. + +\ **Warning:** Deserialized object can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats (remote code execution). + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_ceil: + +.. rst-class:: classref-method + +:ref:`Variant` **ceil**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` + +Rounds ``x`` upward (towards positive infinity), returning the smallest whole number that is not less than ``x``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. + +:: + + var i = ceil(1.45) # i is 2.0 + i = ceil(1.001) # i is 2.0 + +See also :ref:`floor()`, :ref:`round()`, and :ref:`snapped()`. + +\ **Note:** For better type safety, use :ref:`ceilf()`, :ref:`ceili()`, :ref:`Vector2.ceil()`, :ref:`Vector3.ceil()`, or :ref:`Vector4.ceil()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_ceilf: + +.. rst-class:: classref-method + +:ref:`float` **ceilf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Rounds ``x`` upward (towards positive infinity), returning the smallest whole number that is not less than ``x``. + +A type-safe version of :ref:`ceil()`, returning a :ref:`float`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_ceili: + +.. rst-class:: classref-method + +:ref:`int` **ceili**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Rounds ``x`` upward (towards positive infinity), returning the smallest whole number that is not less than ``x``. + +A type-safe version of :ref:`ceil()`, returning an :ref:`int`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_clamp: + +.. rst-class:: classref-method + +:ref:`Variant` **clamp**\ (\ value\: :ref:`Variant`, min\: :ref:`Variant`, max\: :ref:`Variant`\ ) :ref:`🔗` + +Clamps the ``value``, returning a :ref:`Variant` not less than ``min`` and not more than ``max``. Any values that can be compared with the less than and greater than operators will work. + +:: + + var a = clamp(-10, -1, 5) + # a is -1 + + var b = clamp(8.1, 0.9, 5.5) + # b is 5.5 + +\ **Note:** For better type safety, use :ref:`clampf()`, :ref:`clampi()`, :ref:`Vector2.clamp()`, :ref:`Vector2i.clamp()`, :ref:`Vector3.clamp()`, :ref:`Vector3i.clamp()`, :ref:`Vector4.clamp()`, :ref:`Vector4i.clamp()`, or :ref:`Color.clamp()` (not currently supported by this method). + +\ **Note:** When using this on vectors it will *not* perform component-wise clamping, and will pick ``min`` if ``value < min`` or ``max`` if ``value > max``. To perform component-wise clamping use the methods listed above. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_clampf: + +.. rst-class:: classref-method + +:ref:`float` **clampf**\ (\ value\: :ref:`float`, min\: :ref:`float`, max\: :ref:`float`\ ) :ref:`🔗` + +Clamps the ``value``, returning a :ref:`float` not less than ``min`` and not more than ``max``. + +:: + + var speed = 42.1 + var a = clampf(speed, 1.0, 20.5) # a is 20.5 + + speed = -10.0 + var b = clampf(speed, -1.0, 1.0) # b is -1.0 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_clampi: + +.. rst-class:: classref-method + +:ref:`int` **clampi**\ (\ value\: :ref:`int`, min\: :ref:`int`, max\: :ref:`int`\ ) :ref:`🔗` + +Clamps the ``value``, returning an :ref:`int` not less than ``min`` and not more than ``max``. + +:: + + var speed = 42 + var a = clampi(speed, 1, 20) # a is 20 + + speed = -10 + var b = clampi(speed, -1, 1) # b is -1 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_cos: + +.. rst-class:: classref-method + +:ref:`float` **cos**\ (\ angle_rad\: :ref:`float`\ ) :ref:`🔗` + +Returns the cosine of angle ``angle_rad`` in radians. + +:: + + cos(PI * 2) # Returns 1.0 + cos(PI) # Returns -1.0 + cos(deg_to_rad(90)) # Returns 0.0 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_cosh: + +.. rst-class:: classref-method + +:ref:`float` **cosh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the hyperbolic cosine of ``x`` in radians. + +:: + + print(cosh(1)) # Prints 1.543081 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_cubic_interpolate: + +.. rst-class:: classref-method + +:ref:`float` **cubic_interpolate**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` + +Cubic interpolates between two values by the factor defined in ``weight`` with ``pre`` and ``post`` values. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_cubic_interpolate_angle: + +.. rst-class:: classref-method + +:ref:`float` **cubic_interpolate_angle**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` + +Cubic interpolates between two rotation values with shortest path by the factor defined in ``weight`` with ``pre`` and ``post`` values. See also :ref:`lerp_angle()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_cubic_interpolate_angle_in_time: + +.. rst-class:: classref-method + +:ref:`float` **cubic_interpolate_angle_in_time**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`, to_t\: :ref:`float`, pre_t\: :ref:`float`, post_t\: :ref:`float`\ ) :ref:`🔗` + +Cubic interpolates between two rotation values with shortest path by the factor defined in ``weight`` with ``pre`` and ``post`` values. See also :ref:`lerp_angle()`. + +It can perform smoother interpolation than :ref:`cubic_interpolate()` by the time values. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_cubic_interpolate_in_time: + +.. rst-class:: classref-method + +:ref:`float` **cubic_interpolate_in_time**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`, to_t\: :ref:`float`, pre_t\: :ref:`float`, post_t\: :ref:`float`\ ) :ref:`🔗` + +Cubic interpolates between two values by the factor defined in ``weight`` with ``pre`` and ``post`` values. + +It can perform smoother interpolation than :ref:`cubic_interpolate()` by the time values. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_db_to_linear: + +.. rst-class:: classref-method + +:ref:`float` **db_to_linear**\ (\ db\: :ref:`float`\ ) :ref:`🔗` + +Converts from decibels to linear energy (audio). + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_deg_to_rad: + +.. rst-class:: classref-method + +:ref:`float` **deg_to_rad**\ (\ deg\: :ref:`float`\ ) :ref:`🔗` + +Converts an angle expressed in degrees to radians. + +:: + + var r = deg_to_rad(180) # r is 3.141593 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_ease: + +.. rst-class:: classref-method + +:ref:`float` **ease**\ (\ x\: :ref:`float`, curve\: :ref:`float`\ ) :ref:`🔗` + +Returns an "eased" value of ``x`` based on an easing function defined with ``curve``. This easing function is based on an exponent. The ``curve`` can be any floating-point number, with specific values leading to the following behaviors: + +.. code:: text + + - Lower than -1.0 (exclusive): Ease in-out + - -1.0: Linear + - Between -1.0 and 0.0 (exclusive): Ease out-in + - 0.0: Constant + - Between 0.0 to 1.0 (exclusive): Ease out + - 1.0: Linear + - Greater than 1.0 (exclusive): Ease in + +\ `ease() curve values cheatsheet `__\ + +See also :ref:`smoothstep()`. If you need to perform more advanced transitions, use :ref:`Tween.interpolate_value()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_error_string: + +.. rst-class:: classref-method + +:ref:`String` **error_string**\ (\ error\: :ref:`int`\ ) :ref:`🔗` + +Returns a human-readable name for the given :ref:`Error` code. + +:: + + print(OK) # Prints 0 + print(error_string(OK)) # Prints "OK" + print(error_string(ERR_BUSY)) # Prints "Busy" + print(error_string(ERR_OUT_OF_MEMORY)) # Prints "Out of memory" + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_exp: + +.. rst-class:: classref-method + +:ref:`float` **exp**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +The natural exponential function. It raises the mathematical constant *e* to the power of ``x`` and returns it. + +\ *e* has an approximate value of 2.71828, and can be obtained with ``exp(1)``. + +For exponents to other bases use the method :ref:`pow()`. + +:: + + var a = exp(2) # Approximately 7.39 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_floor: + +.. rst-class:: classref-method + +:ref:`Variant` **floor**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` + +Rounds ``x`` downward (towards negative infinity), returning the largest whole number that is not more than ``x``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. + +:: + + var a = floor(2.99) # a is 2.0 + a = floor(-2.99) # a is -3.0 + +See also :ref:`ceil()`, :ref:`round()`, and :ref:`snapped()`. + +\ **Note:** For better type safety, use :ref:`floorf()`, :ref:`floori()`, :ref:`Vector2.floor()`, :ref:`Vector3.floor()`, or :ref:`Vector4.floor()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_floorf: + +.. rst-class:: classref-method + +:ref:`float` **floorf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Rounds ``x`` downward (towards negative infinity), returning the largest whole number that is not more than ``x``. + +A type-safe version of :ref:`floor()`, returning a :ref:`float`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_floori: + +.. rst-class:: classref-method + +:ref:`int` **floori**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Rounds ``x`` downward (towards negative infinity), returning the largest whole number that is not more than ``x``. + +A type-safe version of :ref:`floor()`, returning an :ref:`int`. + +\ **Note:** This function is *not* the same as ``int(x)``, which rounds towards 0. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_fmod: + +.. rst-class:: classref-method + +:ref:`float` **fmod**\ (\ x\: :ref:`float`, y\: :ref:`float`\ ) :ref:`🔗` + +Returns the floating-point remainder of ``x`` divided by ``y``, keeping the sign of ``x``. + +:: + + var remainder = fmod(7, 5.5) # remainder is 1.5 + +For the integer remainder operation, use the ``%`` operator. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_fposmod: + +.. rst-class:: classref-method + +:ref:`float` **fposmod**\ (\ x\: :ref:`float`, y\: :ref:`float`\ ) :ref:`🔗` + +Returns the floating-point modulus of ``x`` divided by ``y``, wrapping equally in positive and negative. + +:: + + print(" (x) (fmod(x, 1.5)) (fposmod(x, 1.5))") + for i in 7: + var x = i * 0.5 - 1.5 + print("%4.1f %4.1f | %4.1f" % [x, fmod(x, 1.5), fposmod(x, 1.5)]) + +Prints: + +.. code:: text + + (x) (fmod(x, 1.5)) (fposmod(x, 1.5)) + -1.5 -0.0 | 0.0 + -1.0 -1.0 | 0.5 + -0.5 -0.5 | 1.0 + 0.0 0.0 | 0.0 + 0.5 0.5 | 0.5 + 1.0 1.0 | 1.0 + 1.5 0.0 | 0.0 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_hash: + +.. rst-class:: classref-method + +:ref:`int` **hash**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` + +Returns the integer hash of the passed ``variable``. + + +.. tabs:: + + .. code-tab:: gdscript + + print(hash("a")) # Prints 177670 + + .. code-tab:: csharp + + GD.Print(GD.Hash("a")); // Prints 177670 + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_instance_from_id: + +.. rst-class:: classref-method + +:ref:`Object` **instance_from_id**\ (\ instance_id\: :ref:`int`\ ) :ref:`🔗` + +Returns the :ref:`Object` that corresponds to ``instance_id``. All Objects have a unique instance ID. See also :ref:`Object.get_instance_id()`. + + +.. tabs:: + + .. code-tab:: gdscript + + var drink = "water" + + func _ready(): + var id = get_instance_id() + var instance = instance_from_id(id) + print(instance.foo) # Prints "water" + + .. code-tab:: csharp + + public partial class MyNode : Node + { + public string Drink { get; set; } = "water"; + + public override void _Ready() + { + ulong id = GetInstanceId(); + var instance = (MyNode)InstanceFromId(Id); + GD.Print(instance.Drink); // Prints "water" + } + } + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_inverse_lerp: + +.. rst-class:: classref-method + +:ref:`float` **inverse_lerp**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` + +Returns an interpolation or extrapolation factor considering the range specified in ``from`` and ``to``, and the interpolated value specified in ``weight``. The returned value will be between ``0.0`` and ``1.0`` if ``weight`` is between ``from`` and ``to`` (inclusive). If ``weight`` is located outside this range, then an extrapolation factor will be returned (return value lower than ``0.0`` or greater than ``1.0``). Use :ref:`clamp()` on the result of :ref:`inverse_lerp()` if this is not desired. + +:: + + # The interpolation ratio in the `lerp()` call below is 0.75. + var middle = lerp(20, 30, 0.75) + # middle is now 27.5. + + # Now, we pretend to have forgotten the original ratio and want to get it back. + var ratio = inverse_lerp(20, 30, 27.5) + # ratio is now 0.75. + +See also :ref:`lerp()`, which performs the reverse of this operation, and :ref:`remap()` to map a continuous series of values to another. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_is_equal_approx: + +.. rst-class:: classref-method + +:ref:`bool` **is_equal_approx**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) :ref:`🔗` + +Returns ``true`` if ``a`` and ``b`` are approximately equal to each other. + +Here, "approximately equal" means that ``a`` and ``b`` are within a small internal epsilon of each other, which scales with the magnitude of the numbers. + +Infinity values of the same sign are considered equal. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_is_finite: + +.. rst-class:: classref-method + +:ref:`bool` **is_finite**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns whether ``x`` is a finite value, i.e. it is not :ref:`@GDScript.NAN`, positive infinity, or negative infinity. See also :ref:`is_inf()` and :ref:`is_nan()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_is_inf: + +.. rst-class:: classref-method + +:ref:`bool` **is_inf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns ``true`` if ``x`` is either positive infinity or negative infinity. See also :ref:`is_finite()` and :ref:`is_nan()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_is_instance_id_valid: + +.. rst-class:: classref-method + +:ref:`bool` **is_instance_id_valid**\ (\ id\: :ref:`int`\ ) :ref:`🔗` + +Returns ``true`` if the Object that corresponds to ``id`` is a valid object (e.g. has not been deleted from memory). All Objects have a unique instance ID. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_is_instance_valid: + +.. rst-class:: classref-method + +:ref:`bool` **is_instance_valid**\ (\ instance\: :ref:`Variant`\ ) :ref:`🔗` + +Returns ``true`` if ``instance`` is a valid Object (e.g. has not been deleted from memory). + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_is_nan: + +.. rst-class:: classref-method + +:ref:`bool` **is_nan**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns ``true`` if ``x`` is a NaN ("Not a Number" or invalid) value. This method is needed as :ref:`@GDScript.NAN` is not equal to itself, which means ``x == NAN`` can't be used to check whether a value is a NaN. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_is_same: + +.. rst-class:: classref-method + +:ref:`bool` **is_same**\ (\ a\: :ref:`Variant`, b\: :ref:`Variant`\ ) :ref:`🔗` + +Returns ``true``, for value types, if ``a`` and ``b`` share the same value. Returns ``true``, for reference types, if the references of ``a`` and ``b`` are the same. + +:: + + # Vector2 is a value type + var vec2_a = Vector2(0, 0) + var vec2_b = Vector2(0, 0) + var vec2_c = Vector2(1, 1) + is_same(vec2_a, vec2_a) # true + is_same(vec2_a, vec2_b) # true + is_same(vec2_a, vec2_c) # false + + # Array is a reference type + var arr_a = [] + var arr_b = [] + is_same(arr_a, arr_a) # true + is_same(arr_a, arr_b) # false + +These are :ref:`Variant` value types: ``null``, :ref:`bool`, :ref:`int`, :ref:`float`, :ref:`String`, :ref:`StringName`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`, :ref:`Rect2`, :ref:`Rect2i`, :ref:`Transform2D`, :ref:`Transform3D`, :ref:`Plane`, :ref:`Quaternion`, :ref:`AABB`, :ref:`Basis`, :ref:`Projection`, :ref:`Color`, :ref:`NodePath`, :ref:`RID`, :ref:`Callable` and :ref:`Signal`. + +These are :ref:`Variant` reference types: :ref:`Object`, :ref:`Dictionary`, :ref:`Array`, :ref:`PackedByteArray`, :ref:`PackedInt32Array`, :ref:`PackedInt64Array`, :ref:`PackedFloat32Array`, :ref:`PackedFloat64Array`, :ref:`PackedStringArray`, :ref:`PackedVector2Array`, :ref:`PackedVector3Array`, :ref:`PackedVector4Array`, and :ref:`PackedColorArray`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_is_zero_approx: + +.. rst-class:: classref-method + +:ref:`bool` **is_zero_approx**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns ``true`` if ``x`` is zero or almost zero. The comparison is done using a tolerance calculation with a small internal epsilon. + +This function is faster than using :ref:`is_equal_approx()` with one value as zero. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_lerp: + +.. rst-class:: classref-method + +:ref:`Variant` **lerp**\ (\ from\: :ref:`Variant`, to\: :ref:`Variant`, weight\: :ref:`Variant`\ ) :ref:`🔗` + +Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use :ref:`clampf()` to limit ``weight``. + +Both ``from`` and ``to`` must be the same type. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector3`, :ref:`Vector4`, :ref:`Color`, :ref:`Quaternion`, :ref:`Basis`, :ref:`Transform2D`, :ref:`Transform3D`. + +:: + + lerp(0, 4, 0.75) # Returns 3.0 + +See also :ref:`inverse_lerp()` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp()`, combine it with :ref:`ease()` or :ref:`smoothstep()`. See also :ref:`remap()` to map a continuous series of values to another. + +\ **Note:** For better type safety, use :ref:`lerpf()`, :ref:`Vector2.lerp()`, :ref:`Vector3.lerp()`, :ref:`Vector4.lerp()`, :ref:`Color.lerp()`, :ref:`Quaternion.slerp()`, :ref:`Basis.slerp()`, :ref:`Transform2D.interpolate_with()`, or :ref:`Transform3D.interpolate_with()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_lerp_angle: + +.. rst-class:: classref-method + +:ref:`float` **lerp_angle**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` + +Linearly interpolates between two angles (in radians) by a ``weight`` value between 0.0 and 1.0. + +Similar to :ref:`lerp()`, but interpolates correctly when the angles wrap around :ref:`@GDScript.TAU`. To perform eased interpolation with :ref:`lerp_angle()`, combine it with :ref:`ease()` or :ref:`smoothstep()`. + +:: + + extends Sprite + var elapsed = 0.0 + func _process(delta): + var min_angle = deg_to_rad(0.0) + var max_angle = deg_to_rad(90.0) + rotation = lerp_angle(min_angle, max_angle, elapsed) + elapsed += delta + +\ **Note:** This function lerps through the shortest path between ``from`` and ``to``. However, when these two angles are approximately ``PI + k * TAU`` apart for any integer ``k``, it's not obvious which way they lerp due to floating-point precision errors. For example, ``lerp_angle(0, PI, weight)`` lerps counter-clockwise, while ``lerp_angle(0, PI + 5 * TAU, weight)`` lerps clockwise. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_lerpf: + +.. rst-class:: classref-method + +:ref:`float` **lerpf**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` + +Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use :ref:`clampf()` on the result of this function. + +:: + + lerpf(0, 4, 0.75) # Returns 3.0 + +See also :ref:`inverse_lerp()` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp()`, combine it with :ref:`ease()` or :ref:`smoothstep()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_linear_to_db: + +.. rst-class:: classref-method + +:ref:`float` **linear_to_db**\ (\ lin\: :ref:`float`\ ) :ref:`🔗` + +Converts from linear energy to decibels (audio). Since volume is not normally linear, this can be used to implement volume sliders that behave as expected. + +\ **Example:** Change the Master bus's volume through a :ref:`Slider` node, which ranges from ``0.0`` to ``1.0``: + +:: + + AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db($Slider.value)) + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_log: + +.. rst-class:: classref-method + +:ref:`float` **log**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the `natural logarithm `__ of ``x`` (base `[i]e[/i] `__, with *e* being approximately 2.71828). This is the amount of time needed to reach a certain level of continuous growth. + +\ **Note:** This is not the same as the "log" function on most calculators, which uses a base 10 logarithm. To use base 10 logarithm, use ``log(x) / log(10)``. + +:: + + log(10) # Returns 2.302585 + +\ **Note:** The logarithm of ``0`` returns ``-inf``, while negative values return ``-nan``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_max: + +.. rst-class:: classref-method + +:ref:`Variant` **max**\ (\ ...\ ) |vararg| :ref:`🔗` + +Returns the maximum of the given numeric values. This function can take any number of arguments. + +:: + + max(1, 7, 3, -6, 5) # Returns 7 + +\ **Note:** When using this on vectors it will *not* perform component-wise maximum, and will pick the largest value when compared using ``x < y``. To perform component-wise maximum, use :ref:`Vector2.max()`, :ref:`Vector2i.max()`, :ref:`Vector3.max()`, :ref:`Vector3i.max()`, :ref:`Vector4.max()`, and :ref:`Vector4i.max()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_maxf: + +.. rst-class:: classref-method + +:ref:`float` **maxf**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) :ref:`🔗` + +Returns the maximum of two :ref:`float` values. + +:: + + maxf(3.6, 24) # Returns 24.0 + maxf(-3.99, -4) # Returns -3.99 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_maxi: + +.. rst-class:: classref-method + +:ref:`int` **maxi**\ (\ a\: :ref:`int`, b\: :ref:`int`\ ) :ref:`🔗` + +Returns the maximum of two :ref:`int` values. + +:: + + maxi(1, 2) # Returns 2 + maxi(-3, -4) # Returns -3 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_min: + +.. rst-class:: classref-method + +:ref:`Variant` **min**\ (\ ...\ ) |vararg| :ref:`🔗` + +Returns the minimum of the given numeric values. This function can take any number of arguments. + +:: + + min(1, 7, 3, -6, 5) # Returns -6 + +\ **Note:** When using this on vectors it will *not* perform component-wise minimum, and will pick the smallest value when compared using ``x < y``. To perform component-wise minimum, use :ref:`Vector2.min()`, :ref:`Vector2i.min()`, :ref:`Vector3.min()`, :ref:`Vector3i.min()`, :ref:`Vector4.min()`, and :ref:`Vector4i.min()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_minf: + +.. rst-class:: classref-method + +:ref:`float` **minf**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) :ref:`🔗` + +Returns the minimum of two :ref:`float` values. + +:: + + minf(3.6, 24) # Returns 3.6 + minf(-3.99, -4) # Returns -4.0 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_mini: + +.. rst-class:: classref-method + +:ref:`int` **mini**\ (\ a\: :ref:`int`, b\: :ref:`int`\ ) :ref:`🔗` + +Returns the minimum of two :ref:`int` values. + +:: + + mini(1, 2) # Returns 1 + mini(-3, -4) # Returns -4 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_move_toward: + +.. rst-class:: classref-method + +:ref:`float` **move_toward**\ (\ from\: :ref:`float`, to\: :ref:`float`, delta\: :ref:`float`\ ) :ref:`🔗` + +Moves ``from`` toward ``to`` by the ``delta`` amount. Will not go past ``to``. + +Use a negative ``delta`` value to move away. + +:: + + move_toward(5, 10, 4) # Returns 9 + move_toward(10, 5, 4) # Returns 6 + move_toward(5, 10, 9) # Returns 10 + move_toward(10, 5, -1.5) # Returns 11.5 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_nearest_po2: + +.. rst-class:: classref-method + +:ref:`int` **nearest_po2**\ (\ value\: :ref:`int`\ ) :ref:`🔗` + +Returns the smallest integer power of 2 that is greater than or equal to ``value``. + +:: + + nearest_po2(3) # Returns 4 + nearest_po2(4) # Returns 4 + nearest_po2(5) # Returns 8 + + nearest_po2(0) # Returns 0 (this may not be expected) + nearest_po2(-1) # Returns 0 (this may not be expected) + +\ **Warning:** Due to its implementation, this method returns ``0`` rather than ``1`` for values less than or equal to ``0``, with an exception for ``value`` being the smallest negative 64-bit integer (``-9223372036854775808``) in which case the ``value`` is returned unchanged. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_pingpong: + +.. rst-class:: classref-method + +:ref:`float` **pingpong**\ (\ value\: :ref:`float`, length\: :ref:`float`\ ) :ref:`🔗` + +Wraps ``value`` between ``0`` and the ``length``. If the limit is reached, the next value the function returns is decreased to the ``0`` side or increased to the ``length`` side (like a triangle wave). If ``length`` is less than zero, it becomes positive. + +:: + + pingpong(-3.0, 3.0) # Returns 3.0 + pingpong(-2.0, 3.0) # Returns 2.0 + pingpong(-1.0, 3.0) # Returns 1.0 + pingpong(0.0, 3.0) # Returns 0.0 + pingpong(1.0, 3.0) # Returns 1.0 + pingpong(2.0, 3.0) # Returns 2.0 + pingpong(3.0, 3.0) # Returns 3.0 + pingpong(4.0, 3.0) # Returns 2.0 + pingpong(5.0, 3.0) # Returns 1.0 + pingpong(6.0, 3.0) # Returns 0.0 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_posmod: + +.. rst-class:: classref-method + +:ref:`int` **posmod**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) :ref:`🔗` + +Returns the integer modulus of ``x`` divided by ``y`` that wraps equally in positive and negative. + +:: + + print("#(i) (i % 3) (posmod(i, 3))") + for i in range(-3, 4): + print("%2d %2d | %2d" % [i, i % 3, posmod(i, 3)]) + +Prints: + +.. code:: text + + (i) (i % 3) (posmod(i, 3)) + -3 0 | 0 + -2 -2 | 1 + -1 -1 | 2 + 0 0 | 0 + 1 1 | 1 + 2 2 | 2 + 3 0 | 0 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_pow: + +.. rst-class:: classref-method + +:ref:`float` **pow**\ (\ base\: :ref:`float`, exp\: :ref:`float`\ ) :ref:`🔗` + +Returns the result of ``base`` raised to the power of ``exp``. + +In GDScript, this is the equivalent of the ``**`` operator. + +:: + + pow(2, 5) # Returns 32.0 + pow(4, 1.5) # Returns 8.0 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_print: + +.. rst-class:: classref-method + +|void| **print**\ (\ ...\ ) |vararg| :ref:`🔗` + +Converts one or more arguments of any type to string in the best way possible and prints them to the console. + + +.. tabs:: + + .. code-tab:: gdscript + + var a = [1, 2, 3] + print("a", "b", a) # Prints "ab[1, 2, 3]" + + .. code-tab:: csharp + + Godot.Collections.Array a = [1, 2, 3]; + GD.Print("a", "b", a); // Prints "ab[1, 2, 3]" + + + +\ **Note:** Consider using :ref:`push_error()` and :ref:`push_warning()` to print error and warning messages instead of :ref:`print()` or :ref:`print_rich()`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. See also :ref:`Engine.print_to_stdout` and :ref:`ProjectSettings.application/run/disable_stdout`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_print_rich: + +.. rst-class:: classref-method + +|void| **print_rich**\ (\ ...\ ) |vararg| :ref:`🔗` + +Converts one or more arguments of any type to string in the best way possible and prints them to the console. + +The following BBCode tags are supported: ``b``, ``i``, ``u``, ``s``, ``indent``, ``code``, ``url``, ``center``, ``right``, ``color``, ``bgcolor``, ``fgcolor``. + +URL tags only support URLs wrapped by a URL tag, not URLs with a different title. + +When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Support for ANSI escape codes varies across terminal emulators, especially for italic and strikethrough. In standard output, ``code`` is represented with faint text but without any font change. Unsupported tags are left as-is in standard output. + + +.. tabs:: + + .. code-tab:: gdscript + + print_rich("[color=green][b]Hello world![/b][/color]") # Prints "Hello world!", in green with a bold font. + + .. code-tab:: csharp + + GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints "Hello world!", in green with a bold font. + + + +\ **Note:** Consider using :ref:`push_error()` and :ref:`push_warning()` to print error and warning messages instead of :ref:`print()` or :ref:`print_rich()`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. + +\ **Note:** Output displayed in the editor supports clickable ``[url=address]text[/url]`` tags. The ``[url]`` tag's ``address`` value is handled by :ref:`OS.shell_open()` when clicked. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_print_verbose: + +.. rst-class:: classref-method + +|void| **print_verbose**\ (\ ...\ ) |vararg| :ref:`🔗` + +If verbose mode is enabled (:ref:`OS.is_stdout_verbose()` returning ``true``), converts one or more arguments of any type to string in the best way possible and prints them to the console. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_printerr: + +.. rst-class:: classref-method + +|void| **printerr**\ (\ ...\ ) |vararg| :ref:`🔗` + +Prints one or more arguments to strings in the best way possible to standard error line. + + +.. tabs:: + + .. code-tab:: gdscript + + printerr("prints to stderr") + + .. code-tab:: csharp + + GD.PrintErr("prints to stderr"); + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_printraw: + +.. rst-class:: classref-method + +|void| **printraw**\ (\ ...\ ) |vararg| :ref:`🔗` + +Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike :ref:`print()`, no newline is automatically added at the end. + +\ **Note:** The OS terminal is *not* the same as the editor's Output dock. The output sent to the OS terminal can be seen when running Godot from a terminal. On Windows, this requires using the ``console.exe`` executable. + + +.. tabs:: + + .. code-tab:: gdscript + + # Prints "ABC" to terminal. + printraw("A") + printraw("B") + printraw("C") + + .. code-tab:: csharp + + // Prints "ABC" to terminal. + GD.PrintRaw("A"); + GD.PrintRaw("B"); + GD.PrintRaw("C"); + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_prints: + +.. rst-class:: classref-method + +|void| **prints**\ (\ ...\ ) |vararg| :ref:`🔗` + +Prints one or more arguments to the console with a space between each argument. + + +.. tabs:: + + .. code-tab:: gdscript + + prints("A", "B", "C") # Prints "A B C" + + .. code-tab:: csharp + + GD.PrintS("A", "B", "C"); // Prints "A B C" + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_printt: + +.. rst-class:: classref-method + +|void| **printt**\ (\ ...\ ) |vararg| :ref:`🔗` + +Prints one or more arguments to the console with a tab between each argument. + + +.. tabs:: + + .. code-tab:: gdscript + + printt("A", "B", "C") # Prints "A B C" + + .. code-tab:: csharp + + GD.PrintT("A", "B", "C"); // Prints "A B C" + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_push_error: + +.. rst-class:: classref-method + +|void| **push_error**\ (\ ...\ ) |vararg| :ref:`🔗` + +Pushes an error message to Godot's built-in debugger and to the OS terminal. + + +.. tabs:: + + .. code-tab:: gdscript + + push_error("test error") # Prints "test error" to debugger and terminal as an error. + + .. code-tab:: csharp + + GD.PushError("test error"); // Prints "test error" to debugger and terminal as an error. + + + +\ **Note:** This function does not pause project execution. To print an error message and pause project execution in debug builds, use ``assert(false, "test error")`` instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_push_warning: + +.. rst-class:: classref-method + +|void| **push_warning**\ (\ ...\ ) |vararg| :ref:`🔗` + +Pushes a warning message to Godot's built-in debugger and to the OS terminal. + + +.. tabs:: + + .. code-tab:: gdscript + + push_warning("test warning") # Prints "test warning" to debugger and terminal as a warning. + + .. code-tab:: csharp + + GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as a warning. + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_rad_to_deg: + +.. rst-class:: classref-method + +:ref:`float` **rad_to_deg**\ (\ rad\: :ref:`float`\ ) :ref:`🔗` + +Converts an angle expressed in radians to degrees. + +:: + + rad_to_deg(0.523599) # Returns 30 + rad_to_deg(PI) # Returns 180 + rad_to_deg(PI * 2) # Returns 360 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_rand_from_seed: + +.. rst-class:: classref-method + +:ref:`PackedInt64Array` **rand_from_seed**\ (\ seed\: :ref:`int`\ ) :ref:`🔗` + +Given a ``seed``, returns a :ref:`PackedInt64Array` of size ``2``, where its first element is the randomized :ref:`int` value, and the second element is the same as ``seed``. Passing the same ``seed`` consistently returns the same array. + +\ **Note:** "Seed" here refers to the internal state of the pseudo random number generator, currently implemented as a 64 bit integer. + +:: + + var a = rand_from_seed(4) + + print(a[0]) # Prints 2879024997 + print(a[1]) # Prints 4 + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_randf: + +.. rst-class:: classref-method + +:ref:`float` **randf**\ (\ ) :ref:`🔗` + +Returns a random floating-point value between ``0.0`` and ``1.0`` (inclusive). + + +.. tabs:: + + .. code-tab:: gdscript + + randf() # Returns e.g. 0.375671 + + .. code-tab:: csharp + + GD.Randf(); // Returns e.g. 0.375671 + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_randf_range: + +.. rst-class:: classref-method + +:ref:`float` **randf_range**\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) :ref:`🔗` + +Returns a random floating-point value between ``from`` and ``to`` (inclusive). + + +.. tabs:: + + .. code-tab:: gdscript -- **TYPE_STRING** = **4** --- Variable is of type :ref:`String`. + randf_range(0, 20.5) # Returns e.g. 7.45315 + randf_range(-10, 10) # Returns e.g. -3.844535 -- **TYPE_VECTOR2** = **5** --- Variable is of type :ref:`Vector2`. + .. code-tab:: csharp -- **TYPE_VECTOR2I** = **6** --- Variable is of type :ref:`Vector2i`. + GD.RandRange(0.0, 20.5); // Returns e.g. 7.45315 + GD.RandRange(-10.0, 10.0); // Returns e.g. -3.844535 -- **TYPE_RECT2** = **7** --- Variable is of type :ref:`Rect2`. -- **TYPE_RECT2I** = **8** --- Variable is of type :ref:`Rect2i`. -- **TYPE_VECTOR3** = **9** --- Variable is of type :ref:`Vector3`. +.. rst-class:: classref-item-separator -- **TYPE_VECTOR3I** = **10** --- Variable is of type :ref:`Vector3i`. +---- -- **TYPE_TRANSFORM2D** = **11** --- Variable is of type :ref:`Transform2D`. +.. _class_@GlobalScope_method_randfn: -- **TYPE_PLANE** = **12** --- Variable is of type :ref:`Plane`. +.. rst-class:: classref-method -- **TYPE_QUAT** = **13** --- Variable is of type :ref:`Quat`. +:ref:`float` **randfn**\ (\ mean\: :ref:`float`, deviation\: :ref:`float`\ ) :ref:`🔗` -- **TYPE_AABB** = **14** --- Variable is of type :ref:`AABB`. +Returns a `normally-distributed `__, pseudo-random floating-point value from the specified ``mean`` and a standard ``deviation``. This is also known as a Gaussian distribution. -- **TYPE_BASIS** = **15** --- Variable is of type :ref:`Basis`. +\ **Note:** This method uses the `Box-Muller transform `__ algorithm. -- **TYPE_TRANSFORM** = **16** --- Variable is of type :ref:`Transform`. +.. rst-class:: classref-item-separator -- **TYPE_COLOR** = **17** --- Variable is of type :ref:`Color`. +---- -- **TYPE_STRING_NAME** = **18** --- Variable is of type :ref:`StringName`. +.. _class_@GlobalScope_method_randi: -- **TYPE_NODE_PATH** = **19** --- Variable is of type :ref:`NodePath`. +.. rst-class:: classref-method -- **TYPE_RID** = **20** --- Variable is of type :ref:`RID`. +:ref:`int` **randi**\ (\ ) :ref:`🔗` -- **TYPE_OBJECT** = **21** --- Variable is of type :ref:`Object`. +Returns a random unsigned 32-bit integer. Use remainder to obtain a random value in the interval ``[0, N - 1]`` (where N is smaller than 2^32). -- **TYPE_CALLABLE** = **22** --- Variable is of type :ref:`Callable`. -- **TYPE_SIGNAL** = **23** --- Variable is of type :ref:`Signal`. +.. tabs:: -- **TYPE_DICTIONARY** = **24** --- Variable is of type :ref:`Dictionary`. + .. code-tab:: gdscript -- **TYPE_ARRAY** = **25** --- Variable is of type :ref:`Array`. + randi() # Returns random integer between 0 and 2^32 - 1 + randi() % 20 # Returns random integer between 0 and 19 + randi() % 100 # Returns random integer between 0 and 99 + randi() % 100 + 1 # Returns random integer between 1 and 100 -- **TYPE_RAW_ARRAY** = **26** --- Variable is of type :ref:`PackedByteArray`. + .. code-tab:: csharp -- **TYPE_INT32_ARRAY** = **27** --- Variable is of type :ref:`PackedInt32Array`. + GD.Randi(); // Returns random integer between 0 and 2^32 - 1 + GD.Randi() % 20; // Returns random integer between 0 and 19 + GD.Randi() % 100; // Returns random integer between 0 and 99 + GD.Randi() % 100 + 1; // Returns random integer between 1 and 100 -- **TYPE_INT64_ARRAY** = **28** --- Variable is of type :ref:`PackedInt64Array`. -- **TYPE_FLOAT32_ARRAY** = **29** --- Variable is of type :ref:`PackedFloat32Array`. -- **TYPE_FLOAT64_ARRAY** = **30** --- Variable is of type :ref:`PackedFloat64Array`. +.. rst-class:: classref-item-separator -- **TYPE_STRING_ARRAY** = **31** --- Variable is of type :ref:`PackedStringArray`. +---- -- **TYPE_VECTOR2_ARRAY** = **32** --- Variable is of type :ref:`PackedVector2Array`. +.. _class_@GlobalScope_method_randi_range: -- **TYPE_VECTOR3_ARRAY** = **33** --- Variable is of type :ref:`PackedVector3Array`. +.. rst-class:: classref-method -- **TYPE_COLOR_ARRAY** = **34** --- Variable is of type :ref:`PackedColorArray`. +:ref:`int` **randi_range**\ (\ from\: :ref:`int`, to\: :ref:`int`\ ) :ref:`🔗` -- **TYPE_MAX** = **35** --- Represents the size of the :ref:`Variant.Type` enum. +Returns a random signed 32-bit integer between ``from`` and ``to`` (inclusive). If ``to`` is lesser than ``from``, they are swapped. ----- -.. _enum_@GlobalScope_Variant.Operator: +.. tabs:: -.. _class_@GlobalScope_constant_OP_EQUAL: + .. code-tab:: gdscript -.. _class_@GlobalScope_constant_OP_NOT_EQUAL: + randi_range(0, 1) # Returns either 0 or 1 + randi_range(-10, 1000) # Returns random integer between -10 and 1000 -.. _class_@GlobalScope_constant_OP_LESS: + .. code-tab:: csharp -.. _class_@GlobalScope_constant_OP_LESS_EQUAL: + GD.RandRange(0, 1); // Returns either 0 or 1 + GD.RandRange(-10, 1000); // Returns random integer between -10 and 1000 -.. _class_@GlobalScope_constant_OP_GREATER: -.. _class_@GlobalScope_constant_OP_GREATER_EQUAL: -.. _class_@GlobalScope_constant_OP_ADD: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_OP_SUBTRACT: +---- -.. _class_@GlobalScope_constant_OP_MULTIPLY: +.. _class_@GlobalScope_method_randomize: -.. _class_@GlobalScope_constant_OP_DIVIDE: +.. rst-class:: classref-method -.. _class_@GlobalScope_constant_OP_NEGATE: +|void| **randomize**\ (\ ) :ref:`🔗` -.. _class_@GlobalScope_constant_OP_POSITIVE: +Randomizes the seed (or the internal state) of the random number generator. The current implementation uses a number based on the device's time. -.. _class_@GlobalScope_constant_OP_MODULE: +\ **Note:** This function is called automatically when the project is run. If you need to fix the seed to have consistent, reproducible results, use :ref:`seed()` to initialize the random number generator. -.. _class_@GlobalScope_constant_OP_STRING_CONCAT: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_OP_SHIFT_LEFT: +---- -.. _class_@GlobalScope_constant_OP_SHIFT_RIGHT: +.. _class_@GlobalScope_method_remap: -.. _class_@GlobalScope_constant_OP_BIT_AND: +.. rst-class:: classref-method -.. _class_@GlobalScope_constant_OP_BIT_OR: +:ref:`float` **remap**\ (\ value\: :ref:`float`, istart\: :ref:`float`, istop\: :ref:`float`, ostart\: :ref:`float`, ostop\: :ref:`float`\ ) :ref:`🔗` -.. _class_@GlobalScope_constant_OP_BIT_XOR: +Maps a ``value`` from range ``[istart, istop]`` to ``[ostart, ostop]``. See also :ref:`lerp()` and :ref:`inverse_lerp()`. If ``value`` is outside ``[istart, istop]``, then the resulting value will also be outside ``[ostart, ostop]``. If this is not desired, use :ref:`clamp()` on the result of this function. -.. _class_@GlobalScope_constant_OP_BIT_NEGATE: +:: -.. _class_@GlobalScope_constant_OP_AND: + remap(75, 0, 100, -1, 1) # Returns 0.5 -.. _class_@GlobalScope_constant_OP_OR: +For complex use cases where multiple ranges are needed, consider using :ref:`Curve` or :ref:`Gradient` instead. -.. _class_@GlobalScope_constant_OP_XOR: +\ **Note:** If ``istart == istop``, the return value is undefined (most likely NaN, INF, or -INF). -.. _class_@GlobalScope_constant_OP_NOT: +.. rst-class:: classref-item-separator -.. _class_@GlobalScope_constant_OP_IN: +---- -.. _class_@GlobalScope_constant_OP_MAX: +.. _class_@GlobalScope_method_rid_allocate_id: -enum **Variant.Operator**: +.. rst-class:: classref-method -- **OP_EQUAL** = **0** --- Equality operator (``==``). +:ref:`int` **rid_allocate_id**\ (\ ) :ref:`🔗` -- **OP_NOT_EQUAL** = **1** --- Inequality operator (``!=``). +Allocates a unique ID which can be used by the implementation to construct an RID. This is used mainly from native extensions to implement servers. -- **OP_LESS** = **2** --- Less than operator (``<``). +.. rst-class:: classref-item-separator + +---- -- **OP_LESS_EQUAL** = **3** --- Less than or equal operator (``<=``). +.. _class_@GlobalScope_method_rid_from_int64: -- **OP_GREATER** = **4** --- Greater than operator (``>``). +.. rst-class:: classref-method -- **OP_GREATER_EQUAL** = **5** --- Greater than or equal operator (``>=``). +:ref:`RID` **rid_from_int64**\ (\ base\: :ref:`int`\ ) :ref:`🔗` -- **OP_ADD** = **6** --- Addition operator (``+``). +Creates an RID from a ``base``. This is used mainly from native extensions to build servers. -- **OP_SUBTRACT** = **7** --- Subtraction operator (``-``). +.. rst-class:: classref-item-separator -- **OP_MULTIPLY** = **8** --- Multiplication operator (``*``). +---- -- **OP_DIVIDE** = **9** --- Division operator (``/``). +.. _class_@GlobalScope_method_rotate_toward: -- **OP_NEGATE** = **10** --- Unary negation operator (``-``). +.. rst-class:: classref-method -- **OP_POSITIVE** = **11** --- Unary plus operator (``+``). +:ref:`float` **rotate_toward**\ (\ from\: :ref:`float`, to\: :ref:`float`, delta\: :ref:`float`\ ) :ref:`🔗` -- **OP_MODULE** = **12** --- Remainder/modulo operator (``%``). +Rotates ``from`` toward ``to`` by the ``delta`` amount. Will not go past ``to``. -- **OP_STRING_CONCAT** = **13** --- String concatenation operator (``+``). +Similar to :ref:`move_toward()`, but interpolates correctly when the angles wrap around :ref:`@GDScript.TAU`. -- **OP_SHIFT_LEFT** = **14** --- Left shift operator (``<<``). +If ``delta`` is negative, this function will rotate away from ``to``, toward the opposite angle, and will not go past the opposite angle. -- **OP_SHIFT_RIGHT** = **15** --- Right shift operator (``>>``). +.. rst-class:: classref-item-separator -- **OP_BIT_AND** = **16** --- Bitwise AND operator (``&``). +---- -- **OP_BIT_OR** = **17** --- Bitwise OR operator (``|``). +.. _class_@GlobalScope_method_round: -- **OP_BIT_XOR** = **18** --- Bitwise XOR operator (``^``). +.. rst-class:: classref-method -- **OP_BIT_NEGATE** = **19** --- Bitwise NOT operator (``~``). +:ref:`Variant` **round**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` -- **OP_AND** = **20** --- Logical AND operator (``and`` or ``&&``). +Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. -- **OP_OR** = **21** --- Logical OR operator (``or`` or ``||``). +:: -- **OP_XOR** = **22** --- Logical XOR operator (not implemented in GDScript). + round(2.4) # Returns 2 + round(2.5) # Returns 3 + round(2.6) # Returns 3 -- **OP_NOT** = **23** --- Logical NOT operator (``not`` or ``!``). +See also :ref:`floor()`, :ref:`ceil()`, and :ref:`snapped()`. -- **OP_IN** = **24** --- Logical IN operator (``in``). +\ **Note:** For better type safety, use :ref:`roundf()`, :ref:`roundi()`, :ref:`Vector2.round()`, :ref:`Vector3.round()`, or :ref:`Vector4.round()`. -- **OP_MAX** = **25** --- Represents the size of the :ref:`Variant.Operator` enum. +.. rst-class:: classref-item-separator -Constants ---------- +---- -.. _class_@GlobalScope_constant_SPKEY: +.. _class_@GlobalScope_method_roundf: -- **SPKEY** = **16777216** --- Keycodes with this bit applied are non-printable. +.. rst-class:: classref-method -Property Descriptions ---------------------- +:ref:`float` **roundf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` -.. _class_@GlobalScope_property_ARVRServer: +Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0. -- :ref:`ARVRServer` **ARVRServer** +A type-safe version of :ref:`round()`, returning a :ref:`float`. -The :ref:`ARVRServer` singleton. +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_AudioServer: +.. _class_@GlobalScope_method_roundi: -- :ref:`AudioServer` **AudioServer** +.. rst-class:: classref-method -The :ref:`AudioServer` singleton. +:ref:`int` **roundi**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0. + +A type-safe version of :ref:`round()`, returning an :ref:`int`. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_CameraServer: +.. _class_@GlobalScope_method_seed: -- :ref:`CameraServer` **CameraServer** +.. rst-class:: classref-method -The :ref:`CameraServer` singleton. +|void| **seed**\ (\ base\: :ref:`int`\ ) :ref:`🔗` + +Sets the seed for the random number generator to ``base``. Setting the seed manually can ensure consistent, repeatable results for most random functions. + + +.. tabs:: + + .. code-tab:: gdscript + + var my_seed = "Godot Rocks".hash() + seed(my_seed) + var a = randf() + randi() + seed(my_seed) + var b = randf() + randi() + # a and b are now identical + + .. code-tab:: csharp + + ulong mySeed = (ulong)GD.Hash("Godot Rocks"); + GD.Seed(mySeed); + var a = GD.Randf() + GD.Randi(); + GD.Seed(mySeed); + var b = GD.Randf() + GD.Randi(); + // a and b are now identical + + + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_ClassDB: +.. _class_@GlobalScope_method_sign: -- :ref:`ClassDB` **ClassDB** +.. rst-class:: classref-method -The :ref:`ClassDB` singleton. +:ref:`Variant` **sign**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` + +Returns the same type of :ref:`Variant` as ``x``, with ``-1`` for negative values, ``1`` for positive values, and ``0`` for zeros. For ``nan`` values it returns 0. + +Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. + +:: + + sign(-6.0) # Returns -1 + sign(0.0) # Returns 0 + sign(6.0) # Returns 1 + sign(NAN) # Returns 0 + + sign(Vector3(-6.0, 0.0, 6.0)) # Returns (-1, 0, 1) + +\ **Note:** For better type safety, use :ref:`signf()`, :ref:`signi()`, :ref:`Vector2.sign()`, :ref:`Vector2i.sign()`, :ref:`Vector3.sign()`, :ref:`Vector3i.sign()`, :ref:`Vector4.sign()`, or :ref:`Vector4i.sign()`. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_Engine: +.. _class_@GlobalScope_method_signf: -- :ref:`Engine` **Engine** +.. rst-class:: classref-method -The :ref:`Engine` singleton. +:ref:`float` **signf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns ``-1.0`` if ``x`` is negative, ``1.0`` if ``x`` is positive, and ``0.0`` if ``x`` is zero. For ``nan`` values of ``x`` it returns 0.0. + +:: + + signf(-6.5) # Returns -1.0 + signf(0.0) # Returns 0.0 + signf(6.5) # Returns 1.0 + signf(NAN) # Returns 0.0 + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_Geometry: +.. _class_@GlobalScope_method_signi: + +.. rst-class:: classref-method + +:ref:`int` **signi**\ (\ x\: :ref:`int`\ ) :ref:`🔗` + +Returns ``-1`` if ``x`` is negative, ``1`` if ``x`` is positive, and ``0`` if ``x`` is zero. -- :ref:`Geometry` **Geometry** +:: + + signi(-6) # Returns -1 + signi(0) # Returns 0 + signi(6) # Returns 1 -The :ref:`Geometry` singleton. +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_GodotSharp: +.. _class_@GlobalScope_method_sin: + +.. rst-class:: classref-method + +:ref:`float` **sin**\ (\ angle_rad\: :ref:`float`\ ) :ref:`🔗` -- :ref:`GodotSharp` **GodotSharp** +Returns the sine of angle ``angle_rad`` in radians. -The :ref:`GodotSharp` singleton. Only available when using Godot's Mono build. +:: + + sin(0.523599) # Returns 0.5 + sin(deg_to_rad(90)) # Returns 1.0 + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_IP: +.. _class_@GlobalScope_method_sinh: -- :ref:`IP` **IP** +.. rst-class:: classref-method -The :ref:`IP` singleton. +:ref:`float` **sinh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the hyperbolic sine of ``x``. + +:: + + var a = log(2.0) # Returns 0.693147 + sinh(a) # Returns 0.75 + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_Input: +.. _class_@GlobalScope_method_smoothstep: -- :ref:`Input` **Input** +.. rst-class:: classref-method -The :ref:`Input` singleton. +:ref:`float` **smoothstep**\ (\ from\: :ref:`float`, to\: :ref:`float`, x\: :ref:`float`\ ) :ref:`🔗` + +Returns a smooth cubic Hermite interpolation between ``0`` and ``1``. + +For positive ranges (when ``from <= to``) the return value is ``0`` when ``x <= from``, and ``1`` when ``x >= to``. If ``x`` lies between ``from`` and ``to``, the return value follows an S-shaped curve that smoothly transitions from ``0`` to ``1``. + +For negative ranges (when ``from > to``) the function is mirrored and returns ``1`` when ``x <= to`` and ``0`` when ``x >= from``. + +This S-shaped curve is the cubic Hermite interpolator, given by ``f(y) = 3*y^2 - 2*y^3`` where ``y = (x-from) / (to-from)``. + +:: + + smoothstep(0, 2, -5.0) # Returns 0.0 + smoothstep(0, 2, 0.5) # Returns 0.15625 + smoothstep(0, 2, 1.0) # Returns 0.5 + smoothstep(0, 2, 2.0) # Returns 1.0 + +Compared to :ref:`ease()` with a curve value of ``-1.6521``, :ref:`smoothstep()` returns the smoothest possible curve with no sudden changes in the derivative. If you need to perform more advanced transitions, use :ref:`Tween` or :ref:`AnimationPlayer`. + +\ `Comparison between smoothstep() and ease(x, -1.6521) return values `__\ + +\ `Smoothstep() return values with positive, zero, and negative ranges `__ + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_InputMap: +.. _class_@GlobalScope_method_snapped: -- :ref:`InputMap` **InputMap** +.. rst-class:: classref-method -The :ref:`InputMap` singleton. +:ref:`Variant` **snapped**\ (\ x\: :ref:`Variant`, step\: :ref:`Variant`\ ) :ref:`🔗` + +Returns the multiple of ``step`` that is the closest to ``x``. This can also be used to round a floating-point number to an arbitrary number of decimals. + +The returned value is the same type of :ref:`Variant` as ``step``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. + +:: + + snapped(100, 32) # Returns 96 + snapped(3.14159, 0.01) # Returns 3.14 + + snapped(Vector2(34, 70), Vector2(8, 8)) # Returns (32, 72) + +See also :ref:`ceil()`, :ref:`floor()`, and :ref:`round()`. + +\ **Note:** For better type safety, use :ref:`snappedf()`, :ref:`snappedi()`, :ref:`Vector2.snapped()`, :ref:`Vector2i.snapped()`, :ref:`Vector3.snapped()`, :ref:`Vector3i.snapped()`, :ref:`Vector4.snapped()`, or :ref:`Vector4i.snapped()`. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_JSON: +.. _class_@GlobalScope_method_snappedf: + +.. rst-class:: classref-method + +:ref:`float` **snappedf**\ (\ x\: :ref:`float`, step\: :ref:`float`\ ) :ref:`🔗` -- :ref:`JSON` **JSON** +Returns the multiple of ``step`` that is the closest to ``x``. This can also be used to round a floating-point number to an arbitrary number of decimals. -The :ref:`JSON` singleton. +A type-safe version of :ref:`snapped()`, returning a :ref:`float`. + +:: + + snappedf(32.0, 2.5) # Returns 32.5 + snappedf(3.14159, 0.01) # Returns 3.14 + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_JavaClassWrapper: +.. _class_@GlobalScope_method_snappedi: -- :ref:`JavaClassWrapper` **JavaClassWrapper** +.. rst-class:: classref-method -The :ref:`JavaClassWrapper` singleton. +:ref:`int` **snappedi**\ (\ x\: :ref:`float`, step\: :ref:`int`\ ) :ref:`🔗` + +Returns the multiple of ``step`` that is the closest to ``x``. + +A type-safe version of :ref:`snapped()`, returning an :ref:`int`. -**Note:** Only implemented on Android. +:: + + snappedi(53, 16) # Returns 48 + snappedi(4096, 100) # Returns 4100 + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_JavaScript: +.. _class_@GlobalScope_method_sqrt: + +.. rst-class:: classref-method + +:ref:`float` **sqrt**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the square root of ``x``, where ``x`` is a non-negative number. + +:: -- :ref:`JavaScript` **JavaScript** + sqrt(9) # Returns 3 + sqrt(10.24) # Returns 3.2 + sqrt(-1) # Returns NaN -The :ref:`JavaScript` singleton. +\ **Note:** Negative values of ``x`` return NaN ("Not a Number"). In C#, if you need negative inputs, use ``System.Numerics.Complex``. -**Note:** Only implemented on HTML5. +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_Marshalls: +.. _class_@GlobalScope_method_step_decimals: -- :ref:`Marshalls` **Marshalls** +.. rst-class:: classref-method -The :ref:`Marshalls` singleton. +:ref:`int` **step_decimals**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the position of the first non-zero digit, after the decimal point. Note that the maximum return value is 10, which is a design decision in the implementation. + +:: + + var n = step_decimals(5) # n is 0 + n = step_decimals(1.0005) # n is 4 + n = step_decimals(0.000000005) # n is 9 + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_Navigation2DServer: +.. _class_@GlobalScope_method_str: + +.. rst-class:: classref-method -- :ref:`Navigation2DServer` **Navigation2DServer** +:ref:`String` **str**\ (\ ...\ ) |vararg| :ref:`🔗` -The :ref:`Navigation2DServer` singleton. +Converts one or more arguments of any :ref:`Variant` type to a :ref:`String` in the best way possible. + +:: + + var a = [10, 20, 30] + var b = str(a) + print(len(a)) # Prints 3 (the number of elements in the array). + print(len(b)) # Prints 12 (the length of the string "[10, 20, 30]"). + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_NavigationMeshGenerator: +.. _class_@GlobalScope_method_str_to_var: -- :ref:`NavigationMeshGenerator` **NavigationMeshGenerator** +.. rst-class:: classref-method -The :ref:`NavigationMeshGenerator` singleton. +:ref:`Variant` **str_to_var**\ (\ string\: :ref:`String`\ ) :ref:`🔗` + +Converts a formatted ``string`` that was returned by :ref:`var_to_str()` to the original :ref:`Variant`. + + +.. tabs:: + + .. code-tab:: gdscript + + var data = '{ "a": 1, "b": 2 }' # data is a String + var dict = str_to_var(data) # dict is a Dictionary + print(dict["a"]) # Prints 1 + + .. code-tab:: csharp + + string data = "{ \"a\": 1, \"b\": 2 }"; // data is a string + var dict = GD.StrToVar(data).AsGodotDictionary(); // dict is a Dictionary + GD.Print(dict["a"]); // Prints 1 + + + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_NavigationServer: +.. _class_@GlobalScope_method_tan: -- :ref:`NavigationServer` **NavigationServer** +.. rst-class:: classref-method -The :ref:`NavigationServer` singleton. +:ref:`float` **tan**\ (\ angle_rad\: :ref:`float`\ ) :ref:`🔗` + +Returns the tangent of angle ``angle_rad`` in radians. + +:: + + tan(deg_to_rad(45)) # Returns 1 + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_OS: +.. _class_@GlobalScope_method_tanh: -- :ref:`OS` **OS** +.. rst-class:: classref-method -The :ref:`OS` singleton. +:ref:`float` **tanh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` + +Returns the hyperbolic tangent of ``x``. + +:: + + var a = log(2.0) # Returns 0.693147 + tanh(a) # Returns 0.6 + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_Performance: +.. _class_@GlobalScope_method_type_convert: -- :ref:`Performance` **Performance** +.. rst-class:: classref-method -The :ref:`Performance` singleton. +:ref:`Variant` **type_convert**\ (\ variant\: :ref:`Variant`, type\: :ref:`int`\ ) :ref:`🔗` + +Converts the given ``variant`` to the given ``type``, using the :ref:`Variant.Type` values. This method is generous with how it handles types, it can automatically convert between array types, convert numeric :ref:`String`\ s to :ref:`int`, and converting most things to :ref:`String`. + +If the type conversion cannot be done, this method will return the default value for that type, for example converting :ref:`Rect2` to :ref:`Vector2` will always return :ref:`Vector2.ZERO`. This method will never show error messages as long as ``type`` is a valid Variant type. + +The returned value is a :ref:`Variant`, but the data inside and its type will be the same as the requested type. + +:: + + type_convert("Hi!", TYPE_INT) # Returns 0 + type_convert("123", TYPE_INT) # Returns 123 + type_convert(123.4, TYPE_INT) # Returns 123 + type_convert(5, TYPE_VECTOR2) # Returns (0, 0) + type_convert("Hi!", TYPE_NIL) # Returns null + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GlobalScope_method_type_string: + +.. rst-class:: classref-method + +:ref:`String` **type_string**\ (\ type\: :ref:`int`\ ) :ref:`🔗` + +Returns a human-readable name of the given ``type``, using the :ref:`Variant.Type` values. + +:: + + print(TYPE_INT) # Prints 2 + print(type_string(TYPE_INT)) # Prints "int" + print(type_string(TYPE_STRING)) # Prints "String" + +See also :ref:`typeof()`. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_Physics2DServer: +.. _class_@GlobalScope_method_typeof: -- :ref:`Physics2DServer` **Physics2DServer** +.. rst-class:: classref-method -The :ref:`Physics2DServer` singleton. +:ref:`int` **typeof**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` + +Returns the internal type of the given ``variable``, using the :ref:`Variant.Type` values. + +:: + + var json = JSON.new() + json.parse('["a", "b", "c"]') + var result = json.get_data() + if result is Array: + print(result[0]) # Prints "a" + else: + print("Unexpected result!") + +See also :ref:`type_string()`. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_PhysicsServer: +.. _class_@GlobalScope_method_var_to_bytes: + +.. rst-class:: classref-method + +:ref:`PackedByteArray` **var_to_bytes**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` -- :ref:`PhysicsServer` **PhysicsServer** +Encodes a :ref:`Variant` value to a byte array, without encoding objects. Deserialization can be done with :ref:`bytes_to_var()`. -The :ref:`PhysicsServer` singleton. +\ **Note:** If you need object serialization, see :ref:`var_to_bytes_with_objects()`. + +\ **Note:** Encoding :ref:`Callable` is not supported and will result in an empty value, regardless of the data. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_ProjectSettings: +.. _class_@GlobalScope_method_var_to_bytes_with_objects: -- :ref:`ProjectSettings` **ProjectSettings** +.. rst-class:: classref-method -The :ref:`ProjectSettings` singleton. +:ref:`PackedByteArray` **var_to_bytes_with_objects**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` + +Encodes a :ref:`Variant` value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with :ref:`bytes_to_var_with_objects()`. + +\ **Note:** Encoding :ref:`Callable` is not supported and will result in an empty value, regardless of the data. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_ResourceLoader: +.. _class_@GlobalScope_method_var_to_str: -- :ref:`ResourceLoader` **ResourceLoader** +.. rst-class:: classref-method -The :ref:`ResourceLoader` singleton. +:ref:`String` **var_to_str**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` + +Converts a :ref:`Variant` ``variable`` to a formatted :ref:`String` that can then be parsed using :ref:`str_to_var()`. + + +.. tabs:: + + .. code-tab:: gdscript + + var a = { "a": 1, "b": 2 } + print(var_to_str(a)) + + .. code-tab:: csharp + + var a = new Godot.Collections.Dictionary { ["a"] = 1, ["b"] = 2 }; + GD.Print(GD.VarToStr(a)); + + + +Prints: + +.. code:: text + + { + "a": 1, + "b": 2 + } + +\ **Note:** Converting :ref:`Signal` or :ref:`Callable` is not supported and will result in an empty value for these types, regardless of their data. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_ResourceSaver: +.. _class_@GlobalScope_method_weakref: -- :ref:`ResourceSaver` **ResourceSaver** +.. rst-class:: classref-method -The :ref:`ResourceSaver` singleton. +:ref:`Variant` **weakref**\ (\ obj\: :ref:`Variant`\ ) :ref:`🔗` + +Returns a :ref:`WeakRef` instance holding a weak reference to ``obj``. Returns an empty :ref:`WeakRef` instance if ``obj`` is ``null``. Prints an error and returns ``null`` if ``obj`` is neither :ref:`Object`-derived nor ``null``. + +A weak reference to an object is not enough to keep the object alive: when the only remaining references to a referent are weak references, garbage collection is free to destroy the referent and reuse its memory for something else. However, until the object is actually destroyed the weak reference may return the object even if there are no strong references to it. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_TranslationServer: +.. _class_@GlobalScope_method_wrap: -- :ref:`TranslationServer` **TranslationServer** +.. rst-class:: classref-method -The :ref:`TranslationServer` singleton. +:ref:`Variant` **wrap**\ (\ value\: :ref:`Variant`, min\: :ref:`Variant`, max\: :ref:`Variant`\ ) :ref:`🔗` + +Wraps the :ref:`Variant` ``value`` between ``min`` and ``max``. ``min`` is *inclusive* while ``max`` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. + +Variant types :ref:`int` and :ref:`float` are supported. If any of the arguments is :ref:`float`, this function returns a :ref:`float`, otherwise it returns an :ref:`int`. + +:: + + var a = wrap(4, 5, 10) + # a is 9 (int) + + var a = wrap(7, 5, 10) + # a is 7 (int) + + var a = wrap(10.5, 5, 10) + # a is 5.5 (float) + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_VisualScriptEditor: +.. _class_@GlobalScope_method_wrapf: + +.. rst-class:: classref-method + +:ref:`float` **wrapf**\ (\ value\: :ref:`float`, min\: :ref:`float`, max\: :ref:`float`\ ) :ref:`🔗` -- :ref:`VisualScriptEditor` **VisualScriptEditor** +Wraps the float ``value`` between ``min`` and ``max``. ``min`` is *inclusive* while ``max`` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. -The :ref:`VisualScriptEditor` singleton. +:: + + # Infinite loop between 5.0 and 9.9 + value = wrapf(value + 0.1, 5.0, 10.0) + +:: + + # Infinite rotation (in radians) + angle = wrapf(angle + 0.1, 0.0, TAU) + +:: + + # Infinite rotation (in radians) + angle = wrapf(angle + 0.1, -PI, PI) + +\ **Note:** If ``min`` is ``0``, this is equivalent to :ref:`fposmod()`, so prefer using that instead. :ref:`wrapf()` is more flexible than using the :ref:`fposmod()` approach by giving the user control over the minimum value. + +.. rst-class:: classref-item-separator ---- -.. _class_@GlobalScope_property_VisualServer: +.. _class_@GlobalScope_method_wrapi: + +.. rst-class:: classref-method + +:ref:`int` **wrapi**\ (\ value\: :ref:`int`, min\: :ref:`int`, max\: :ref:`int`\ ) :ref:`🔗` -- :ref:`VisualServer` **VisualServer** +Wraps the integer ``value`` between ``min`` and ``max``. ``min`` is *inclusive* while ``max`` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. -The :ref:`VisualServer` singleton. +:: + + # Infinite loop between 5 and 9 + frame = wrapi(frame + 1, 5, 10) + +:: + # result is -2 + var result = wrapi(-6, -5, -1) + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_@nativescript.rst b/classes/class_@nativescript.rst deleted file mode 100644 index aa731484b4e..00000000000 --- a/classes/class_@nativescript.rst +++ /dev/null @@ -1,13 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the @NativeScript.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_@NativeScript: - -@NativeScript -============= - - - diff --git a/classes/class_@visualscript.rst b/classes/class_@visualscript.rst deleted file mode 100644 index 323db2046a9..00000000000 --- a/classes/class_@visualscript.rst +++ /dev/null @@ -1,18 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the @VisualScript.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_@VisualScript: - -@VisualScript -============= - -Built-in visual script functions. - -Description ------------ - -A list of built-in visual script functions, see :ref:`VisualScriptBuiltinFunc` and :ref:`VisualScript`. - diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst index 177bb571b90..e07be295a85 100644 --- a/classes/class_aabb.rst +++ b/classes/class_aabb.rst @@ -1,297 +1,778 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AABB.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AABB.xml. .. _class_AABB: AABB ==== -Axis-Aligned Bounding Box. +A 3D axis-aligned bounding box. + +.. rst-class:: classref-introduction-group Description ----------- -AABB consists of a position, a size, and several utility functions. It is typically used for fast overlap tests. +The **AABB** built-in :ref:`Variant` type represents an axis-aligned bounding box in a 3D space. It is defined by its :ref:`position` and :ref:`size`, which are :ref:`Vector3`. It is frequently used for fast overlap tests (see :ref:`intersects()`). Although **AABB** itself is axis-aligned, it can be combined with :ref:`Transform3D` to represent a rotated or skewed bounding box. + +It uses floating-point coordinates. The 2D counterpart to **AABB** is :ref:`Rect2`. There is no version of **AABB** that uses integer coordinates. + +\ **Note:** Negative values for :ref:`size` are not supported. With negative size, most **AABB** methods do not work correctly. Use :ref:`abs()` to get an equivalent **AABB** with a non-negative size. + +\ **Note:** In a boolean context, an **AABB** evaluates to ``false`` if both :ref:`position` and :ref:`size` are zero (equal to :ref:`Vector3.ZERO`). Otherwise, it always evaluates to ``true``. + +.. note:: + + There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/math/index` +- :doc:`Math documentation index <../tutorials/math/index>` + +- :doc:`Vector math <../tutorials/math/vector_math>` + +- :doc:`Advanced vector math <../tutorials/math/vectors_advanced>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------------+-----------------------------------------------+------------------------+ -| :ref:`Vector3` | :ref:`end` | ``Vector3( 0, 0, 0 )`` | -+-------------------------------+-----------------------------------------------+------------------------+ -| :ref:`Vector3` | :ref:`position` | ``Vector3( 0, 0, 0 )`` | -+-------------------------------+-----------------------------------------------+------------------------+ -| :ref:`Vector3` | :ref:`size` | ``Vector3( 0, 0, 0 )`` | -+-------------------------------+-----------------------------------------------+------------------------+ +.. table:: + :widths: auto + + +-------------------------------+-----------------------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`end` | ``Vector3(0, 0, 0)`` | + +-------------------------------+-----------------------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`position` | ``Vector3(0, 0, 0)`` | + +-------------------------------+-----------------------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`size` | ``Vector3(0, 0, 0)`` | + +-------------------------------+-----------------------------------------------+----------------------+ + +.. rst-class:: classref-reftable-group + +Constructors +------------ + +.. table:: + :widths: auto + + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`AABB`\ (\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`AABB`\ (\ from\: :ref:`AABB`\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`AABB`\ (\ position\: :ref:`Vector3`, size\: :ref:`Vector3`\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AABB` | :ref:`AABB` **(** :ref:`Vector3` position, :ref:`Vector3` size **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`encloses` **(** :ref:`AABB` with **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AABB` | :ref:`expand` **(** :ref:`Vector3` to_point **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_area` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_endpoint` **(** :ref:`int` idx **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_longest_axis` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_longest_axis_index` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_longest_axis_size` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_shortest_axis` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_shortest_axis_index` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_shortest_axis_size` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_support` **(** :ref:`Vector3` dir **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AABB` | :ref:`grow` **(** :ref:`float` by **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_no_area` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_no_surface` **(** **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_point` **(** :ref:`Vector3` point **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AABB` | :ref:`intersection` **(** :ref:`AABB` with **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`intersects` **(** :ref:`AABB` with **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`intersects_plane` **(** :ref:`Plane` plane **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`intersects_segment` **(** :ref:`Vector3` from, :ref:`Vector3` to **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_equal_approx` **(** :ref:`AABB` aabb **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AABB` | :ref:`merge` **(** :ref:`AABB` with **)** | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`abs`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`encloses`\ (\ with\: :ref:`AABB`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`expand`\ (\ to_point\: :ref:`Vector3`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_center`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_endpoint`\ (\ idx\: :ref:`int`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_longest_axis`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_longest_axis_index`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_longest_axis_size`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_shortest_axis`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_shortest_axis_index`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_shortest_axis_size`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_support`\ (\ direction\: :ref:`Vector3`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_volume`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`grow`\ (\ by\: :ref:`float`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_point`\ (\ point\: :ref:`Vector3`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_surface`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_volume`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`intersection`\ (\ with\: :ref:`AABB`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`intersects`\ (\ with\: :ref:`AABB`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`intersects_plane`\ (\ plane\: :ref:`Plane`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`intersects_ray`\ (\ from\: :ref:`Vector3`, dir\: :ref:`Vector3`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`intersects_segment`\ (\ from\: :ref:`Vector3`, to\: :ref:`Vector3`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_equal_approx`\ (\ aabb\: :ref:`AABB`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_finite`\ (\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`merge`\ (\ with\: :ref:`AABB`\ ) |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Operators +--------- + +.. table:: + :widths: auto + + +-------------------------+-------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator !=`\ (\ right\: :ref:`AABB`\ ) | + +-------------------------+-------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`operator *`\ (\ right\: :ref:`Transform3D`\ ) | + +-------------------------+-------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator ==`\ (\ right\: :ref:`AABB`\ ) | + +-------------------------+-------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AABB_property_end: -- :ref:`Vector3` **end** +.. rst-class:: classref-property + +:ref:`Vector3` **end** = ``Vector3(0, 0, 0)`` :ref:`🔗` -+-----------+------------------------+ -| *Default* | ``Vector3( 0, 0, 0 )`` | -+-----------+------------------------+ +The ending point. This is usually the corner on the top-right and back of the bounding box, and is equivalent to ``position + size``. Setting this point affects the :ref:`size`. -Ending corner. This is calculated as ``position + size``. Changing this property changes :ref:`size` accordingly. +.. rst-class:: classref-item-separator ---- .. _class_AABB_property_position: -- :ref:`Vector3` **position** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``Vector3( 0, 0, 0 )`` | -+-----------+------------------------+ +:ref:`Vector3` **position** = ``Vector3(0, 0, 0)`` :ref:`🔗` -Beginning corner. +The origin point. This is usually the corner on the bottom-left and forward of the bounding box. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_property_size: -- :ref:`Vector3` **size** +.. rst-class:: classref-property + +:ref:`Vector3` **size** = ``Vector3(0, 0, 0)`` :ref:`🔗` -+-----------+------------------------+ -| *Default* | ``Vector3( 0, 0, 0 )`` | -+-----------+------------------------+ +The bounding box's width, height, and depth starting from :ref:`position`. Setting this value also affects the :ref:`end` point. -Size from position to end. +\ **Note:** It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the :ref:`position` is the bottom-left-forward corner, and the :ref:`end` is the top-right-back corner. To get an equivalent bounding box with non-negative size, use :ref:`abs()`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constructor Descriptions +------------------------ + +.. _class_AABB_constructor_AABB: + +.. rst-class:: classref-constructor + +:ref:`AABB` **AABB**\ (\ ) :ref:`🔗` + +Constructs an **AABB** with its :ref:`position` and :ref:`size` set to :ref:`Vector3.ZERO`. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`AABB` **AABB**\ (\ from\: :ref:`AABB`\ ) + +Constructs an **AABB** as a copy of the given **AABB**. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`AABB` **AABB**\ (\ position\: :ref:`Vector3`, size\: :ref:`Vector3`\ ) + +Constructs an **AABB** by ``position`` and ``size``. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_AABB_method_AABB: +.. _class_AABB_method_abs: + +.. rst-class:: classref-method + +:ref:`AABB` **abs**\ (\ ) |const| :ref:`🔗` + +Returns an **AABB** equivalent to this bounding box, with its width, height, and depth modified to be non-negative values. + + +.. tabs:: + + .. code-tab:: gdscript -- :ref:`AABB` **AABB** **(** :ref:`Vector3` position, :ref:`Vector3` size **)** + var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5)) + var absolute = box.abs() + print(absolute.position) # Prints (-15.0, -10.0, 0.0) + print(absolute.size) # Prints (20.0, 10.0, 5.0) -Optional constructor, accepts position and size. + .. code-tab:: csharp + + var box = new Aabb(new Vector3(5, 0, 5), new Vector3(-20, -10, -5)); + var absolute = box.Abs(); + GD.Print(absolute.Position); // Prints (-15, -10, 0) + GD.Print(absolute.Size); // Prints (20, 10, 5) + + + +\ **Note:** It's recommended to use this method when :ref:`size` is negative, as most other methods in Godot assume that the :ref:`size`'s components are greater than ``0``. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_encloses: -- :ref:`bool` **encloses** **(** :ref:`AABB` with **)** +.. rst-class:: classref-method + +:ref:`bool` **encloses**\ (\ with\: :ref:`AABB`\ ) |const| :ref:`🔗` + +Returns ``true`` if this bounding box *completely* encloses the ``with`` box. The edges of both boxes are included. + + +.. tabs:: + + .. code-tab:: gdscript + + var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4)) + var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3)) + var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8)) + + print(a.encloses(a)) # Prints true + print(a.encloses(b)) # Prints true + print(a.encloses(c)) # Prints false + + .. code-tab:: csharp + + var a = new Aabb(new Vector3(0, 0, 0), new Vector3(4, 4, 4)); + var b = new Aabb(new Vector3(1, 1, 1), new Vector3(3, 3, 3)); + var c = new Aabb(new Vector3(2, 2, 2), new Vector3(8, 8, 8)); -Returns ``true`` if this ``AABB`` completely encloses another one. + GD.Print(a.Encloses(a)); // Prints True + GD.Print(a.Encloses(b)); // Prints True + GD.Print(a.Encloses(c)); // Prints False + + + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_expand: -- :ref:`AABB` **expand** **(** :ref:`Vector3` to_point **)** +.. rst-class:: classref-method + +:ref:`AABB` **expand**\ (\ to_point\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns a copy of this bounding box expanded to align the edges with the given ``to_point``, if necessary. + + +.. tabs:: + + .. code-tab:: gdscript + + var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5)) + + box = box.expand(Vector3(10, 0, 0)) + print(box.position) # Prints (0.0, 0.0, 0.0) + print(box.size) # Prints (10.0, 2.0, 5.0) + + box = box.expand(Vector3(-5, 0, 5)) + print(box.position) # Prints (-5.0, 0.0, 0.0) + print(box.size) # Prints (15.0, 2.0, 5.0) + + .. code-tab:: csharp + + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 5)); + + box = box.Expand(new Vector3(10, 0, 0)); + GD.Print(box.Position); // Prints (0, 0, 0) + GD.Print(box.Size); // Prints (10, 2, 5) -Returns this ``AABB`` expanded to include a given point. + box = box.Expand(new Vector3(-5, 0, 5)); + GD.Print(box.Position); // Prints (-5, 0, 0) + GD.Print(box.Size); // Prints (15, 2, 5) + + + +.. rst-class:: classref-item-separator ---- -.. _class_AABB_method_get_area: +.. _class_AABB_method_get_center: + +.. rst-class:: classref-method -- :ref:`float` **get_area** **(** **)** +:ref:`Vector3` **get_center**\ (\ ) |const| :ref:`🔗` -Returns the volume of the ``AABB``. +Returns the center point of the bounding box. This is the same as ``position + (size / 2.0)``. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_get_endpoint: -- :ref:`Vector3` **get_endpoint** **(** :ref:`int` idx **)** +.. rst-class:: classref-method + +:ref:`Vector3` **get_endpoint**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the position of one of the 8 vertices that compose this bounding box. With an ``idx`` of ``0`` this is the same as :ref:`position`, and an ``idx`` of ``7`` is the same as :ref:`end`. -Gets the position of the 8 endpoints of the ``AABB`` in space. +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_get_longest_axis: -- :ref:`Vector3` **get_longest_axis** **(** **)** +.. rst-class:: classref-method + +:ref:`Vector3` **get_longest_axis**\ (\ ) |const| :ref:`🔗` + +Returns the longest normalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`). + + +.. tabs:: + + .. code-tab:: gdscript + + var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8)) + + print(box.get_longest_axis()) # Prints (0.0, 0.0, 1.0) + print(box.get_longest_axis_index()) # Prints 2 + print(box.get_longest_axis_size()) # Prints 8.0 -Returns the normalized longest axis of the ``AABB``. + .. code-tab:: csharp + + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8)); + + GD.Print(box.GetLongestAxis()); // Prints (0, 0, 1) + GD.Print(box.GetLongestAxisIndex()); // Prints Z + GD.Print(box.GetLongestAxisSize()); // Prints 8 + + + +See also :ref:`get_longest_axis_index()` and :ref:`get_longest_axis_size()`. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_get_longest_axis_index: -- :ref:`int` **get_longest_axis_index** **(** **)** +.. rst-class:: classref-method + +:ref:`int` **get_longest_axis_index**\ (\ ) |const| :ref:`🔗` -Returns the index of the longest axis of the ``AABB`` (according to :ref:`Vector3`'s ``AXIS_*`` constants). +Returns the index to the longest axis of this bounding box's :ref:`size` (see :ref:`Vector3.AXIS_X`, :ref:`Vector3.AXIS_Y`, and :ref:`Vector3.AXIS_Z`). + +For an example, see :ref:`get_longest_axis()`. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_get_longest_axis_size: -- :ref:`float` **get_longest_axis_size** **(** **)** +.. rst-class:: classref-method + +:ref:`float` **get_longest_axis_size**\ (\ ) |const| :ref:`🔗` + +Returns the longest dimension of this bounding box's :ref:`size`. -Returns the scalar length of the longest axis of the ``AABB``. +For an example, see :ref:`get_longest_axis()`. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_get_shortest_axis: -- :ref:`Vector3` **get_shortest_axis** **(** **)** +.. rst-class:: classref-method + +:ref:`Vector3` **get_shortest_axis**\ (\ ) |const| :ref:`🔗` + +Returns the shortest normalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`). -Returns the normalized shortest axis of the ``AABB``. + +.. tabs:: + + .. code-tab:: gdscript + + var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8)) + + print(box.get_shortest_axis()) # Prints (1.0, 0.0, 0.0) + print(box.get_shortest_axis_index()) # Prints 0 + print(box.get_shortest_axis_size()) # Prints 2.0 + + .. code-tab:: csharp + + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8)); + + GD.Print(box.GetShortestAxis()); // Prints (1, 0, 0) + GD.Print(box.GetShortestAxisIndex()); // Prints X + GD.Print(box.GetShortestAxisSize()); // Prints 2 + + + +See also :ref:`get_shortest_axis_index()` and :ref:`get_shortest_axis_size()`. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_get_shortest_axis_index: -- :ref:`int` **get_shortest_axis_index** **(** **)** +.. rst-class:: classref-method + +:ref:`int` **get_shortest_axis_index**\ (\ ) |const| :ref:`🔗` -Returns the index of the shortest axis of the ``AABB`` (according to :ref:`Vector3`::AXIS\* enum). +Returns the index to the shortest axis of this bounding box's :ref:`size` (see :ref:`Vector3.AXIS_X`, :ref:`Vector3.AXIS_Y`, and :ref:`Vector3.AXIS_Z`). + +For an example, see :ref:`get_shortest_axis()`. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_get_shortest_axis_size: -- :ref:`float` **get_shortest_axis_size** **(** **)** +.. rst-class:: classref-method + +:ref:`float` **get_shortest_axis_size**\ (\ ) |const| :ref:`🔗` -Returns the scalar length of the shortest axis of the ``AABB``. +Returns the shortest dimension of this bounding box's :ref:`size`. + +For an example, see :ref:`get_shortest_axis()`. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_get_support: -- :ref:`Vector3` **get_support** **(** :ref:`Vector3` dir **)** +.. rst-class:: classref-method + +:ref:`Vector3` **get_support**\ (\ direction\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns the vertex's position of this bounding box that's the farthest in the given direction. This point is commonly known as the support point in collision detection algorithms. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AABB_method_get_volume: + +.. rst-class:: classref-method + +:ref:`float` **get_volume**\ (\ ) |const| :ref:`🔗` + +Returns the bounding box's volume. This is equivalent to ``size.x * size.y * size.z``. See also :ref:`has_volume()`. -Returns the support point in a given direction. This is useful for collision detection algorithms. +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_grow: -- :ref:`AABB` **grow** **(** :ref:`float` by **)** +.. rst-class:: classref-method + +:ref:`AABB` **grow**\ (\ by\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns a copy of this bounding box extended on all sides by the given amount ``by``. A negative amount shrinks the box instead. + -Returns a copy of the ``AABB`` grown a given amount of units towards all the sides. +.. tabs:: + + .. code-tab:: gdscript + + var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4) + print(a.position) # Prints (0.0, 0.0, 0.0) + print(a.size) # Prints (16.0, 16.0, 16.0) + + var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2) + print(b.position) # Prints (-2.0, -2.0, -2.0) + print(b.size) # Prints (12.0, 8.0, 6.0) + + .. code-tab:: csharp + + var a = new Aabb(new Vector3(4, 4, 4), new Vector3(8, 8, 8)).Grow(4); + GD.Print(a.Position); // Prints (0, 0, 0) + GD.Print(a.Size); // Prints (16, 16, 16) + + var b = new Aabb(new Vector3(0, 0, 0), new Vector3(8, 4, 2)).Grow(2); + GD.Print(b.Position); // Prints (-2, -2, -2) + GD.Print(b.Size); // Prints (12, 8, 6) + + + +.. rst-class:: classref-item-separator ---- -.. _class_AABB_method_has_no_area: +.. _class_AABB_method_has_point: + +.. rst-class:: classref-method -- :ref:`bool` **has_no_area** **(** **)** +:ref:`bool` **has_point**\ (\ point\: :ref:`Vector3`\ ) |const| :ref:`🔗` -Returns ``true`` if the ``AABB`` is flat or empty. +Returns ``true`` if the bounding box contains the given ``point``. By convention, points exactly on the right, top, and front sides are **not** included. + +\ **Note:** This method is not reliable for **AABB** with a *negative* :ref:`size`. Use :ref:`abs()` first to get a valid bounding box. + +.. rst-class:: classref-item-separator ---- -.. _class_AABB_method_has_no_surface: +.. _class_AABB_method_has_surface: + +.. rst-class:: classref-method -- :ref:`bool` **has_no_surface** **(** **)** +:ref:`bool` **has_surface**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the ``AABB`` is empty. +Returns ``true`` if this bounding box has a surface or a length, that is, at least one component of :ref:`size` is greater than ``0``. Otherwise, returns ``false``. + +.. rst-class:: classref-item-separator ---- -.. _class_AABB_method_has_point: +.. _class_AABB_method_has_volume: + +.. rst-class:: classref-method + +:ref:`bool` **has_volume**\ (\ ) |const| :ref:`🔗` -- :ref:`bool` **has_point** **(** :ref:`Vector3` point **)** +Returns ``true`` if this bounding box's width, height, and depth are all positive. See also :ref:`get_volume()`. -Returns ``true`` if the ``AABB`` contains a point. +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_intersection: -- :ref:`AABB` **intersection** **(** :ref:`AABB` with **)** +.. rst-class:: classref-method + +:ref:`AABB` **intersection**\ (\ with\: :ref:`AABB`\ ) |const| :ref:`🔗` + +Returns the intersection between this bounding box and ``with``. If the boxes do not intersect, returns an empty **AABB**. If the boxes intersect at the edge, returns a flat **AABB** with no volume (see :ref:`has_surface()` and :ref:`has_volume()`). + + +.. tabs:: + + .. code-tab:: gdscript + + var box1 = AABB(Vector3(0, 0, 0), Vector3(5, 2, 8)) + var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4)) + + var intersection = box1.intersection(box2) + print(intersection.position) # Prints (2.0, 0.0, 2.0) + print(intersection.size) # Prints (3.0, 2.0, 4.0) + + .. code-tab:: csharp + + var box1 = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 8)); + var box2 = new Aabb(new Vector3(2, 0, 2), new Vector3(8, 4, 4)); + + var intersection = box1.Intersection(box2); + GD.Print(intersection.Position); // Prints (2, 0, 2) + GD.Print(intersection.Size); // Prints (3, 2, 4) -Returns the intersection between two ``AABB``. An empty AABB (size 0,0,0) is returned on failure. + + +\ **Note:** If you only need to know whether two bounding boxes are intersecting, use :ref:`intersects()`, instead. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_intersects: -- :ref:`bool` **intersects** **(** :ref:`AABB` with **)** +.. rst-class:: classref-method + +:ref:`bool` **intersects**\ (\ with\: :ref:`AABB`\ ) |const| :ref:`🔗` -Returns ``true`` if the ``AABB`` overlaps with another. +Returns ``true`` if this bounding box overlaps with the box ``with``. The edges of both boxes are *always* excluded. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_intersects_plane: -- :ref:`bool` **intersects_plane** **(** :ref:`Plane` plane **)** +.. rst-class:: classref-method + +:ref:`bool` **intersects_plane**\ (\ plane\: :ref:`Plane`\ ) |const| :ref:`🔗` + +Returns ``true`` if this bounding box is on both sides of the given ``plane``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AABB_method_intersects_ray: + +.. rst-class:: classref-method + +:ref:`Variant` **intersects_ray**\ (\ from\: :ref:`Vector3`, dir\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns the first point where this bounding box and the given ray intersect, as a :ref:`Vector3`. If no intersection occurs, returns ``null``. -Returns ``true`` if the ``AABB`` is on both sides of a plane. +The ray begin at ``from``, faces ``dir`` and extends towards infinity. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_intersects_segment: -- :ref:`bool` **intersects_segment** **(** :ref:`Vector3` from, :ref:`Vector3` to **)** +.. rst-class:: classref-method + +:ref:`Variant` **intersects_segment**\ (\ from\: :ref:`Vector3`, to\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns the first point where this bounding box and the given segment intersect, as a :ref:`Vector3`. If no intersection occurs, returns ``null``. + +The segment begins at ``from`` and ends at ``to``. -Returns ``true`` if the ``AABB`` intersects the line segment between ``from`` and ``to``. +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_is_equal_approx: -- :ref:`bool` **is_equal_approx** **(** :ref:`AABB` aabb **)** +.. rst-class:: classref-method + +:ref:`bool` **is_equal_approx**\ (\ aabb\: :ref:`AABB`\ ) |const| :ref:`🔗` + +Returns ``true`` if this bounding box and ``aabb`` are approximately equal, by calling :ref:`Vector3.is_equal_approx()` on the :ref:`position` and the :ref:`size`. + +.. rst-class:: classref-item-separator -Returns ``true`` if this ``AABB`` and ``aabb`` are approximately equal, by calling :ref:`@GDScript.is_equal_approx` on each component. +---- + +.. _class_AABB_method_is_finite: + +.. rst-class:: classref-method + +:ref:`bool` **is_finite**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if this bounding box's values are finite, by calling :ref:`Vector3.is_finite()` on the :ref:`position` and the :ref:`size`. + +.. rst-class:: classref-item-separator ---- .. _class_AABB_method_merge: -- :ref:`AABB` **merge** **(** :ref:`AABB` with **)** +.. rst-class:: classref-method + +:ref:`AABB` **merge**\ (\ with\: :ref:`AABB`\ ) |const| :ref:`🔗` + +Returns an **AABB** that encloses both this bounding box and ``with`` around the edges. See also :ref:`encloses()`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Operator Descriptions +--------------------- + +.. _class_AABB_operator_neq_AABB: + +.. rst-class:: classref-operator + +:ref:`bool` **operator !=**\ (\ right\: :ref:`AABB`\ ) :ref:`🔗` + +Returns ``true`` if the :ref:`position` or :ref:`size` of both bounding boxes are not equal. + +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AABB_operator_mul_Transform3D: + +.. rst-class:: classref-operator + +:ref:`AABB` **operator ***\ (\ right\: :ref:`Transform3D`\ ) :ref:`🔗` + +Inversely transforms (multiplies) the **AABB** by the given :ref:`Transform3D` transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``aabb * transform`` is equivalent to ``transform.inverse() * aabb``. See :ref:`Transform3D.inverse()`. + +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * aabb`` can be used instead. See :ref:`Transform3D.affine_inverse()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AABB_operator_eq_AABB: + +.. rst-class:: classref-operator + +:ref:`bool` **operator ==**\ (\ right\: :ref:`AABB`\ ) :ref:`🔗` + +Returns ``true`` if both :ref:`position` and :ref:`size` of the bounding boxes are exactly equal, respectively. -Returns a larger ``AABB`` that contains both this ``AABB`` and ``with``. +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_acceptdialog.rst b/classes/class_acceptdialog.rst index 7311aa14824..aaaa6294f80 100644 --- a/classes/class_acceptdialog.rst +++ b/classes/class_acceptdialog.rst @@ -1,161 +1,387 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AcceptDialog.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AcceptDialog.xml. .. _class_AcceptDialog: AcceptDialog ============ -**Inherits:** :ref:`WindowDialog` **<** :ref:`Popup` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` +**Inherits:** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` **Inherited By:** :ref:`ConfirmationDialog` -Base dialog for user notification. +A base dialog used for user notification. + +.. rst-class:: classref-introduction-group Description ----------- -This dialog is useful for small notifications to the user about an event. It can only be accepted or closed, with the same result. +The default use of **AcceptDialog** is to allow it to only be accepted or closed, with the same result. However, the :ref:`confirmed` and :ref:`canceled` signals allow to make the two actions different, and the :ref:`add_button()` method allows to add custom buttons and actions. + +\ **Note:** **AcceptDialog** is invisible by default. To make it visible, call one of the ``popup_*`` methods from :ref:`Window` on the node, such as :ref:`Window.popup_centered_clamped()`. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------+-------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`dialog_autowrap` | ``false`` | -+-----------------------------+-------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`dialog_hide_on_ok` | ``true`` | -+-----------------------------+-------------------------------------------------------------------------+---------------------+ -| :ref:`String` | :ref:`dialog_text` | ``""`` | -+-----------------------------+-------------------------------------------------------------------------+---------------------+ -| :ref:`String` | window_title | **O:** ``"Alert!"`` | -+-----------------------------+-------------------------------------------------------------------------+---------------------+ +.. table:: + :widths: auto + + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`dialog_autowrap` | ``false`` | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`dialog_close_on_escape` | ``true`` | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`dialog_hide_on_ok` | ``true`` | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`dialog_text` | ``""`` | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | exclusive | ``true`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | keep_title_visible | ``true`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | maximize_disabled | ``true`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | minimize_disabled | ``true`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`ok_button_text` | ``""`` | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`String` | title | ``"Alert!"`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | transient | ``true`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | visible | ``false`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | wrap_controls | ``true`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Button` | :ref:`add_button` **(** :ref:`String` text, :ref:`bool` right=false, :ref:`String` action="" **)** | -+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Button` | :ref:`add_cancel` **(** :ref:`String` name **)** | -+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Label` | :ref:`get_label` **(** **)** | -+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Button` | :ref:`get_ok` **(** **)** | -+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`register_text_enter` **(** :ref:`Node` line_edit **)** | -+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Button` | :ref:`add_button`\ (\ text\: :ref:`String`, right\: :ref:`bool` = false, action\: :ref:`String` = ""\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Button` | :ref:`add_cancel_button`\ (\ name\: :ref:`String`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Label` | :ref:`get_label`\ (\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Button` | :ref:`get_ok_button`\ (\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`register_text_enter`\ (\ line_edit\: :ref:`LineEdit`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_button`\ (\ button\: :ref:`Button`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Theme Properties +---------------- + +.. table:: + :widths: auto + + +---------------------------------+---------------------------------------------------------------------------------+--------+ + | :ref:`int` | :ref:`buttons_min_height` | ``0`` | + +---------------------------------+---------------------------------------------------------------------------------+--------+ + | :ref:`int` | :ref:`buttons_min_width` | ``0`` | + +---------------------------------+---------------------------------------------------------------------------------+--------+ + | :ref:`int` | :ref:`buttons_separation` | ``10`` | + +---------------------------------+---------------------------------------------------------------------------------+--------+ + | :ref:`StyleBox` | :ref:`panel` | | + +---------------------------------+---------------------------------------------------------------------------------+--------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- +.. _class_AcceptDialog_signal_canceled: + +.. rst-class:: classref-signal + +**canceled**\ (\ ) :ref:`🔗` + +Emitted when the dialog is closed or the button created with :ref:`add_cancel_button()` is pressed. + +.. rst-class:: classref-item-separator + +---- + .. _class_AcceptDialog_signal_confirmed: -- **confirmed** **(** **)** +.. rst-class:: classref-signal + +**confirmed**\ (\ ) :ref:`🔗` Emitted when the dialog is accepted, i.e. the OK button is pressed. +.. rst-class:: classref-item-separator + ---- .. _class_AcceptDialog_signal_custom_action: -- **custom_action** **(** :ref:`StringName` action **)** +.. rst-class:: classref-signal + +**custom_action**\ (\ action\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when a custom button with an action is pressed. See :ref:`add_button()`. + +.. rst-class:: classref-section-separator + +---- -Emitted when a custom button is pressed. See :ref:`add_button`. +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AcceptDialog_property_dialog_autowrap: -- :ref:`bool` **dialog_autowrap** +.. rst-class:: classref-property -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_autowrap(value) | -+-----------+---------------------+ -| *Getter* | has_autowrap() | -+-----------+---------------------+ +:ref:`bool` **dialog_autowrap** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_autowrap**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **has_autowrap**\ (\ ) Sets autowrapping for the text in the dialog. +.. rst-class:: classref-item-separator + +---- + +.. _class_AcceptDialog_property_dialog_close_on_escape: + +.. rst-class:: classref-property + +:ref:`bool` **dialog_close_on_escape** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_close_on_escape**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_close_on_escape**\ (\ ) + +If ``true``, the dialog will be hidden when the ``ui_close_dialog`` action is pressed (by default, this action is bound to :kbd:`Escape`, or :kbd:`Cmd + W` on macOS). + +.. rst-class:: classref-item-separator + ---- .. _class_AcceptDialog_property_dialog_hide_on_ok: -- :ref:`bool` **dialog_hide_on_ok** +.. rst-class:: classref-property + +:ref:`bool` **dialog_hide_on_ok** = ``true`` :ref:`🔗` -+-----------+-----------------------+ -| *Default* | ``true`` | -+-----------+-----------------------+ -| *Setter* | set_hide_on_ok(value) | -+-----------+-----------------------+ -| *Getter* | get_hide_on_ok() | -+-----------+-----------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_hide_on_ok**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_hide_on_ok**\ (\ ) If ``true``, the dialog is hidden when the OK button is pressed. You can set it to ``false`` if you want to do e.g. input validation when receiving the :ref:`confirmed` signal, and handle hiding the dialog in your own logic. -**Note:** Some nodes derived from this class can have a different default value, and potentially their own built-in logic overriding this setting. For example :ref:`FileDialog` defaults to ``false``, and has its own input validation code that is called when you press OK, which eventually hides the dialog if the input is valid. As such, this property can't be used in :ref:`FileDialog` to disable hiding the dialog when pressing OK. +\ **Note:** Some nodes derived from this class can have a different default value, and potentially their own built-in logic overriding this setting. For example :ref:`FileDialog` defaults to ``false``, and has its own input validation code that is called when you press OK, which eventually hides the dialog if the input is valid. As such, this property can't be used in :ref:`FileDialog` to disable hiding the dialog when pressing OK. + +.. rst-class:: classref-item-separator ---- .. _class_AcceptDialog_property_dialog_text: -- :ref:`String` **dialog_text** +.. rst-class:: classref-property + +:ref:`String` **dialog_text** = ``""`` :ref:`🔗` -+-----------+-----------------+ -| *Default* | ``""`` | -+-----------+-----------------+ -| *Setter* | set_text(value) | -+-----------+-----------------+ -| *Getter* | get_text() | -+-----------+-----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_text**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_text**\ (\ ) The text displayed by the dialog. +.. rst-class:: classref-item-separator + +---- + +.. _class_AcceptDialog_property_ok_button_text: + +.. rst-class:: classref-property + +:ref:`String` **ok_button_text** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_ok_button_text**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_ok_button_text**\ (\ ) + +The text displayed by the OK button (see :ref:`get_ok_button()`). If empty, a default text will be used. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- .. _class_AcceptDialog_method_add_button: -- :ref:`Button` **add_button** **(** :ref:`String` text, :ref:`bool` right=false, :ref:`String` action="" **)** +.. rst-class:: classref-method + +:ref:`Button` **add_button**\ (\ text\: :ref:`String`, right\: :ref:`bool` = false, action\: :ref:`String` = ""\ ) :ref:`🔗` -Adds a button with label ``text`` and a custom ``action`` to the dialog and returns the created button. ``action`` will be passed to the :ref:`custom_action` signal when pressed. +Adds a button with label ``text`` and a custom ``action`` to the dialog and returns the created button. + +If ``action`` is not empty, pressing the button will emit the :ref:`custom_action` signal with the specified action string. If ``true``, ``right`` will place the button to the right of any sibling buttons. +You can use :ref:`remove_button()` method to remove a button created with this method from the dialog. + +.. rst-class:: classref-item-separator + ---- -.. _class_AcceptDialog_method_add_cancel: +.. _class_AcceptDialog_method_add_cancel_button: + +.. rst-class:: classref-method -- :ref:`Button` **add_cancel** **(** :ref:`String` name **)** +:ref:`Button` **add_cancel_button**\ (\ name\: :ref:`String`\ ) :ref:`🔗` Adds a button with label ``name`` and a cancel action to the dialog and returns the created button. +You can use :ref:`remove_button()` method to remove a button created with this method from the dialog. + +.. rst-class:: classref-item-separator + ---- .. _class_AcceptDialog_method_get_label: -- :ref:`Label` **get_label** **(** **)** +.. rst-class:: classref-method + +:ref:`Label` **get_label**\ (\ ) :ref:`🔗` Returns the label used for built-in text. +\ **Warning:** This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`CanvasItem.visible` property. + +.. rst-class:: classref-item-separator + ---- -.. _class_AcceptDialog_method_get_ok: +.. _class_AcceptDialog_method_get_ok_button: + +.. rst-class:: classref-method -- :ref:`Button` **get_ok** **(** **)** +:ref:`Button` **get_ok_button**\ (\ ) :ref:`🔗` Returns the OK :ref:`Button` instance. +\ **Warning:** This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`CanvasItem.visible` property. + +.. rst-class:: classref-item-separator + ---- .. _class_AcceptDialog_method_register_text_enter: -- void **register_text_enter** **(** :ref:`Node` line_edit **)** +.. rst-class:: classref-method + +|void| **register_text_enter**\ (\ line_edit\: :ref:`LineEdit`\ ) :ref:`🔗` Registers a :ref:`LineEdit` in the dialog. When the enter key is pressed, the dialog will be accepted. +.. rst-class:: classref-item-separator + +---- + +.. _class_AcceptDialog_method_remove_button: + +.. rst-class:: classref-method + +|void| **remove_button**\ (\ button\: :ref:`Button`\ ) :ref:`🔗` + +Removes the ``button`` from the dialog. Does NOT free the ``button``. The ``button`` must be a :ref:`Button` added with :ref:`add_button()` or :ref:`add_cancel_button()` method. After removal, pressing the ``button`` will no longer emit this dialog's :ref:`custom_action` or :ref:`canceled` signals. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Theme Property Descriptions +--------------------------- + +.. _class_AcceptDialog_theme_constant_buttons_min_height: + +.. rst-class:: classref-themeproperty + +:ref:`int` **buttons_min_height** = ``0`` :ref:`🔗` + +The minimum height of each button in the bottom row (such as OK/Cancel) in pixels. This can be increased to make buttons with short texts easier to click/tap. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AcceptDialog_theme_constant_buttons_min_width: + +.. rst-class:: classref-themeproperty + +:ref:`int` **buttons_min_width** = ``0`` :ref:`🔗` + +The minimum width of each button in the bottom row (such as OK/Cancel) in pixels. This can be increased to make buttons with short texts easier to click/tap. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AcceptDialog_theme_constant_buttons_separation: + +.. rst-class:: classref-themeproperty + +:ref:`int` **buttons_separation** = ``10`` :ref:`🔗` + +The size of the vertical space between the dialog's content and the button row. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AcceptDialog_theme_style_panel: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **panel** :ref:`🔗` + +The panel that fills the background of the window. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_aescontext.rst b/classes/class_aescontext.rst new file mode 100644 index 00000000000..a8f24d24ca0 --- /dev/null +++ b/classes/class_aescontext.rst @@ -0,0 +1,237 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AESContext.xml. + +.. _class_AESContext: + +AESContext +========== + +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` + +Provides access to AES encryption/decryption of raw data. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This class holds the context information required for encryption and decryption operations with AES (Advanced Encryption Standard). Both AES-ECB and AES-CBC modes are supported. + + +.. tabs:: + + .. code-tab:: gdscript + + extends Node + + var aes = AESContext.new() + + func _ready(): + var key = "My secret key!!!" # Key must be either 16 or 32 bytes. + var data = "My secret text!!" # Data size must be multiple of 16 bytes, apply padding if needed. + # Encrypt ECB + aes.start(AESContext.MODE_ECB_ENCRYPT, key.to_utf8_buffer()) + var encrypted = aes.update(data.to_utf8_buffer()) + aes.finish() + # Decrypt ECB + aes.start(AESContext.MODE_ECB_DECRYPT, key.to_utf8_buffer()) + var decrypted = aes.update(encrypted) + aes.finish() + # Check ECB + assert(decrypted == data.to_utf8_buffer()) + + var iv = "My secret iv!!!!" # IV must be of exactly 16 bytes. + # Encrypt CBC + aes.start(AESContext.MODE_CBC_ENCRYPT, key.to_utf8_buffer(), iv.to_utf8_buffer()) + encrypted = aes.update(data.to_utf8_buffer()) + aes.finish() + # Decrypt CBC + aes.start(AESContext.MODE_CBC_DECRYPT, key.to_utf8_buffer(), iv.to_utf8_buffer()) + decrypted = aes.update(encrypted) + aes.finish() + # Check CBC + assert(decrypted == data.to_utf8_buffer()) + + .. code-tab:: csharp + + using Godot; + using System.Diagnostics; + + public partial class MyNode : Node + { + private AesContext _aes = new AesContext(); + + public override void _Ready() + { + string key = "My secret key!!!"; // Key must be either 16 or 32 bytes. + string data = "My secret text!!"; // Data size must be multiple of 16 bytes, apply padding if needed. + // Encrypt ECB + _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8Buffer()); + byte[] encrypted = _aes.Update(data.ToUtf8Buffer()); + _aes.Finish(); + // Decrypt ECB + _aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8Buffer()); + byte[] decrypted = _aes.Update(encrypted); + _aes.Finish(); + // Check ECB + Debug.Assert(decrypted == data.ToUtf8Buffer()); + + string iv = "My secret iv!!!!"; // IV must be of exactly 16 bytes. + // Encrypt CBC + _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8Buffer(), iv.ToUtf8Buffer()); + encrypted = _aes.Update(data.ToUtf8Buffer()); + _aes.Finish(); + // Decrypt CBC + _aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8Buffer(), iv.ToUtf8Buffer()); + decrypted = _aes.Update(encrypted); + _aes.Finish(); + // Check CBC + Debug.Assert(decrypted == data.ToUtf8Buffer()); + } + } + + + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`finish`\ (\ ) | + +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedByteArray` | :ref:`get_iv_state`\ (\ ) | + +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`start`\ (\ mode\: :ref:`Mode`, key\: :ref:`PackedByteArray`, iv\: :ref:`PackedByteArray` = PackedByteArray()\ ) | + +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedByteArray` | :ref:`update`\ (\ src\: :ref:`PackedByteArray`\ ) | + +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AESContext_Mode: + +.. rst-class:: classref-enumeration + +enum **Mode**: :ref:`🔗` + +.. _class_AESContext_constant_MODE_ECB_ENCRYPT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_ECB_ENCRYPT** = ``0`` + +AES electronic codebook encryption mode. + +.. _class_AESContext_constant_MODE_ECB_DECRYPT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_ECB_DECRYPT** = ``1`` + +AES electronic codebook decryption mode. + +.. _class_AESContext_constant_MODE_CBC_ENCRYPT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_CBC_ENCRYPT** = ``2`` + +AES cipher block chaining encryption mode. + +.. _class_AESContext_constant_MODE_CBC_DECRYPT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_CBC_DECRYPT** = ``3`` + +AES cipher block chaining decryption mode. + +.. _class_AESContext_constant_MODE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_MAX** = ``4`` + +Maximum value for the mode enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AESContext_method_finish: + +.. rst-class:: classref-method + +|void| **finish**\ (\ ) :ref:`🔗` + +Close this AES context so it can be started again. See :ref:`start()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AESContext_method_get_iv_state: + +.. rst-class:: classref-method + +:ref:`PackedByteArray` **get_iv_state**\ (\ ) :ref:`🔗` + +Get the current IV state for this context (IV gets updated when calling :ref:`update()`). You normally don't need this function. + +\ **Note:** This function only makes sense when the context is started with :ref:`MODE_CBC_ENCRYPT` or :ref:`MODE_CBC_DECRYPT`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AESContext_method_start: + +.. rst-class:: classref-method + +:ref:`Error` **start**\ (\ mode\: :ref:`Mode`, key\: :ref:`PackedByteArray`, iv\: :ref:`PackedByteArray` = PackedByteArray()\ ) :ref:`🔗` + +Start the AES context in the given ``mode``. A ``key`` of either 16 or 32 bytes must always be provided, while an ``iv`` (initialization vector) of exactly 16 bytes, is only needed when ``mode`` is either :ref:`MODE_CBC_ENCRYPT` or :ref:`MODE_CBC_DECRYPT`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AESContext_method_update: + +.. rst-class:: classref-method + +:ref:`PackedByteArray` **update**\ (\ src\: :ref:`PackedByteArray`\ ) :ref:`🔗` + +Run the desired operation for this AES context. Will return a :ref:`PackedByteArray` containing the result of encrypting (or decrypting) the given ``src``. See :ref:`start()` for mode of operation. + +\ **Note:** The size of ``src`` must be a multiple of 16. Apply some padding if needed. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_aimmodifier3d.rst b/classes/class_aimmodifier3d.rst new file mode 100644 index 00000000000..07ca7f60284 --- /dev/null +++ b/classes/class_aimmodifier3d.rst @@ -0,0 +1,197 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AimModifier3D.xml. + +.. _class_AimModifier3D: + +AimModifier3D +============= + +**Inherits:** :ref:`BoneConstraint3D` **<** :ref:`SkeletonModifier3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +The **AimModifier3D** rotates a bone to look at a reference bone. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This is a simple version of :ref:`LookAtModifier3D` that only allows bone to the reference without advanced options such as angle limitation or time-based interpolation. + +The feature is simplified, but instead it is implemented with smooth tracking without euler, see :ref:`set_use_euler()`. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------+------------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`setting_count` | ``0`` | + +-----------------------+------------------------------------------------------------------+-------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`BoneAxis` | :ref:`get_forward_axis`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Axis` | :ref:`get_primary_rotation_axis`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_using_euler`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_using_secondary_rotation`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_forward_axis`\ (\ index\: :ref:`int`, axis\: :ref:`BoneAxis`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_primary_rotation_axis`\ (\ index\: :ref:`int`, axis\: :ref:`Axis`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_use_euler`\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_use_secondary_rotation`\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AimModifier3D_property_setting_count: + +.. rst-class:: classref-property + +:ref:`int` **setting_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_setting_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_setting_count**\ (\ ) + +The number of settings in the modifier. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AimModifier3D_method_get_forward_axis: + +.. rst-class:: classref-method + +:ref:`BoneAxis` **get_forward_axis**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the forward axis of the bone. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_get_primary_rotation_axis: + +.. rst-class:: classref-method + +:ref:`Axis` **get_primary_rotation_axis**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the axis of the first rotation. It is enabled only if :ref:`is_using_euler()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_is_using_euler: + +.. rst-class:: classref-method + +:ref:`bool` **is_using_euler**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if it provides rotation with using euler. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_is_using_secondary_rotation: + +.. rst-class:: classref-method + +:ref:`bool` **is_using_secondary_rotation**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if it provides rotation by two axes. It is enabled only if :ref:`is_using_euler()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_set_forward_axis: + +.. rst-class:: classref-method + +|void| **set_forward_axis**\ (\ index\: :ref:`int`, axis\: :ref:`BoneAxis`\ ) :ref:`🔗` + +Sets the forward axis of the bone. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_set_primary_rotation_axis: + +.. rst-class:: classref-method + +|void| **set_primary_rotation_axis**\ (\ index\: :ref:`int`, axis\: :ref:`Axis`\ ) :ref:`🔗` + +Sets the axis of the first rotation. It is enabled only if :ref:`is_using_euler()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_set_use_euler: + +.. rst-class:: classref-method + +|void| **set_use_euler**\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` + +If sets ``enabled`` to ``true``, it provides rotation with using euler. + +If sets ``enabled`` to ``false``, it provides rotation with using rotation by arc generated from the forward axis vector and the vector toward the reference. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_set_use_secondary_rotation: + +.. rst-class:: classref-method + +|void| **set_use_secondary_rotation**\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` + +If sets ``enabled`` to ``true``, it provides rotation by two axes. It is enabled only if :ref:`is_using_euler()` is ``true``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animatablebody2d.rst b/classes/class_animatablebody2d.rst new file mode 100644 index 00000000000..33677392102 --- /dev/null +++ b/classes/class_animatablebody2d.rst @@ -0,0 +1,77 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimatableBody2D.xml. + +.. _class_AnimatableBody2D: + +AnimatableBody2D +================ + +**Inherits:** :ref:`StaticBody2D` **<** :ref:`PhysicsBody2D` **<** :ref:`CollisionObject2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` + +A 2D physics body that can't be moved by external forces. When moved manually, it affects other bodies in its path. + +.. rst-class:: classref-introduction-group + +Description +----------- + +An animatable 2D physics body. It can't be moved by external forces or contacts, but can be moved manually by other means such as code, :ref:`AnimationMixer`\ s (with :ref:`AnimationMixer.callback_mode_process` set to :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS`), and :ref:`RemoteTransform2D`. + +When **AnimatableBody2D** is moved, its linear and angular velocity are estimated and used to affect other physics bodies in its path. This makes it useful for moving platforms, doors, and other moving objects. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- :doc:`Troubleshooting physics issues <../tutorials/physics/troubleshooting_physics_issues>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+-------------------------------------------------------------------------+----------+ + | :ref:`bool` | :ref:`sync_to_physics` | ``true`` | + +-------------------------+-------------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimatableBody2D_property_sync_to_physics: + +.. rst-class:: classref-property + +:ref:`bool` **sync_to_physics** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_sync_to_physics**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_sync_to_physics_enabled**\ (\ ) + +If ``true``, the body's movement will be synchronized to the physics frame. This is useful when animating movement via :ref:`AnimationPlayer`, for example on moving platforms. Do **not** use together with :ref:`PhysicsBody2D.move_and_collide()`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animatablebody3d.rst b/classes/class_animatablebody3d.rst new file mode 100644 index 00000000000..1705b4d328b --- /dev/null +++ b/classes/class_animatablebody3d.rst @@ -0,0 +1,83 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimatableBody3D.xml. + +.. _class_AnimatableBody3D: + +AnimatableBody3D +================ + +**Inherits:** :ref:`StaticBody3D` **<** :ref:`PhysicsBody3D` **<** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +A 3D physics body that can't be moved by external forces. When moved manually, it affects other bodies in its path. + +.. rst-class:: classref-introduction-group + +Description +----------- + +An animatable 3D physics body. It can't be moved by external forces or contacts, but can be moved manually by other means such as code, :ref:`AnimationMixer`\ s (with :ref:`AnimationMixer.callback_mode_process` set to :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS`), and :ref:`RemoteTransform3D`. + +When **AnimatableBody3D** is moved, its linear and angular velocity are estimated and used to affect other physics bodies in its path. This makes it useful for moving platforms, doors, and other moving objects. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- :doc:`Troubleshooting physics issues <../tutorials/physics/troubleshooting_physics_issues>` + +- `3D Physics Tests Demo `__ + +- `Third Person Shooter (TPS) Demo `__ + +- `3D Voxel Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+-------------------------------------------------------------------------+----------+ + | :ref:`bool` | :ref:`sync_to_physics` | ``true`` | + +-------------------------+-------------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimatableBody3D_property_sync_to_physics: + +.. rst-class:: classref-property + +:ref:`bool` **sync_to_physics** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_sync_to_physics**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_sync_to_physics_enabled**\ (\ ) + +If ``true``, the body's movement will be synchronized to the physics frame. This is useful when animating movement via :ref:`AnimationPlayer`, for example on moving platforms. Do **not** use together with :ref:`PhysicsBody3D.move_and_collide()`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animatedsprite.rst b/classes/class_animatedsprite.rst deleted file mode 100644 index bd74b043bfe..00000000000 --- a/classes/class_animatedsprite.rst +++ /dev/null @@ -1,271 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimatedSprite.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_AnimatedSprite: - -AnimatedSprite -============== - -**Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` - -Sprite node that can use multiple textures for animation. - -Description ------------ - -Animations are created using a :ref:`SpriteFrames` resource, which can be configured in the editor via the SpriteFrames panel. - -Properties ----------- - -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`StringName` | :ref:`animation` | ``@"default"`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`centered` | ``true`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`flip_h` | ``false`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`flip_v` | ``false`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`frame` | ``0`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`SpriteFrames` | :ref:`frames` | | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`Vector2` | :ref:`offset` | ``Vector2( 0, 0 )`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`playing` | ``false`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`shininess` | ``1.0`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`specular_color` | ``Color( 1, 1, 1, 1 )`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`speed_scale` | ``1.0`` | -+-----------------------------------------+---------------------------------------------------------------------+-------------------------+ - -Methods -------- - -+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_playing` **(** **)** const | -+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`play` **(** :ref:`StringName` anim=@"", :ref:`bool` backwards=false **)** | -+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop` **(** **)** | -+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - -Signals -------- - -.. _class_AnimatedSprite_signal_animation_finished: - -- **animation_finished** **(** **)** - -Emitted when the animation is finished (when it plays the last frame). If the animation is looping, this signal is emitted every time the last frame is drawn. - ----- - -.. _class_AnimatedSprite_signal_frame_changed: - -- **frame_changed** **(** **)** - -Emitted when :ref:`frame` changed. - -Property Descriptions ---------------------- - -.. _class_AnimatedSprite_property_animation: - -- :ref:`StringName` **animation** - -+-----------+----------------------+ -| *Default* | ``@"default"`` | -+-----------+----------------------+ -| *Setter* | set_animation(value) | -+-----------+----------------------+ -| *Getter* | get_animation() | -+-----------+----------------------+ - -The current animation from the ``frames`` resource. If this value changes, the ``frame`` counter is reset. - ----- - -.. _class_AnimatedSprite_property_centered: - -- :ref:`bool` **centered** - -+-----------+---------------------+ -| *Default* | ``true`` | -+-----------+---------------------+ -| *Setter* | set_centered(value) | -+-----------+---------------------+ -| *Getter* | is_centered() | -+-----------+---------------------+ - -If ``true``, texture will be centered. - ----- - -.. _class_AnimatedSprite_property_flip_h: - -- :ref:`bool` **flip_h** - -+-----------+-------------------+ -| *Default* | ``false`` | -+-----------+-------------------+ -| *Setter* | set_flip_h(value) | -+-----------+-------------------+ -| *Getter* | is_flipped_h() | -+-----------+-------------------+ - -If ``true``, texture is flipped horizontally. - ----- - -.. _class_AnimatedSprite_property_flip_v: - -- :ref:`bool` **flip_v** - -+-----------+-------------------+ -| *Default* | ``false`` | -+-----------+-------------------+ -| *Setter* | set_flip_v(value) | -+-----------+-------------------+ -| *Getter* | is_flipped_v() | -+-----------+-------------------+ - -If ``true``, texture is flipped vertically. - ----- - -.. _class_AnimatedSprite_property_frame: - -- :ref:`int` **frame** - -+-----------+------------------+ -| *Default* | ``0`` | -+-----------+------------------+ -| *Setter* | set_frame(value) | -+-----------+------------------+ -| *Getter* | get_frame() | -+-----------+------------------+ - -The displayed animation frame's index. - ----- - -.. _class_AnimatedSprite_property_frames: - -- :ref:`SpriteFrames` **frames** - -+----------+--------------------------+ -| *Setter* | set_sprite_frames(value) | -+----------+--------------------------+ -| *Getter* | get_sprite_frames() | -+----------+--------------------------+ - -The :ref:`SpriteFrames` resource containing the animation(s). - ----- - -.. _class_AnimatedSprite_property_offset: - -- :ref:`Vector2` **offset** - -+-----------+---------------------+ -| *Default* | ``Vector2( 0, 0 )`` | -+-----------+---------------------+ -| *Setter* | set_offset(value) | -+-----------+---------------------+ -| *Getter* | get_offset() | -+-----------+---------------------+ - -The texture's drawing offset. - ----- - -.. _class_AnimatedSprite_property_playing: - -- :ref:`bool` **playing** - -+-----------+-----------+ -| *Default* | ``false`` | -+-----------+-----------+ - -If ``true``, the :ref:`animation` is currently playing. - ----- - -.. _class_AnimatedSprite_property_shininess: - -- :ref:`float` **shininess** - -+-----------+----------------------+ -| *Default* | ``1.0`` | -+-----------+----------------------+ -| *Setter* | set_shininess(value) | -+-----------+----------------------+ -| *Getter* | get_shininess() | -+-----------+----------------------+ - -Strength of the specular light effect of this ``AnimatedSprite``. - ----- - -.. _class_AnimatedSprite_property_specular_color: - -- :ref:`Color` **specular_color** - -+-----------+---------------------------+ -| *Default* | ``Color( 1, 1, 1, 1 )`` | -+-----------+---------------------------+ -| *Setter* | set_specular_color(value) | -+-----------+---------------------------+ -| *Getter* | get_specular_color() | -+-----------+---------------------------+ - -The color of the specular light effect. - ----- - -.. _class_AnimatedSprite_property_speed_scale: - -- :ref:`float` **speed_scale** - -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_speed_scale(value) | -+-----------+------------------------+ -| *Getter* | get_speed_scale() | -+-----------+------------------------+ - -The animation speed is multiplied by this value. - -Method Descriptions -------------------- - -.. _class_AnimatedSprite_method_is_playing: - -- :ref:`bool` **is_playing** **(** **)** const - -Returns ``true`` if an animation is currently being played. - ----- - -.. _class_AnimatedSprite_method_play: - -- void **play** **(** :ref:`StringName` anim=@"", :ref:`bool` backwards=false **)** - -Plays the animation named ``anim``. If no ``anim`` is provided, the current animation is played. If ``backwards`` is ``true``, the animation will be played in reverse. - ----- - -.. _class_AnimatedSprite_method_stop: - -- void **stop** **(** **)** - -Stops the current animation (does not reset the frame counter). - diff --git a/classes/class_animatedsprite2d.rst b/classes/class_animatedsprite2d.rst new file mode 100644 index 00000000000..6843d94c92d --- /dev/null +++ b/classes/class_animatedsprite2d.rst @@ -0,0 +1,452 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimatedSprite2D.xml. + +.. _class_AnimatedSprite2D: + +AnimatedSprite2D +================ + +**Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` + +Sprite node that contains multiple textures as frames to play for animation. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**AnimatedSprite2D** is similar to the :ref:`Sprite2D` node, except it carries multiple textures as animation frames. Animations are created using a :ref:`SpriteFrames` resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The :ref:`SpriteFrames` resource can be configured in the editor via the SpriteFrames bottom panel. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`2D Sprite animation <../tutorials/2d/2d_sprite_animation>` + +- `2D Dodge The Creeps Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`StringName` | :ref:`animation` | ``&"default"`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`String` | :ref:`autoplay` | ``""`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`centered` | ``true`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`flip_h` | ``false`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`flip_v` | ``false`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`int` | :ref:`frame` | ``0`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`frame_progress` | ``0.0`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`Vector2` | :ref:`offset` | ``Vector2(0, 0)`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`speed_scale` | ``1.0`` | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + | :ref:`SpriteFrames` | :ref:`sprite_frames` | | + +-----------------------------------------+-----------------------------------------------------------------------+-------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playing_speed`\ (\ ) |const| | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`pause`\ (\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play`\ (\ name\: :ref:`StringName` = &"", custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_backwards`\ (\ name\: :ref:`StringName` = &""\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_frame_and_progress`\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_AnimatedSprite2D_signal_animation_changed: + +.. rst-class:: classref-signal + +**animation_changed**\ (\ ) :ref:`🔗` + +Emitted when :ref:`animation` changes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_signal_animation_finished: + +.. rst-class:: classref-signal + +**animation_finished**\ (\ ) :ref:`🔗` + +Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback. + +\ **Note:** This signal is not emitted if an animation is looping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_signal_animation_looped: + +.. rst-class:: classref-signal + +**animation_looped**\ (\ ) :ref:`🔗` + +Emitted when the animation loops. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_signal_frame_changed: + +.. rst-class:: classref-signal + +**frame_changed**\ (\ ) :ref:`🔗` + +Emitted when :ref:`frame` changes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_signal_sprite_frames_changed: + +.. rst-class:: classref-signal + +**sprite_frames_changed**\ (\ ) :ref:`🔗` + +Emitted when :ref:`sprite_frames` changes. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimatedSprite2D_property_animation: + +.. rst-class:: classref-property + +:ref:`StringName` **animation** = ``&"default"`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_animation**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_animation**\ (\ ) + +The current animation from the :ref:`sprite_frames` resource. If this value is changed, the :ref:`frame` counter and the :ref:`frame_progress` are reset. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_autoplay: + +.. rst-class:: classref-property + +:ref:`String` **autoplay** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_autoplay**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_autoplay**\ (\ ) + +The key of the animation to play when the scene loads. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_centered: + +.. rst-class:: classref-property + +:ref:`bool` **centered** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_centered**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_centered**\ (\ ) + +If ``true``, texture will be centered. + +\ **Note:** For games with a pixel art aesthetic, textures may appear deformed when centered. This is caused by their position being between pixels. To prevent this, set this property to ``false``, or consider enabling :ref:`ProjectSettings.rendering/2d/snap/snap_2d_vertices_to_pixel` and :ref:`ProjectSettings.rendering/2d/snap/snap_2d_transforms_to_pixel`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_flip_h: + +.. rst-class:: classref-property + +:ref:`bool` **flip_h** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flip_h**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_flipped_h**\ (\ ) + +If ``true``, texture is flipped horizontally. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_flip_v: + +.. rst-class:: classref-property + +:ref:`bool` **flip_v** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flip_v**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_flipped_v**\ (\ ) + +If ``true``, texture is flipped vertically. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_frame: + +.. rst-class:: classref-property + +:ref:`int` **frame** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_frame**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_frame**\ (\ ) + +The displayed animation frame's index. Setting this property also resets :ref:`frame_progress`. If this is not desired, use :ref:`set_frame_and_progress()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_frame_progress: + +.. rst-class:: classref-property + +:ref:`float` **frame_progress** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_frame_progress**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_frame_progress**\ (\ ) + +The progress value between ``0.0`` and ``1.0`` until the current frame transitions to the next frame. If the animation is playing backwards, the value transitions from ``1.0`` to ``0.0``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_offset: + +.. rst-class:: classref-property + +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_offset**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_offset**\ (\ ) + +The texture's drawing offset. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_speed_scale: + +.. rst-class:: classref-property + +:ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_speed_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_speed_scale**\ (\ ) + +The speed scaling ratio. For example, if this value is ``1``, then the animation plays at normal speed. If it's ``0.5``, then it plays at half speed. If it's ``2``, then it plays at double speed. + +If set to a negative value, the animation is played in reverse. If set to ``0``, the animation will not advance. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_property_sprite_frames: + +.. rst-class:: classref-property + +:ref:`SpriteFrames` **sprite_frames** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_sprite_frames**\ (\ value\: :ref:`SpriteFrames`\ ) +- :ref:`SpriteFrames` **get_sprite_frames**\ (\ ) + +The :ref:`SpriteFrames` resource containing the animation(s). Allows you the option to load, edit, clear, make unique and save the states of the :ref:`SpriteFrames` resource. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AnimatedSprite2D_method_get_playing_speed: + +.. rst-class:: classref-method + +:ref:`float` **get_playing_speed**\ (\ ) |const| :ref:`🔗` + +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play()` method. + +Returns a negative value if the current animation is playing backwards. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_method_is_playing: + +.. rst-class:: classref-method + +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale` and/or ``custom_speed`` are ``0``). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_method_pause: + +.. rst-class:: classref-method + +|void| **pause**\ (\ ) :ref:`🔗` + +Pauses the currently playing animation. The :ref:`frame` and :ref:`frame_progress` will be kept and calling :ref:`play()` or :ref:`play_backwards()` without arguments will resume the animation from the current playback position. + +See also :ref:`stop()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_method_play: + +.. rst-class:: classref-method + +|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` + +Plays the animation with key ``name``. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards()`). + +If this method is called with that same animation ``name``, or with no ``name`` parameter, the assigned animation will resume playing if it was paused. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_method_play_backwards: + +.. rst-class:: classref-method + +|void| **play_backwards**\ (\ name\: :ref:`StringName` = &""\ ) :ref:`🔗` + +Plays the animation with key ``name`` in reverse. + +This method is a shorthand for :ref:`play()` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_method_set_frame_and_progress: + +.. rst-class:: classref-method + +|void| **set_frame_and_progress**\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) :ref:`🔗` + +Sets :ref:`frame` and :ref:`frame_progress` to the given values. Unlike setting :ref:`frame`, this method does not reset the :ref:`frame_progress` to ``0.0`` implicitly. + +\ **Example:** Change the animation while keeping the same :ref:`frame` and :ref:`frame_progress`: + + +.. tabs:: + + .. code-tab:: gdscript + + var current_frame = animated_sprite.get_frame() + var current_progress = animated_sprite.get_frame_progress() + animated_sprite.play("walk_another_skin") + animated_sprite.set_frame_and_progress(current_frame, current_progress) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite2D_method_stop: + +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`🔗` + +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause()`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animatedsprite3d.rst b/classes/class_animatedsprite3d.rst index 660af2238a9..9e2d066f4ce 100644 --- a/classes/class_animatedsprite3d.rst +++ b/classes/class_animatedsprite3d.rst @@ -1,137 +1,372 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimatedSprite3D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimatedSprite3D.xml. .. _class_AnimatedSprite3D: AnimatedSprite3D ================ -**Inherits:** :ref:`SpriteBase3D` **<** :ref:`GeometryInstance` **<** :ref:`VisualInstance` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` +**Inherits:** :ref:`SpriteBase3D` **<** :ref:`GeometryInstance3D` **<** :ref:`VisualInstance3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` 2D sprite node in 3D world, that can use multiple 2D textures for animation. +.. rst-class:: classref-introduction-group + Description ----------- -Animations are created using a :ref:`SpriteFrames` resource, which can be configured in the editor via the SpriteFrames panel. +**AnimatedSprite3D** is similar to the :ref:`Sprite3D` node, except it carries multiple textures as animation :ref:`sprite_frames`. Animations are created using a :ref:`SpriteFrames` resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The :ref:`SpriteFrames` resource can be configured in the editor via the SpriteFrames bottom panel. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`2D Sprite animation (also applies to 3D) <../tutorials/2d/2d_sprite_animation>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------+-------------------------------------------------------------+----------------+ -| :ref:`StringName` | :ref:`animation` | ``@"default"`` | -+-----------------------------------------+-------------------------------------------------------------+----------------+ -| :ref:`int` | :ref:`frame` | ``0`` | -+-----------------------------------------+-------------------------------------------------------------+----------------+ -| :ref:`SpriteFrames` | :ref:`frames` | | -+-----------------------------------------+-------------------------------------------------------------+----------------+ -| :ref:`bool` | :ref:`playing` | ``false`` | -+-----------------------------------------+-------------------------------------------------------------+----------------+ +.. table:: + :widths: auto + + +-----------------------------------------+-----------------------------------------------------------------------+----------------+ + | :ref:`StringName` | :ref:`animation` | ``&"default"`` | + +-----------------------------------------+-----------------------------------------------------------------------+----------------+ + | :ref:`String` | :ref:`autoplay` | ``""`` | + +-----------------------------------------+-----------------------------------------------------------------------+----------------+ + | :ref:`int` | :ref:`frame` | ``0`` | + +-----------------------------------------+-----------------------------------------------------------------------+----------------+ + | :ref:`float` | :ref:`frame_progress` | ``0.0`` | + +-----------------------------------------+-----------------------------------------------------------------------+----------------+ + | :ref:`float` | :ref:`speed_scale` | ``1.0`` | + +-----------------------------------------+-----------------------------------------------------------------------+----------------+ + | :ref:`SpriteFrames` | :ref:`sprite_frames` | | + +-----------------------------------------+-----------------------------------------------------------------------+----------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------+----------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_playing` **(** **)** const | -+-------------------------+----------------------------------------------------------------------------------------------------------+ -| void | :ref:`play` **(** :ref:`StringName` anim=@"" **)** | -+-------------------------+----------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop` **(** **)** | -+-------------------------+----------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playing_speed`\ (\ ) |const| | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`pause`\ (\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play`\ (\ name\: :ref:`StringName` = &"", custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_backwards`\ (\ name\: :ref:`StringName` = &""\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_frame_and_progress`\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- +.. _class_AnimatedSprite3D_signal_animation_changed: + +.. rst-class:: classref-signal + +**animation_changed**\ (\ ) :ref:`🔗` + +Emitted when :ref:`animation` changes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite3D_signal_animation_finished: + +.. rst-class:: classref-signal + +**animation_finished**\ (\ ) :ref:`🔗` + +Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback. + +\ **Note:** This signal is not emitted if an animation is looping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite3D_signal_animation_looped: + +.. rst-class:: classref-signal + +**animation_looped**\ (\ ) :ref:`🔗` + +Emitted when the animation loops. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimatedSprite3D_signal_frame_changed: -- **frame_changed** **(** **)** +.. rst-class:: classref-signal -Emitted when :ref:`frame` changed. +**frame_changed**\ (\ ) :ref:`🔗` + +Emitted when :ref:`frame` changes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite3D_signal_sprite_frames_changed: + +.. rst-class:: classref-signal + +**sprite_frames_changed**\ (\ ) :ref:`🔗` + +Emitted when :ref:`sprite_frames` changes. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AnimatedSprite3D_property_animation: -- :ref:`StringName` **animation** +.. rst-class:: classref-property + +:ref:`StringName` **animation** = ``&"default"`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_animation**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_animation**\ (\ ) -+-----------+----------------------+ -| *Default* | ``@"default"`` | -+-----------+----------------------+ -| *Setter* | set_animation(value) | -+-----------+----------------------+ -| *Getter* | get_animation() | -+-----------+----------------------+ +The current animation from the :ref:`sprite_frames` resource. If this value is changed, the :ref:`frame` counter and the :ref:`frame_progress` are reset. -The current animation from the ``frames`` resource. If this value changes, the ``frame`` counter is reset. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite3D_property_autoplay: + +.. rst-class:: classref-property + +:ref:`String` **autoplay** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_autoplay**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_autoplay**\ (\ ) + +The key of the animation to play when the scene loads. + +.. rst-class:: classref-item-separator ---- .. _class_AnimatedSprite3D_property_frame: -- :ref:`int` **frame** +.. rst-class:: classref-property + +:ref:`int` **frame** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_frame**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_frame**\ (\ ) + +The displayed animation frame's index. Setting this property also resets :ref:`frame_progress`. If this is not desired, use :ref:`set_frame_and_progress()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite3D_property_frame_progress: + +.. rst-class:: classref-property + +:ref:`float` **frame_progress** = ``0.0`` :ref:`🔗` -+-----------+------------------+ -| *Default* | ``0`` | -+-----------+------------------+ -| *Setter* | set_frame(value) | -+-----------+------------------+ -| *Getter* | get_frame() | -+-----------+------------------+ +.. rst-class:: classref-property-setget -The displayed animation frame's index. +- |void| **set_frame_progress**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_frame_progress**\ (\ ) + +The progress value between ``0.0`` and ``1.0`` until the current frame transitions to the next frame. If the animation is playing backwards, the value transitions from ``1.0`` to ``0.0``. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimatedSprite3D_property_frames: +.. _class_AnimatedSprite3D_property_speed_scale: + +.. rst-class:: classref-property + +:ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` -- :ref:`SpriteFrames` **frames** +.. rst-class:: classref-property-setget -+----------+--------------------------+ -| *Setter* | set_sprite_frames(value) | -+----------+--------------------------+ -| *Getter* | get_sprite_frames() | -+----------+--------------------------+ +- |void| **set_speed_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_speed_scale**\ (\ ) -The :ref:`SpriteFrames` resource containing the animation(s). +The speed scaling ratio. For example, if this value is ``1``, then the animation plays at normal speed. If it's ``0.5``, then it plays at half speed. If it's ``2``, then it plays at double speed. + +If set to a negative value, the animation is played in reverse. If set to ``0``, the animation will not advance. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimatedSprite3D_property_playing: +.. _class_AnimatedSprite3D_property_sprite_frames: + +.. rst-class:: classref-property + +:ref:`SpriteFrames` **sprite_frames** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_sprite_frames**\ (\ value\: :ref:`SpriteFrames`\ ) +- :ref:`SpriteFrames` **get_sprite_frames**\ (\ ) + +The :ref:`SpriteFrames` resource containing the animation(s). Allows you the option to load, edit, clear, make unique and save the states of the :ref:`SpriteFrames` resource. -- :ref:`bool` **playing** +.. rst-class:: classref-section-separator -+-----------+-----------+ -| *Default* | ``false`` | -+-----------+-----------+ +---- -If ``true``, the :ref:`animation` is currently playing. +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- +.. _class_AnimatedSprite3D_method_get_playing_speed: + +.. rst-class:: classref-method + +:ref:`float` **get_playing_speed**\ (\ ) |const| :ref:`🔗` + +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play()` method. + +Returns a negative value if the current animation is playing backwards. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimatedSprite3D_method_is_playing: -- :ref:`bool` **is_playing** **(** **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale` and/or ``custom_speed`` are ``0``). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite3D_method_pause: -Returns ``true`` if an animation is currently being played. +.. rst-class:: classref-method + +|void| **pause**\ (\ ) :ref:`🔗` + +Pauses the currently playing animation. The :ref:`frame` and :ref:`frame_progress` will be kept and calling :ref:`play()` or :ref:`play_backwards()` without arguments will resume the animation from the current playback position. + +See also :ref:`stop()`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimatedSprite3D_method_play: -- void **play** **(** :ref:`StringName` anim=@"" **)** +.. rst-class:: classref-method + +|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` + +Plays the animation with key ``name``. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards()`). + +If this method is called with that same animation ``name``, or with no ``name`` parameter, the assigned animation will resume playing if it was paused. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite3D_method_play_backwards: + +.. rst-class:: classref-method + +|void| **play_backwards**\ (\ name\: :ref:`StringName` = &""\ ) :ref:`🔗` + +Plays the animation with key ``name`` in reverse. + +This method is a shorthand for :ref:`play()` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. -Plays the animation named ``anim``. If no ``anim`` is provided, the current animation is played. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedSprite3D_method_set_frame_and_progress: + +.. rst-class:: classref-method + +|void| **set_frame_and_progress**\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) :ref:`🔗` + +Sets :ref:`frame` and :ref:`frame_progress` to the given values. Unlike setting :ref:`frame`, this method does not reset the :ref:`frame_progress` to ``0.0`` implicitly. + +\ **Example:** Change the animation while keeping the same :ref:`frame` and :ref:`frame_progress`: + + +.. tabs:: + + .. code-tab:: gdscript + + var current_frame = animated_sprite.get_frame() + var current_progress = animated_sprite.get_frame_progress() + animated_sprite.play("walk_another_skin") + animated_sprite.set_frame_and_progress(current_frame, current_progress) + + + +.. rst-class:: classref-item-separator ---- .. _class_AnimatedSprite3D_method_stop: -- void **stop** **(** **)** +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`🔗` -Stops the current animation (does not reset the frame counter). +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause()`. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animatedtexture.rst b/classes/class_animatedtexture.rst index 2a05bf66a72..7a8e812f059 100644 --- a/classes/class_animatedtexture.rst +++ b/classes/class_animatedtexture.rst @@ -1,132 +1,244 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimatedTexture.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimatedTexture.xml. .. _class_AnimatedTexture: AnimatedTexture =============== -**Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Deprecated:** This class does not work properly in current versions and may be removed in the future. There is currently no equivalent workaround. + +**Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Proxy texture for simple frame-based animations. +.. rst-class:: classref-introduction-group + Description ----------- -``AnimatedTexture`` is a resource format for frame-based animations, where multiple textures can be chained automatically with a predefined delay for each frame. Unlike :ref:`AnimationPlayer` or :ref:`AnimatedSprite`, it isn't a :ref:`Node`, but has the advantage of being usable anywhere a :ref:`Texture2D` resource can be used, e.g. in a :ref:`TileSet`. +**AnimatedTexture** is a resource format for frame-based animations, where multiple textures can be chained automatically with a predefined delay for each frame. Unlike :ref:`AnimationPlayer` or :ref:`AnimatedSprite2D`, it isn't a :ref:`Node`, but has the advantage of being usable anywhere a :ref:`Texture2D` resource can be used, e.g. in a :ref:`TileSet`. + +The playback of the animation is controlled by the :ref:`speed_scale` property, as well as each frame's duration (see :ref:`set_frame_duration()`). The animation loops, i.e. it will restart at frame 0 automatically after playing the last frame. + +\ **AnimatedTexture** currently requires all frame textures to have the same size, otherwise the bigger ones will be cropped to match the smallest one. -The playback of the animation is controlled by the :ref:`fps` property as well as each frame's optional delay (see :ref:`set_frame_delay`). The animation loops, i.e. it will restart at frame 0 automatically after playing the last frame. +\ **Note:** AnimatedTexture doesn't support using :ref:`AtlasTexture`\ s. Each frame needs to be a separate :ref:`Texture2D`. -``AnimatedTexture`` currently requires all frame textures to have the same size, otherwise the bigger ones will be cropped to match the smallest one. Also, it doesn't support :ref:`AtlasTexture`. Each frame needs to be separate image. +\ **Warning:** The current implementation is not efficient for the modern renderers. + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+------------------------------------------------------+---------+ -| :ref:`float` | :ref:`fps` | ``4.0`` | -+---------------------------+------------------------------------------------------+---------+ -| :ref:`int` | :ref:`frames` | ``1`` | -+---------------------------+------------------------------------------------------+---------+ +.. table:: + :widths: auto + + +---------------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`current_frame` | | + +---------------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`frames` | ``1`` | + +---------------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`one_shot` | ``false`` | + +---------------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`pause` | ``false`` | + +---------------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | resource_local_to_scene | ``false`` (overrides :ref:`Resource`) | + +---------------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`speed_scale` | ``1.0`` | + +---------------------------+--------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_frame_delay` **(** :ref:`int` frame **)** const | -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Texture2D` | :ref:`get_frame_texture` **(** :ref:`int` frame **)** const | -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_frame_delay` **(** :ref:`int` frame, :ref:`float` delay **)** | -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_frame_texture` **(** :ref:`int` frame, :ref:`Texture2D` texture **)** | -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_frame_duration`\ (\ frame\: :ref:`int`\ ) |const| | + +-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`get_frame_texture`\ (\ frame\: :ref:`int`\ ) |const| | + +-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_frame_duration`\ (\ frame\: :ref:`int`, duration\: :ref:`float`\ ) | + +-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_frame_texture`\ (\ frame\: :ref:`int`, texture\: :ref:`Texture2D`\ ) | + +-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Constants --------- .. _class_AnimatedTexture_constant_MAX_FRAMES: -- **MAX_FRAMES** = **256** --- The maximum number of frames supported by ``AnimatedTexture``. If you need more frames in your animation, use :ref:`AnimationPlayer` or :ref:`AnimatedSprite`. +.. rst-class:: classref-constant + +**MAX_FRAMES** = ``256`` :ref:`🔗` + +The maximum number of frames supported by **AnimatedTexture**. If you need more frames in your animation, use :ref:`AnimationPlayer` or :ref:`AnimatedSprite2D`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- -.. _class_AnimatedTexture_property_fps: +.. _class_AnimatedTexture_property_current_frame: + +.. rst-class:: classref-property -- :ref:`float` **fps** +:ref:`int` **current_frame** :ref:`🔗` -+-----------+----------------+ -| *Default* | ``4.0`` | -+-----------+----------------+ -| *Setter* | set_fps(value) | -+-----------+----------------+ -| *Getter* | get_fps() | -+-----------+----------------+ +.. rst-class:: classref-property-setget -Animation speed in frames per second. This value defines the default time interval between two frames of the animation, and thus the overall duration of the animation loop based on the :ref:`frames` property. A value of 0 means no predefined number of frames per second, the animation will play according to each frame's frame delay (see :ref:`set_frame_delay`). +- |void| **set_current_frame**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_current_frame**\ (\ ) -For example, an animation with 8 frames, no frame delay and a ``fps`` value of 2 will run for 4 seconds, with each frame lasting 0.5 seconds. +Sets the currently visible frame of the texture. Setting this frame while playing resets the current frame time, so the newly selected frame plays for its whole configured frame duration. + +.. rst-class:: classref-item-separator ---- .. _class_AnimatedTexture_property_frames: -- :ref:`int` **frames** +.. rst-class:: classref-property + +:ref:`int` **frames** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_frames**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_frames**\ (\ ) + +Number of frames to use in the animation. While you can create the frames independently with :ref:`set_frame_texture()`, you need to set this value for the animation to take new frames into account. The maximum number of frames is :ref:`MAX_FRAMES`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedTexture_property_one_shot: + +.. rst-class:: classref-property + +:ref:`bool` **one_shot** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------+ -| *Default* | ``1`` | -+-----------+-------------------+ -| *Setter* | set_frames(value) | -+-----------+-------------------+ -| *Getter* | get_frames() | -+-----------+-------------------+ +- |void| **set_one_shot**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_one_shot**\ (\ ) -Number of frames to use in the animation. While you can create the frames independently with :ref:`set_frame_texture`, you need to set this value for the animation to take new frames into account. The maximum number of frames is :ref:`MAX_FRAMES`. +If ``true``, the animation will only play once and will not loop back to the first frame after reaching the end. Note that reaching the end will not set :ref:`pause` to ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedTexture_property_pause: + +.. rst-class:: classref-property + +:ref:`bool` **pause** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pause**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_pause**\ (\ ) + +If ``true``, the animation will pause where it currently is (i.e. at :ref:`current_frame`). The animation will continue from where it was paused when changing this property to ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimatedTexture_property_speed_scale: + +.. rst-class:: classref-property + +:ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_speed_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_speed_scale**\ (\ ) + +The animation speed is multiplied by this value. If set to a negative value, the animation is played in reverse. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_AnimatedTexture_method_get_frame_delay: +.. _class_AnimatedTexture_method_get_frame_duration: + +.. rst-class:: classref-method -- :ref:`float` **get_frame_delay** **(** :ref:`int` frame **)** const +:ref:`float` **get_frame_duration**\ (\ frame\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the given frame's delay value. +Returns the given ``frame``'s duration, in seconds. + +.. rst-class:: classref-item-separator ---- .. _class_AnimatedTexture_method_get_frame_texture: -- :ref:`Texture2D` **get_frame_texture** **(** :ref:`int` frame **)** const +.. rst-class:: classref-method + +:ref:`Texture2D` **get_frame_texture**\ (\ frame\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given frame's :ref:`Texture2D`. ----- +.. rst-class:: classref-item-separator -.. _class_AnimatedTexture_method_set_frame_delay: +---- -- void **set_frame_delay** **(** :ref:`int` frame, :ref:`float` delay **)** +.. _class_AnimatedTexture_method_set_frame_duration: -Sets an additional delay (in seconds) between this frame and the next one, that will be added to the time interval defined by :ref:`fps`. By default, frames have no delay defined. If a delay value is defined, the final time interval between this frame and the next will be ``1.0 / fps + delay``. +.. rst-class:: classref-method -For example, for an animation with 3 frames, 2 FPS and a frame delay on the second frame of 1.2, the resulting playback will be: +|void| **set_frame_duration**\ (\ frame\: :ref:`int`, duration\: :ref:`float`\ ) :ref:`🔗` -:: +Sets the duration of any given ``frame``. The final duration is affected by the :ref:`speed_scale`. If set to ``0``, the frame is skipped during playback. - Frame 0: 0.5 s (1 / fps) - Frame 1: 1.7 s (1 / fps + 1.2) - Frame 2: 0.5 s (1 / fps) - Total duration: 2.7 s +.. rst-class:: classref-item-separator ---- .. _class_AnimatedTexture_method_set_frame_texture: -- void **set_frame_texture** **(** :ref:`int` frame, :ref:`Texture2D` texture **)** +.. rst-class:: classref-method + +|void| **set_frame_texture**\ (\ frame\: :ref:`int`, texture\: :ref:`Texture2D`\ ) :ref:`🔗` Assigns a :ref:`Texture2D` to the given frame. Frame IDs start at 0, so the first frame has ID 0, and the last frame of the animation has ID :ref:`frames` - 1. You can define any number of textures up to :ref:`MAX_FRAMES`, but keep in mind that only frames from 0 to :ref:`frames` - 1 will be part of the animation. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animation.rst b/classes/class_animation.rst index ac50bd6a357..da4032bc928 100644 --- a/classes/class_animation.rst +++ b/classes/class_animation.rst @@ -1,775 +1,1566 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Animation.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Animation.xml. .. _class_Animation: Animation ========= -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Contains data used to animate everything in the engine. +Holds data that can be used to animate anything in the engine. + +.. rst-class:: classref-introduction-group Description ----------- -An Animation resource contains data used to animate everything in the engine. Animations are divided into tracks, and each track must be linked to a node. The state of that node can be changed through time, by adding timed keys (events) to the track. +This resource holds data that can be used to animate anything in the engine. Animations are divided into tracks and each track must be linked to a node. The state of that node can be changed through time, by adding timed keys (events) to the track. + -:: +.. tabs:: + + .. code-tab:: gdscript # This creates an animation that makes the node "Enemy" move to the right by - # 100 pixels in 1 second. + # 100 pixels in 2.0 seconds. var animation = Animation.new() var track_index = animation.add_track(Animation.TYPE_VALUE) animation.track_set_path(track_index, "Enemy:position:x") animation.track_insert_key(track_index, 0.0, 0) - animation.track_insert_key(track_index, 0.5, 100) + animation.track_insert_key(track_index, 2.0, 100) + animation.length = 2.0 + + .. code-tab:: csharp + + // This creates an animation that makes the node "Enemy" move to the right by + // 100 pixels in 2.0 seconds. + var animation = new Animation(); + int trackIndex = animation.AddTrack(Animation.TrackType.Value); + animation.TrackSetPath(trackIndex, "Enemy:position:x"); + animation.TrackInsertKey(trackIndex, 0.0f, 0); + animation.TrackInsertKey(trackIndex, 2.0f, 100); + animation.Length = 2.0f; + + Animations are just data containers, and must be added to nodes such as an :ref:`AnimationPlayer` to be played back. Animation tracks have different types, each with its own set of dedicated methods. Check :ref:`TrackType` to see available types. +\ **Note:** For 3D position/rotation/scale, using the dedicated :ref:`TYPE_POSITION_3D`, :ref:`TYPE_ROTATION_3D` and :ref:`TYPE_SCALE_3D` track types instead of :ref:`TYPE_VALUE` is recommended for performance reasons. + +.. rst-class:: classref-introduction-group + Tutorials --------- -- :doc:`../tutorials/animation/index` +- :doc:`Animation documentation index <../tutorials/animation/index>` + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+------------------------------------------------+-----------+ -| :ref:`float` | :ref:`length` | ``1.0`` | -+---------------------------+------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`loop` | ``false`` | -+---------------------------+------------------------------------------------+-----------+ -| :ref:`float` | :ref:`step` | ``0.1`` | -+---------------------------+------------------------------------------------+-----------+ +.. table:: + :widths: auto -Methods -------- + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + | :ref:`bool` | :ref:`capture_included` | ``false`` | + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + | :ref:`float` | :ref:`length` | ``1.0`` | + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + | :ref:`LoopMode` | :ref:`loop_mode` | ``0`` | + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + | :ref:`float` | :ref:`step` | ``0.033333335`` | + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + +.. rst-class:: classref-reftable-group -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`add_track` **(** :ref:`TrackType` type, :ref:`int` at_position=-1 **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`animation_track_get_key_animation` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`animation_track_insert_key` **(** :ref:`int` track_idx, :ref:`float` time, :ref:`StringName` animation **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`animation_track_set_key_animation` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`StringName` animation **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`audio_track_get_key_end_offset` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`audio_track_get_key_start_offset` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Resource` | :ref:`audio_track_get_key_stream` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`audio_track_insert_key` **(** :ref:`int` track_idx, :ref:`float` time, :ref:`Resource` stream, :ref:`float` start_offset=0, :ref:`float` end_offset=0 **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`audio_track_set_key_end_offset` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` offset **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`audio_track_set_key_start_offset` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` offset **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`audio_track_set_key_stream` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`Resource` stream **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`bezier_track_get_key_in_handle` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`bezier_track_get_key_out_handle` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`bezier_track_get_key_value` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`bezier_track_insert_key` **(** :ref:`int` track_idx, :ref:`float` time, :ref:`float` value, :ref:`Vector2` in_handle=Vector2( 0, 0 ), :ref:`Vector2` out_handle=Vector2( 0, 0 ) **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`bezier_track_interpolate` **(** :ref:`int` track_idx, :ref:`float` time **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`bezier_track_set_key_in_handle` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`Vector2` in_handle **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`bezier_track_set_key_out_handle` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`Vector2` out_handle **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`bezier_track_set_key_value` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` value **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear` **(** **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`copy_track` **(** :ref:`int` track_idx, :ref:`Animation` to_animation **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`find_track` **(** :ref:`NodePath` path **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_track_count` **(** **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedInt32Array` | :ref:`method_track_get_key_indices` **(** :ref:`int` track_idx, :ref:`float` time_sec, :ref:`float` delta **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`method_track_get_name` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`method_track_get_params` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_track` **(** :ref:`int` track_idx **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`track_find_key` **(** :ref:`int` track_idx, :ref:`float` time, :ref:`bool` exact=false **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`track_get_interpolation_loop_wrap` **(** :ref:`int` track_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`InterpolationType` | :ref:`track_get_interpolation_type` **(** :ref:`int` track_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`track_get_key_count` **(** :ref:`int` track_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`track_get_key_time` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`track_get_key_transition` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`track_get_key_value` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`NodePath` | :ref:`track_get_path` **(** :ref:`int` track_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`TrackType` | :ref:`track_get_type` **(** :ref:`int` track_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_insert_key` **(** :ref:`int` track_idx, :ref:`float` time, :ref:`Variant` key, :ref:`float` transition=1 **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`track_is_enabled` **(** :ref:`int` track_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`track_is_imported` **(** :ref:`int` track_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_move_down` **(** :ref:`int` track_idx **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_move_to` **(** :ref:`int` track_idx, :ref:`int` to_idx **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_move_up` **(** :ref:`int` track_idx **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_remove_key` **(** :ref:`int` track_idx, :ref:`int` key_idx **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_remove_key_at_position` **(** :ref:`int` track_idx, :ref:`float` position **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_set_enabled` **(** :ref:`int` track_idx, :ref:`bool` enabled **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_set_imported` **(** :ref:`int` track_idx, :ref:`bool` imported **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_set_interpolation_loop_wrap` **(** :ref:`int` track_idx, :ref:`bool` interpolation **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_set_interpolation_type` **(** :ref:`int` track_idx, :ref:`InterpolationType` interpolation **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_set_key_time` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` time **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_set_key_transition` **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` transition **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_set_key_value` **(** :ref:`int` track_idx, :ref:`int` key, :ref:`Variant` value **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_set_path` **(** :ref:`int` track_idx, :ref:`NodePath` path **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`track_swap` **(** :ref:`int` track_idx, :ref:`int` with_idx **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`transform_track_insert_key` **(** :ref:`int` track_idx, :ref:`float` time, :ref:`Vector3` location, :ref:`Quat` rotation, :ref:`Vector3` scale **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`transform_track_interpolate` **(** :ref:`int` track_idx, :ref:`float` time_sec **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedInt32Array` | :ref:`value_track_get_key_indices` **(** :ref:`int` track_idx, :ref:`float` time_sec, :ref:`float` delta **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`UpdateMode` | :ref:`value_track_get_update_mode` **(** :ref:`int` track_idx **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`value_track_set_update_mode` **(** :ref:`int` track_idx, :ref:`UpdateMode` mode **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Signals +Methods ------- -.. _class_Animation_signal_tracks_changed: +.. table:: + :widths: auto + + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_marker`\ (\ name\: :ref:`StringName`, time\: :ref:`float`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`add_track`\ (\ type\: :ref:`TrackType`, at_position\: :ref:`int` = -1\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`animation_track_get_key_animation`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`animation_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, animation\: :ref:`StringName`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`animation_track_set_key_animation`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, animation\: :ref:`StringName`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`audio_track_get_key_end_offset`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`audio_track_get_key_start_offset`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Resource` | :ref:`audio_track_get_key_stream`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`audio_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, stream\: :ref:`Resource`, start_offset\: :ref:`float` = 0, end_offset\: :ref:`float` = 0\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`audio_track_is_use_blend`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`audio_track_set_key_end_offset`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, offset\: :ref:`float`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`audio_track_set_key_start_offset`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, offset\: :ref:`float`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`audio_track_set_key_stream`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, stream\: :ref:`Resource`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`audio_track_set_use_blend`\ (\ track_idx\: :ref:`int`, enable\: :ref:`bool`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`bezier_track_get_key_in_handle`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`bezier_track_get_key_out_handle`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`bezier_track_get_key_value`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`bezier_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, value\: :ref:`float`, in_handle\: :ref:`Vector2` = Vector2(0, 0), out_handle\: :ref:`Vector2` = Vector2(0, 0)\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`bezier_track_interpolate`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`bezier_track_set_key_in_handle`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, in_handle\: :ref:`Vector2`, balanced_value_time_ratio\: :ref:`float` = 1.0\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`bezier_track_set_key_out_handle`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, out_handle\: :ref:`Vector2`, balanced_value_time_ratio\: :ref:`float` = 1.0\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`bezier_track_set_key_value`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, value\: :ref:`float`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`blend_shape_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, amount\: :ref:`float`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`blend_shape_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear`\ (\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`compress`\ (\ page_size\: :ref:`int` = 8192, fps\: :ref:`int` = 120, split_tolerance\: :ref:`float` = 4.0\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`copy_track`\ (\ track_idx\: :ref:`int`, to_animation\: :ref:`Animation`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`find_track`\ (\ path\: :ref:`NodePath`, type\: :ref:`TrackType`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_marker_at_time`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`get_marker_color`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_marker_names`\ (\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_marker_time`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_next_marker`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_prev_marker`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_track_count`\ (\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_marker`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`method_track_get_name`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`method_track_get_params`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`optimize`\ (\ allowed_velocity_err\: :ref:`float` = 0.01, allowed_angular_err\: :ref:`float` = 0.01, precision\: :ref:`int` = 3\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`position_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, position\: :ref:`Vector3`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`position_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_marker`\ (\ name\: :ref:`StringName`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_track`\ (\ track_idx\: :ref:`int`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rotation_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, rotation\: :ref:`Quaternion`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Quaternion` | :ref:`rotation_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`scale_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, scale\: :ref:`Vector3`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`scale_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_marker_color`\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`track_find_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, find_mode\: :ref:`FindMode` = 0, limit\: :ref:`bool` = false, backward\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`track_get_interpolation_loop_wrap`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`InterpolationType` | :ref:`track_get_interpolation_type`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`track_get_key_count`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`track_get_key_time`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`track_get_key_transition`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`track_get_key_value`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`track_get_path`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`TrackType` | :ref:`track_get_type`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, key\: :ref:`Variant`, transition\: :ref:`float` = 1\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`track_is_compressed`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`track_is_enabled`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`track_is_imported`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_move_down`\ (\ track_idx\: :ref:`int`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_move_to`\ (\ track_idx\: :ref:`int`, to_idx\: :ref:`int`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_move_up`\ (\ track_idx\: :ref:`int`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_remove_key`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_remove_key_at_time`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_set_enabled`\ (\ track_idx\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_set_imported`\ (\ track_idx\: :ref:`int`, imported\: :ref:`bool`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_set_interpolation_loop_wrap`\ (\ track_idx\: :ref:`int`, interpolation\: :ref:`bool`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_set_interpolation_type`\ (\ track_idx\: :ref:`int`, interpolation\: :ref:`InterpolationType`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_set_key_time`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, time\: :ref:`float`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_set_key_transition`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, transition\: :ref:`float`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_set_key_value`\ (\ track_idx\: :ref:`int`, key\: :ref:`int`, value\: :ref:`Variant`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_set_path`\ (\ track_idx\: :ref:`int`, path\: :ref:`NodePath`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`track_swap`\ (\ track_idx\: :ref:`int`, with_idx\: :ref:`int`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`UpdateMode` | :ref:`value_track_get_update_mode`\ (\ track_idx\: :ref:`int`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`value_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`value_track_set_update_mode`\ (\ track_idx\: :ref:`int`, mode\: :ref:`UpdateMode`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator -- **tracks_changed** **(** **)** +---- -Emitted when there's a change in the list of tracks, e.g. tracks are added, moved or have changed paths. +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_Animation_TrackType: +.. rst-class:: classref-enumeration + +enum **TrackType**: :ref:`🔗` + .. _class_Animation_constant_TYPE_VALUE: -.. _class_Animation_constant_TYPE_TRANSFORM: +.. rst-class:: classref-enumeration-constant + +:ref:`TrackType` **TYPE_VALUE** = ``0`` + +Value tracks set values in node properties, but only those which can be interpolated. For 3D position/rotation/scale, using the dedicated :ref:`TYPE_POSITION_3D`, :ref:`TYPE_ROTATION_3D` and :ref:`TYPE_SCALE_3D` track types instead of :ref:`TYPE_VALUE` is recommended for performance reasons. + +.. _class_Animation_constant_TYPE_POSITION_3D: + +.. rst-class:: classref-enumeration-constant + +:ref:`TrackType` **TYPE_POSITION_3D** = ``1`` + +3D position track (values are stored in :ref:`Vector3`\ s). + +.. _class_Animation_constant_TYPE_ROTATION_3D: + +.. rst-class:: classref-enumeration-constant + +:ref:`TrackType` **TYPE_ROTATION_3D** = ``2`` + +3D rotation track (values are stored in :ref:`Quaternion`\ s). + +.. _class_Animation_constant_TYPE_SCALE_3D: + +.. rst-class:: classref-enumeration-constant + +:ref:`TrackType` **TYPE_SCALE_3D** = ``3`` + +3D scale track (values are stored in :ref:`Vector3`\ s). + +.. _class_Animation_constant_TYPE_BLEND_SHAPE: + +.. rst-class:: classref-enumeration-constant + +:ref:`TrackType` **TYPE_BLEND_SHAPE** = ``4`` + +Blend shape track. .. _class_Animation_constant_TYPE_METHOD: +.. rst-class:: classref-enumeration-constant + +:ref:`TrackType` **TYPE_METHOD** = ``5`` + +Method tracks call functions with given arguments per key. + .. _class_Animation_constant_TYPE_BEZIER: +.. rst-class:: classref-enumeration-constant + +:ref:`TrackType` **TYPE_BEZIER** = ``6`` + +Bezier tracks are used to interpolate a value using custom curves. They can also be used to animate sub-properties of vectors and colors (e.g. alpha value of a :ref:`Color`). + .. _class_Animation_constant_TYPE_AUDIO: -.. _class_Animation_constant_TYPE_ANIMATION: +.. rst-class:: classref-enumeration-constant -enum **TrackType**: +:ref:`TrackType` **TYPE_AUDIO** = ``7`` -- **TYPE_VALUE** = **0** --- Value tracks set values in node properties, but only those which can be Interpolated. +Audio tracks are used to play an audio stream with either type of :ref:`AudioStreamPlayer`. The stream can be trimmed and previewed in the animation. -- **TYPE_TRANSFORM** = **1** --- Transform tracks are used to change node local transforms or skeleton pose bones. Transitions are interpolated. +.. _class_Animation_constant_TYPE_ANIMATION: -- **TYPE_METHOD** = **2** --- Method tracks call functions with given arguments per key. +.. rst-class:: classref-enumeration-constant -- **TYPE_BEZIER** = **3** --- Bezier tracks are used to interpolate a value using custom curves. They can also be used to animate sub-properties of vectors and colors (e.g. alpha value of a :ref:`Color`). +:ref:`TrackType` **TYPE_ANIMATION** = ``8`` -- **TYPE_AUDIO** = **4** --- Audio tracks are used to play an audio stream with either type of :ref:`AudioStreamPlayer`. The stream can be trimmed and previewed in the animation. +Animation tracks play animations in other :ref:`AnimationPlayer` nodes. -- **TYPE_ANIMATION** = **5** --- Animation tracks play animations in other :ref:`AnimationPlayer` nodes. +.. rst-class:: classref-item-separator ---- .. _enum_Animation_InterpolationType: +.. rst-class:: classref-enumeration + +enum **InterpolationType**: :ref:`🔗` + .. _class_Animation_constant_INTERPOLATION_NEAREST: +.. rst-class:: classref-enumeration-constant + +:ref:`InterpolationType` **INTERPOLATION_NEAREST** = ``0`` + +No interpolation (nearest value). + .. _class_Animation_constant_INTERPOLATION_LINEAR: +.. rst-class:: classref-enumeration-constant + +:ref:`InterpolationType` **INTERPOLATION_LINEAR** = ``1`` + +Linear interpolation. + .. _class_Animation_constant_INTERPOLATION_CUBIC: -enum **InterpolationType**: +.. rst-class:: classref-enumeration-constant + +:ref:`InterpolationType` **INTERPOLATION_CUBIC** = ``2`` + +Cubic interpolation. This looks smoother than linear interpolation, but is more expensive to interpolate. Stick to :ref:`INTERPOLATION_LINEAR` for complex 3D animations imported from external software, even if it requires using a higher animation framerate in return. -- **INTERPOLATION_NEAREST** = **0** --- No interpolation (nearest value). +.. _class_Animation_constant_INTERPOLATION_LINEAR_ANGLE: -- **INTERPOLATION_LINEAR** = **1** --- Linear interpolation. +.. rst-class:: classref-enumeration-constant -- **INTERPOLATION_CUBIC** = **2** --- Cubic interpolation. +:ref:`InterpolationType` **INTERPOLATION_LINEAR_ANGLE** = ``3`` + +Linear interpolation with shortest path rotation. + +\ **Note:** The result value is always normalized and may not match the key value. + +.. _class_Animation_constant_INTERPOLATION_CUBIC_ANGLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`InterpolationType` **INTERPOLATION_CUBIC_ANGLE** = ``4`` + +Cubic interpolation with shortest path rotation. + +\ **Note:** The result value is always normalized and may not match the key value. + +.. rst-class:: classref-item-separator ---- .. _enum_Animation_UpdateMode: +.. rst-class:: classref-enumeration + +enum **UpdateMode**: :ref:`🔗` + .. _class_Animation_constant_UPDATE_CONTINUOUS: +.. rst-class:: classref-enumeration-constant + +:ref:`UpdateMode` **UPDATE_CONTINUOUS** = ``0`` + +Update between keyframes and hold the value. + .. _class_Animation_constant_UPDATE_DISCRETE: -.. _class_Animation_constant_UPDATE_TRIGGER: +.. rst-class:: classref-enumeration-constant + +:ref:`UpdateMode` **UPDATE_DISCRETE** = ``1`` + +Update at the keyframes. .. _class_Animation_constant_UPDATE_CAPTURE: -enum **UpdateMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`UpdateMode` **UPDATE_CAPTURE** = ``2`` + +Same as :ref:`UPDATE_CONTINUOUS` but works as a flag to capture the value of the current object and perform interpolation in some methods. See also :ref:`AnimationMixer.capture()`, :ref:`AnimationPlayer.playback_auto_capture`, and :ref:`AnimationPlayer.play_with_capture()`. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Animation_LoopMode: + +.. rst-class:: classref-enumeration + +enum **LoopMode**: :ref:`🔗` + +.. _class_Animation_constant_LOOP_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopMode` **LOOP_NONE** = ``0`` -- **UPDATE_CONTINUOUS** = **0** --- Update between keyframes. +At both ends of the animation, the animation will stop playing. -- **UPDATE_DISCRETE** = **1** --- Update at the keyframes and hold the value. +.. _class_Animation_constant_LOOP_LINEAR: -- **UPDATE_TRIGGER** = **2** --- Update at the keyframes. +.. rst-class:: classref-enumeration-constant -- **UPDATE_CAPTURE** = **3** --- Same as linear interpolation, but also interpolates from the current value (i.e. dynamically at runtime) if the first key isn't at 0 seconds. +:ref:`LoopMode` **LOOP_LINEAR** = ``1`` + +At both ends of the animation, the animation will be repeated without changing the playback direction. + +.. _class_Animation_constant_LOOP_PINGPONG: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopMode` **LOOP_PINGPONG** = ``2`` + +Repeats playback and reverse playback at both ends of the animation. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Animation_LoopedFlag: + +.. rst-class:: classref-enumeration + +enum **LoopedFlag**: :ref:`🔗` + +.. _class_Animation_constant_LOOPED_FLAG_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopedFlag` **LOOPED_FLAG_NONE** = ``0`` + +This flag indicates that the animation proceeds without any looping. + +.. _class_Animation_constant_LOOPED_FLAG_END: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopedFlag` **LOOPED_FLAG_END** = ``1`` + +This flag indicates that the animation has reached the end of the animation and just after loop processed. + +.. _class_Animation_constant_LOOPED_FLAG_START: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopedFlag` **LOOPED_FLAG_START** = ``2`` + +This flag indicates that the animation has reached the start of the animation and just after loop processed. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Animation_FindMode: + +.. rst-class:: classref-enumeration + +enum **FindMode**: :ref:`🔗` + +.. _class_Animation_constant_FIND_MODE_NEAREST: + +.. rst-class:: classref-enumeration-constant + +:ref:`FindMode` **FIND_MODE_NEAREST** = ``0`` + +Finds the nearest time key. + +.. _class_Animation_constant_FIND_MODE_APPROX: + +.. rst-class:: classref-enumeration-constant + +:ref:`FindMode` **FIND_MODE_APPROX** = ``1`` + +Finds only the key with approximating the time. + +.. _class_Animation_constant_FIND_MODE_EXACT: + +.. rst-class:: classref-enumeration-constant + +:ref:`FindMode` **FIND_MODE_EXACT** = ``2`` + +Finds only the key with matching the time. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- +.. _class_Animation_property_capture_included: + +.. rst-class:: classref-property + +:ref:`bool` **capture_included** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`bool` **is_capture_included**\ (\ ) + +Returns ``true`` if the capture track is included. This is a cached readonly value for performance. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_property_length: -- :ref:`float` **length** +.. rst-class:: classref-property + +:ref:`float` **length** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------+ -| *Setter* | set_length(value) | -+-----------+-------------------+ -| *Getter* | get_length() | -+-----------+-------------------+ +- |void| **set_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_length**\ (\ ) The total length of the animation (in seconds). -**Note:** Length is not delimited by the last key, as this one may be before or after the end to ensure correct interpolation and looping. +\ **Note:** Length is not delimited by the last key, as this one may be before or after the end to ensure correct interpolation and looping. + +.. rst-class:: classref-item-separator ---- -.. _class_Animation_property_loop: +.. _class_Animation_property_loop_mode: + +.. rst-class:: classref-property + +:ref:`LoopMode` **loop_mode** = ``0`` :ref:`🔗` -- :ref:`bool` **loop** +.. rst-class:: classref-property-setget -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_loop(value) | -+-----------+-----------------+ -| *Getter* | has_loop() | -+-----------+-----------------+ +- |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode`\ ) +- :ref:`LoopMode` **get_loop_mode**\ (\ ) -A flag indicating that the animation must loop. This is uses for correct interpolation of animation cycles, and for hinting the player that it must restart the animation. +Determines the behavior of both ends of the animation timeline during animation playback. This indicates whether and how the animation should be restarted, and is also used to correctly interpolate animation cycles. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_property_step: -- :ref:`float` **step** +.. rst-class:: classref-property + +:ref:`float` **step** = ``0.033333335`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------+ -| *Default* | ``0.1`` | -+-----------+-----------------+ -| *Setter* | set_step(value) | -+-----------+-----------------+ -| *Getter* | get_step() | -+-----------+-----------------+ +- |void| **set_step**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_step**\ (\ ) The animation step value. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- +.. _class_Animation_method_add_marker: + +.. rst-class:: classref-method + +|void| **add_marker**\ (\ name\: :ref:`StringName`, time\: :ref:`float`\ ) :ref:`🔗` + +Adds a marker to this Animation. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_add_track: -- :ref:`int` **add_track** **(** :ref:`TrackType` type, :ref:`int` at_position=-1 **)** +.. rst-class:: classref-method + +:ref:`int` **add_track**\ (\ type\: :ref:`TrackType`, at_position\: :ref:`int` = -1\ ) :ref:`🔗` Adds a track to the Animation. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_animation_track_get_key_animation: -- :ref:`StringName` **animation_track_get_key_animation** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`StringName` **animation_track_get_key_animation**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the animation name at the key identified by ``key_idx``. The ``track_idx`` must be the index of an Animation Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_animation_track_insert_key: -- :ref:`int` **animation_track_insert_key** **(** :ref:`int` track_idx, :ref:`float` time, :ref:`StringName` animation **)** +.. rst-class:: classref-method + +:ref:`int` **animation_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, animation\: :ref:`StringName`\ ) :ref:`🔗` Inserts a key with value ``animation`` at the given ``time`` (in seconds). The ``track_idx`` must be the index of an Animation Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_animation_track_set_key_animation: -- void **animation_track_set_key_animation** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`StringName` animation **)** +.. rst-class:: classref-method + +|void| **animation_track_set_key_animation**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, animation\: :ref:`StringName`\ ) :ref:`🔗` Sets the key identified by ``key_idx`` to value ``animation``. The ``track_idx`` must be the index of an Animation Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_audio_track_get_key_end_offset: -- :ref:`float` **audio_track_get_key_end_offset** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **audio_track_get_key_end_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the end offset of the key identified by ``key_idx``. The ``track_idx`` must be the index of an Audio Track. End offset is the number of seconds cut off at the ending of the audio stream. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_audio_track_get_key_start_offset: -- :ref:`float` **audio_track_get_key_start_offset** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **audio_track_get_key_start_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the start offset of the key identified by ``key_idx``. The ``track_idx`` must be the index of an Audio Track. Start offset is the number of seconds cut off at the beginning of the audio stream. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_audio_track_get_key_stream: -- :ref:`Resource` **audio_track_get_key_stream** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`Resource` **audio_track_get_key_stream**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the audio stream of the key identified by ``key_idx``. The ``track_idx`` must be the index of an Audio Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_audio_track_insert_key: -- :ref:`int` **audio_track_insert_key** **(** :ref:`int` track_idx, :ref:`float` time, :ref:`Resource` stream, :ref:`float` start_offset=0, :ref:`float` end_offset=0 **)** +.. rst-class:: classref-method + +:ref:`int` **audio_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, stream\: :ref:`Resource`, start_offset\: :ref:`float` = 0, end_offset\: :ref:`float` = 0\ ) :ref:`🔗` Inserts an Audio Track key at the given ``time`` in seconds. The ``track_idx`` must be the index of an Audio Track. -``stream`` is the :ref:`AudioStream` resource to play. ``start_offset`` is the number of seconds cut off at the beginning of the audio stream, while ``end_offset`` is at the ending. +\ ``stream`` is the :ref:`AudioStream` resource to play. ``start_offset`` is the number of seconds cut off at the beginning of the audio stream, while ``end_offset`` is at the ending. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_audio_track_is_use_blend: + +.. rst-class:: classref-method + +:ref:`bool` **audio_track_is_use_blend**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the track at ``track_idx`` will be blended with other animations. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_audio_track_set_key_end_offset: -- void **audio_track_set_key_end_offset** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` offset **)** +.. rst-class:: classref-method + +|void| **audio_track_set_key_end_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, offset\: :ref:`float`\ ) :ref:`🔗` Sets the end offset of the key identified by ``key_idx`` to value ``offset``. The ``track_idx`` must be the index of an Audio Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_audio_track_set_key_start_offset: -- void **audio_track_set_key_start_offset** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` offset **)** +.. rst-class:: classref-method + +|void| **audio_track_set_key_start_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, offset\: :ref:`float`\ ) :ref:`🔗` Sets the start offset of the key identified by ``key_idx`` to value ``offset``. The ``track_idx`` must be the index of an Audio Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_audio_track_set_key_stream: -- void **audio_track_set_key_stream** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`Resource` stream **)** +.. rst-class:: classref-method + +|void| **audio_track_set_key_stream**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, stream\: :ref:`Resource`\ ) :ref:`🔗` + +Sets the stream of the key identified by ``key_idx`` to value ``stream``. The ``track_idx`` must be the index of an Audio Track. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_audio_track_set_use_blend: + +.. rst-class:: classref-method + +|void| **audio_track_set_use_blend**\ (\ track_idx\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` -Sets the stream of the key identified by ``key_idx`` to value ``offset``. The ``track_idx`` must be the index of an Audio Track. +Sets whether the track will be blended with other animations. If ``true``, the audio playback volume changes depending on the blend value. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_bezier_track_get_key_in_handle: -- :ref:`Vector2` **bezier_track_get_key_in_handle** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **bezier_track_get_key_in_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the in handle of the key identified by ``key_idx``. The ``track_idx`` must be the index of a Bezier Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_bezier_track_get_key_out_handle: -- :ref:`Vector2` **bezier_track_get_key_out_handle** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **bezier_track_get_key_out_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the out handle of the key identified by ``key_idx``. The ``track_idx`` must be the index of a Bezier Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_bezier_track_get_key_value: -- :ref:`float` **bezier_track_get_key_value** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **bezier_track_get_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the value of the key identified by ``key_idx``. The ``track_idx`` must be the index of a Bezier Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_bezier_track_insert_key: -- :ref:`int` **bezier_track_insert_key** **(** :ref:`int` track_idx, :ref:`float` time, :ref:`float` value, :ref:`Vector2` in_handle=Vector2( 0, 0 ), :ref:`Vector2` out_handle=Vector2( 0, 0 ) **)** +.. rst-class:: classref-method + +:ref:`int` **bezier_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, value\: :ref:`float`, in_handle\: :ref:`Vector2` = Vector2(0, 0), out_handle\: :ref:`Vector2` = Vector2(0, 0)\ ) :ref:`🔗` Inserts a Bezier Track key at the given ``time`` in seconds. The ``track_idx`` must be the index of a Bezier Track. -``in_handle`` is the left-side weight of the added Bezier curve point, ``out_handle`` is the right-side one, while ``value`` is the actual value at this point. +\ ``in_handle`` is the left-side weight of the added Bezier curve point, ``out_handle`` is the right-side one, while ``value`` is the actual value at this point. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_bezier_track_interpolate: -- :ref:`float` **bezier_track_interpolate** **(** :ref:`int` track_idx, :ref:`float` time **)** const +.. rst-class:: classref-method + +:ref:`float` **bezier_track_interpolate**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`\ ) |const| :ref:`🔗` Returns the interpolated value at the given ``time`` (in seconds). The ``track_idx`` must be the index of a Bezier Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_bezier_track_set_key_in_handle: -- void **bezier_track_set_key_in_handle** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`Vector2` in_handle **)** +.. rst-class:: classref-method + +|void| **bezier_track_set_key_in_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, in_handle\: :ref:`Vector2`, balanced_value_time_ratio\: :ref:`float` = 1.0\ ) :ref:`🔗` Sets the in handle of the key identified by ``key_idx`` to value ``in_handle``. The ``track_idx`` must be the index of a Bezier Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_bezier_track_set_key_out_handle: -- void **bezier_track_set_key_out_handle** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`Vector2` out_handle **)** +.. rst-class:: classref-method + +|void| **bezier_track_set_key_out_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, out_handle\: :ref:`Vector2`, balanced_value_time_ratio\: :ref:`float` = 1.0\ ) :ref:`🔗` Sets the out handle of the key identified by ``key_idx`` to value ``out_handle``. The ``track_idx`` must be the index of a Bezier Track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_bezier_track_set_key_value: -- void **bezier_track_set_key_value** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` value **)** +.. rst-class:: classref-method + +|void| **bezier_track_set_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, value\: :ref:`float`\ ) :ref:`🔗` Sets the value of the key identified by ``key_idx`` to the given value. The ``track_idx`` must be the index of a Bezier Track. +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_blend_shape_track_insert_key: + +.. rst-class:: classref-method + +:ref:`int` **blend_shape_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, amount\: :ref:`float`\ ) :ref:`🔗` + +Inserts a key in a given blend shape track. Returns the key index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_blend_shape_track_interpolate: + +.. rst-class:: classref-method + +:ref:`float` **blend_shape_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns the interpolated blend shape value at the given time (in seconds). The ``track_idx`` must be the index of a blend shape track. + +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_clear: -- void **clear** **(** **)** +.. rst-class:: classref-method + +|void| **clear**\ (\ ) :ref:`🔗` Clear the animation (clear all tracks and reset all). +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_compress: + +.. rst-class:: classref-method + +|void| **compress**\ (\ page_size\: :ref:`int` = 8192, fps\: :ref:`int` = 120, split_tolerance\: :ref:`float` = 4.0\ ) :ref:`🔗` + +Compress the animation and all its tracks in-place. This will make :ref:`track_is_compressed()` return ``true`` once called on this **Animation**. Compressed tracks require less memory to be played, and are designed to be used for complex 3D animations (such as cutscenes) imported from external 3D software. Compression is lossy, but the difference is usually not noticeable in real world conditions. + +\ **Note:** Compressed tracks have various limitations (such as not being editable from the editor), so only use compressed animations if you actually need them. + +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_copy_track: -- void **copy_track** **(** :ref:`int` track_idx, :ref:`Animation` to_animation **)** +.. rst-class:: classref-method + +|void| **copy_track**\ (\ track_idx\: :ref:`int`, to_animation\: :ref:`Animation`\ ) :ref:`🔗` -Adds a new track that is a copy of the given track from ``to_animation``. +Adds a new track to ``to_animation`` that is a copy of the given track from this animation. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_find_track: -- :ref:`int` **find_track** **(** :ref:`NodePath` path **)** const +.. rst-class:: classref-method + +:ref:`int` **find_track**\ (\ path\: :ref:`NodePath`, type\: :ref:`TrackType`\ ) |const| :ref:`🔗` Returns the index of the specified track. If the track is not found, return -1. +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_at_time: + +.. rst-class:: classref-method + +:ref:`StringName` **get_marker_at_time**\ (\ time\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns the name of the marker located at the given time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_color: + +.. rst-class:: classref-method + +:ref:`Color` **get_marker_color**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the given marker's color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_names: + +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_marker_names**\ (\ ) |const| :ref:`🔗` + +Returns every marker in this Animation, sorted ascending by time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_time: + +.. rst-class:: classref-method + +:ref:`float` **get_marker_time**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the given marker's time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_next_marker: + +.. rst-class:: classref-method + +:ref:`StringName` **get_next_marker**\ (\ time\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns the closest marker that comes after the given time. If no such marker exists, an empty string is returned. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_prev_marker: + +.. rst-class:: classref-method + +:ref:`StringName` **get_prev_marker**\ (\ time\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns the closest marker that comes before the given time. If no such marker exists, an empty string is returned. + +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_get_track_count: -- :ref:`int` **get_track_count** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_track_count**\ (\ ) |const| :ref:`🔗` Returns the amount of tracks in the animation. +.. rst-class:: classref-item-separator + ---- -.. _class_Animation_method_method_track_get_key_indices: +.. _class_Animation_method_has_marker: + +.. rst-class:: classref-method + +:ref:`bool` **has_marker**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` -- :ref:`PackedInt32Array` **method_track_get_key_indices** **(** :ref:`int` track_idx, :ref:`float` time_sec, :ref:`float` delta **)** const +Returns ``true`` if this Animation contains a marker with the given name. -Returns all the key indices of a method track, given a position and delta time. +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_method_track_get_name: -- :ref:`StringName` **method_track_get_name** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`StringName` **method_track_get_name**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the method name of a method track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_method_track_get_params: -- :ref:`Array` **method_track_get_params** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`Array` **method_track_get_params**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the arguments values to be called on a method track for a given key in a given track. +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_optimize: + +.. rst-class:: classref-method + +|void| **optimize**\ (\ allowed_velocity_err\: :ref:`float` = 0.01, allowed_angular_err\: :ref:`float` = 0.01, precision\: :ref:`int` = 3\ ) :ref:`🔗` + +Optimize the animation and all its tracks in-place. This will preserve only as many keys as are necessary to keep the animation within the specified bounds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_position_track_insert_key: + +.. rst-class:: classref-method + +:ref:`int` **position_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, position\: :ref:`Vector3`\ ) :ref:`🔗` + +Inserts a key in a given 3D position track. Returns the key index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_position_track_interpolate: + +.. rst-class:: classref-method + +:ref:`Vector3` **position_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns the interpolated position value at the given time (in seconds). The ``track_idx`` must be the index of a 3D position track. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_remove_marker: + +.. rst-class:: classref-method + +|void| **remove_marker**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Removes the marker with the given name from this Animation. + +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_remove_track: -- void **remove_track** **(** :ref:`int` track_idx **)** +.. rst-class:: classref-method + +|void| **remove_track**\ (\ track_idx\: :ref:`int`\ ) :ref:`🔗` Removes a track by specifying the track index. +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_rotation_track_insert_key: + +.. rst-class:: classref-method + +:ref:`int` **rotation_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, rotation\: :ref:`Quaternion`\ ) :ref:`🔗` + +Inserts a key in a given 3D rotation track. Returns the key index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_rotation_track_interpolate: + +.. rst-class:: classref-method + +:ref:`Quaternion` **rotation_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns the interpolated rotation value at the given time (in seconds). The ``track_idx`` must be the index of a 3D rotation track. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_scale_track_insert_key: + +.. rst-class:: classref-method + +:ref:`int` **scale_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, scale\: :ref:`Vector3`\ ) :ref:`🔗` + +Inserts a key in a given 3D scale track. Returns the key index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_scale_track_interpolate: + +.. rst-class:: classref-method + +:ref:`Vector3` **scale_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns the interpolated scale value at the given time (in seconds). The ``track_idx`` must be the index of a 3D scale track. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_set_marker_color: + +.. rst-class:: classref-method + +|void| **set_marker_color**\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) :ref:`🔗` + +Sets the given marker's color. + +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_find_key: -- :ref:`int` **track_find_key** **(** :ref:`int` track_idx, :ref:`float` time, :ref:`bool` exact=false **)** const +.. rst-class:: classref-method + +:ref:`int` **track_find_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, find_mode\: :ref:`FindMode` = 0, limit\: :ref:`bool` = false, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Finds the key index by time in a given track. Optionally, only find it if the approx/exact time is given. + +If ``limit`` is ``true``, it does not return keys outside the animation range. + +If ``backward`` is ``true``, the direction is reversed in methods that rely on one directional processing. + +For example, in case ``find_mode`` is :ref:`FIND_MODE_NEAREST`, if there is no key in the current position just after seeked, the first key found is retrieved by searching before the position, but if ``backward`` is ``true``, the first key found is retrieved after the position. -Finds the key index by time in a given track. Optionally, only find it if the exact time is given. +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_get_interpolation_loop_wrap: -- :ref:`bool` **track_get_interpolation_loop_wrap** **(** :ref:`int` track_idx **)** const +.. rst-class:: classref-method -Returns ``true`` if the track at ``idx`` wraps the interpolation loop. New tracks wrap the interpolation loop by default. +:ref:`bool` **track_get_interpolation_loop_wrap**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the track at ``track_idx`` wraps the interpolation loop. New tracks wrap the interpolation loop by default. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_get_interpolation_type: -- :ref:`InterpolationType` **track_get_interpolation_type** **(** :ref:`int` track_idx **)** const +.. rst-class:: classref-method + +:ref:`InterpolationType` **track_get_interpolation_type**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the interpolation type of a given track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_get_key_count: -- :ref:`int` **track_get_key_count** **(** :ref:`int` track_idx **)** const +.. rst-class:: classref-method -Returns the amount of keys in a given track. +:ref:`int` **track_get_key_count**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the number of keys in a given track. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_get_key_time: -- :ref:`float` **track_get_key_time** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **track_get_key_time**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the time at which the key is located. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_get_key_transition: -- :ref:`float` **track_get_key_transition** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **track_get_key_transition**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the transition curve (easing) for a specific key (see the built-in math function :ref:`@GlobalScope.ease()`). -Returns the transition curve (easing) for a specific key (see the built-in math function :ref:`@GDScript.ease`). +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_get_key_value: -- :ref:`Variant` **track_get_key_value** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** const +.. rst-class:: classref-method + +:ref:`Variant` **track_get_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the value of a given key in a given track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_get_path: -- :ref:`NodePath` **track_get_path** **(** :ref:`int` track_idx **)** const +.. rst-class:: classref-method + +:ref:`NodePath` **track_get_path**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Gets the path of a track. For more information on the path format, see :ref:`track_set_path`. +Gets the path of a track. For more information on the path format, see :ref:`track_set_path()`. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_get_type: -- :ref:`TrackType` **track_get_type** **(** :ref:`int` track_idx **)** const +.. rst-class:: classref-method + +:ref:`TrackType` **track_get_type**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Gets the type of a track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_insert_key: -- void **track_insert_key** **(** :ref:`int` track_idx, :ref:`float` time, :ref:`Variant` key, :ref:`float` transition=1 **)** +.. rst-class:: classref-method + +:ref:`int` **track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, key\: :ref:`Variant`, transition\: :ref:`float` = 1\ ) :ref:`🔗` -Insert a generic key in a given track. +Inserts a generic key in a given track. Returns the key index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_track_is_compressed: + +.. rst-class:: classref-method + +:ref:`bool` **track_is_compressed**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the track is compressed, ``false`` otherwise. See also :ref:`compress()`. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_is_enabled: -- :ref:`bool` **track_is_enabled** **(** :ref:`int` track_idx **)** const +.. rst-class:: classref-method + +:ref:`bool` **track_is_enabled**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Returns ``true`` if the track at index ``idx`` is enabled. +Returns ``true`` if the track at index ``track_idx`` is enabled. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_is_imported: -- :ref:`bool` **track_is_imported** **(** :ref:`int` track_idx **)** const +.. rst-class:: classref-method + +:ref:`bool` **track_is_imported**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if the given track is imported. Else, return ``false``. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_move_down: -- void **track_move_down** **(** :ref:`int` track_idx **)** +.. rst-class:: classref-method + +|void| **track_move_down**\ (\ track_idx\: :ref:`int`\ ) :ref:`🔗` Moves a track down. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_move_to: -- void **track_move_to** **(** :ref:`int` track_idx, :ref:`int` to_idx **)** +.. rst-class:: classref-method + +|void| **track_move_to**\ (\ track_idx\: :ref:`int`, to_idx\: :ref:`int`\ ) :ref:`🔗` + +Changes the index position of track ``track_idx`` to the one defined in ``to_idx``. -Changes the index position of track ``idx`` to the one defined in ``to_idx``. +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_move_up: -- void **track_move_up** **(** :ref:`int` track_idx **)** +.. rst-class:: classref-method + +|void| **track_move_up**\ (\ track_idx\: :ref:`int`\ ) :ref:`🔗` Moves a track up. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_remove_key: -- void **track_remove_key** **(** :ref:`int` track_idx, :ref:`int` key_idx **)** +.. rst-class:: classref-method + +|void| **track_remove_key**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) :ref:`🔗` Removes a key by index in a given track. +.. rst-class:: classref-item-separator + ---- -.. _class_Animation_method_track_remove_key_at_position: +.. _class_Animation_method_track_remove_key_at_time: + +.. rst-class:: classref-method + +|void| **track_remove_key_at_time**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`\ ) :ref:`🔗` -- void **track_remove_key_at_position** **(** :ref:`int` track_idx, :ref:`float` position **)** +Removes a key at ``time`` in a given track. -Removes a key by position (seconds) in a given track. +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_set_enabled: -- void **track_set_enabled** **(** :ref:`int` track_idx, :ref:`bool` enabled **)** +.. rst-class:: classref-method + +|void| **track_set_enabled**\ (\ track_idx\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` Enables/disables the given track. Tracks are enabled by default. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_set_imported: -- void **track_set_imported** **(** :ref:`int` track_idx, :ref:`bool` imported **)** +.. rst-class:: classref-method + +|void| **track_set_imported**\ (\ track_idx\: :ref:`int`, imported\: :ref:`bool`\ ) :ref:`🔗` Sets the given track as imported or not. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_set_interpolation_loop_wrap: -- void **track_set_interpolation_loop_wrap** **(** :ref:`int` track_idx, :ref:`bool` interpolation **)** +.. rst-class:: classref-method -If ``true``, the track at ``idx`` wraps the interpolation loop. +|void| **track_set_interpolation_loop_wrap**\ (\ track_idx\: :ref:`int`, interpolation\: :ref:`bool`\ ) :ref:`🔗` + +If ``true``, the track at ``track_idx`` wraps the interpolation loop. + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_set_interpolation_type: -- void **track_set_interpolation_type** **(** :ref:`int` track_idx, :ref:`InterpolationType` interpolation **)** +.. rst-class:: classref-method + +|void| **track_set_interpolation_type**\ (\ track_idx\: :ref:`int`, interpolation\: :ref:`InterpolationType`\ ) :ref:`🔗` Sets the interpolation type of a given track. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_set_key_time: -- void **track_set_key_time** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` time **)** +.. rst-class:: classref-method + +|void| **track_set_key_time**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, time\: :ref:`float`\ ) :ref:`🔗` Sets the time of an existing key. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_set_key_transition: -- void **track_set_key_transition** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`float` transition **)** +.. rst-class:: classref-method -Sets the transition curve (easing) for a specific key (see the built-in math function :ref:`@GDScript.ease`). +|void| **track_set_key_transition**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, transition\: :ref:`float`\ ) :ref:`🔗` + +Sets the transition curve (easing) for a specific key (see the built-in math function :ref:`@GlobalScope.ease()`). + +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_track_set_key_value: -- void **track_set_key_value** **(** :ref:`int` track_idx, :ref:`int` key, :ref:`Variant` value **)** +.. rst-class:: classref-method + +|void| **track_set_key_value**\ (\ track_idx\: :ref:`int`, key\: :ref:`int`, value\: :ref:`Variant`\ ) :ref:`🔗` Sets the value of an existing key. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_set_path: -- void **track_set_path** **(** :ref:`int` track_idx, :ref:`NodePath` path **)** +.. rst-class:: classref-method + +|void| **track_set_path**\ (\ track_idx\: :ref:`int`, path\: :ref:`NodePath`\ ) :ref:`🔗` -Sets the path of a track. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by ``":"``. +Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the :ref:`AnimationMixer.root_node` that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by ``":"``. For example, ``"character/skeleton:ankle"`` or ``"character/mesh:transform/local"``. +.. rst-class:: classref-item-separator + ---- .. _class_Animation_method_track_swap: -- void **track_swap** **(** :ref:`int` track_idx, :ref:`int` with_idx **)** +.. rst-class:: classref-method -Swaps the track ``idx``'s index position with the track ``with_idx``. +|void| **track_swap**\ (\ track_idx\: :ref:`int`, with_idx\: :ref:`int`\ ) :ref:`🔗` ----- +Swaps the track ``track_idx``'s index position with the track ``with_idx``. -.. _class_Animation_method_transform_track_insert_key: +.. rst-class:: classref-item-separator -- :ref:`int` **transform_track_insert_key** **(** :ref:`int` track_idx, :ref:`float` time, :ref:`Vector3` location, :ref:`Quat` rotation, :ref:`Vector3` scale **)** +---- -Insert a transform key for a transform track. +.. _class_Animation_method_value_track_get_update_mode: ----- +.. rst-class:: classref-method -.. _class_Animation_method_transform_track_interpolate: +:ref:`UpdateMode` **value_track_get_update_mode**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` -- :ref:`Array` **transform_track_interpolate** **(** :ref:`int` track_idx, :ref:`float` time_sec **)** const +Returns the update mode of a value track. -Returns the interpolated value of a transform track at a given time (in seconds). An array consisting of 3 elements: position (:ref:`Vector3`), rotation (:ref:`Quat`) and scale (:ref:`Vector3`). +.. rst-class:: classref-item-separator ---- -.. _class_Animation_method_value_track_get_key_indices: - -- :ref:`PackedInt32Array` **value_track_get_key_indices** **(** :ref:`int` track_idx, :ref:`float` time_sec, :ref:`float` delta **)** const +.. _class_Animation_method_value_track_interpolate: -Returns all the key indices of a value track, given a position and delta time. +.. rst-class:: classref-method ----- +:ref:`Variant` **value_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` -.. _class_Animation_method_value_track_get_update_mode: +Returns the interpolated value at the given time (in seconds). The ``track_idx`` must be the index of a value track. -- :ref:`UpdateMode` **value_track_get_update_mode** **(** :ref:`int` track_idx **)** const +A ``backward`` mainly affects the direction of key retrieval of the track with :ref:`UPDATE_DISCRETE` converted by :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS` to match the result with :ref:`track_find_key()`. -Returns the update mode of a value track. +.. rst-class:: classref-item-separator ---- .. _class_Animation_method_value_track_set_update_mode: -- void **value_track_set_update_mode** **(** :ref:`int` track_idx, :ref:`UpdateMode` mode **)** +.. rst-class:: classref-method + +|void| **value_track_set_update_mode**\ (\ track_idx\: :ref:`int`, mode\: :ref:`UpdateMode`\ ) :ref:`🔗` -Sets the update mode (see :ref:`UpdateMode`) of a value track. +Sets the update mode of a value track. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationlibrary.rst b/classes/class_animationlibrary.rst new file mode 100644 index 00000000000..73d3860bfdb --- /dev/null +++ b/classes/class_animationlibrary.rst @@ -0,0 +1,207 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationLibrary.xml. + +.. _class_AnimationLibrary: + +AnimationLibrary +================ + +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Container for :ref:`Animation` resources. + +.. rst-class:: classref-introduction-group + +Description +----------- + +An animation library stores a set of animations accessible through :ref:`StringName` keys, for use with :ref:`AnimationPlayer` nodes. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Animation tutorial index <../tutorials/animation/index>` + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`add_animation`\ (\ name\: :ref:`StringName`, animation\: :ref:`Animation`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Animation` | :ref:`get_animation`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_animation_list`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_animation_list_size`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_animation`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_animation`\ (\ name\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`rename_animation`\ (\ name\: :ref:`StringName`, newname\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_AnimationLibrary_signal_animation_added: + +.. rst-class:: classref-signal + +**animation_added**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when an :ref:`Animation` is added, under the key ``name``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_signal_animation_changed: + +.. rst-class:: classref-signal + +**animation_changed**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when there's a change in one of the animations, e.g. tracks are added, moved or have changed paths. ``name`` is the key of the animation that was changed. + +See also :ref:`Resource.changed`, which this acts as a relay for. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_signal_animation_removed: + +.. rst-class:: classref-signal + +**animation_removed**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when an :ref:`Animation` stored with the key ``name`` is removed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_signal_animation_renamed: + +.. rst-class:: classref-signal + +**animation_renamed**\ (\ name\: :ref:`StringName`, to_name\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when the key for an :ref:`Animation` is changed, from ``name`` to ``to_name``. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AnimationLibrary_method_add_animation: + +.. rst-class:: classref-method + +:ref:`Error` **add_animation**\ (\ name\: :ref:`StringName`, animation\: :ref:`Animation`\ ) :ref:`🔗` + +Adds the ``animation`` to the library, accessible by the key ``name``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_method_get_animation: + +.. rst-class:: classref-method + +:ref:`Animation` **get_animation**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the :ref:`Animation` with the key ``name``. If the animation does not exist, ``null`` is returned and an error is logged. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_method_get_animation_list: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`StringName`\] **get_animation_list**\ (\ ) |const| :ref:`🔗` + +Returns the keys for the :ref:`Animation`\ s stored in the library. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_method_get_animation_list_size: + +.. rst-class:: classref-method + +:ref:`int` **get_animation_list_size**\ (\ ) |const| :ref:`🔗` + +Returns the key count for the :ref:`Animation`\ s stored in the library. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_method_has_animation: + +.. rst-class:: classref-method + +:ref:`bool` **has_animation**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns ``true`` if the library stores an :ref:`Animation` with ``name`` as the key. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_method_remove_animation: + +.. rst-class:: classref-method + +|void| **remove_animation**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Removes the :ref:`Animation` with the key ``name``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationLibrary_method_rename_animation: + +.. rst-class:: classref-method + +|void| **rename_animation**\ (\ name\: :ref:`StringName`, newname\: :ref:`StringName`\ ) :ref:`🔗` + +Changes the key of the :ref:`Animation` associated with the key ``name`` to ``newname``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationmixer.rst b/classes/class_animationmixer.rst new file mode 100644 index 00000000000..d33265e7cc8 --- /dev/null +++ b/classes/class_animationmixer.rst @@ -0,0 +1,983 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationMixer.xml. + +.. _class_AnimationMixer: + +AnimationMixer +============== + +**Inherits:** :ref:`Node` **<** :ref:`Object` + +**Inherited By:** :ref:`AnimationPlayer`, :ref:`AnimationTree` + +Base class for :ref:`AnimationPlayer` and :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Base class for :ref:`AnimationPlayer` and :ref:`AnimationTree` to manage animation lists. It also has general properties and methods for playback and blending. + +After instantiating the playback information data within the extended class, the blending is processed by the **AnimationMixer**. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Migrating Animations from Godot 4.0 to 4.3 `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`active` | ``true`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`int` | :ref:`audio_max_polyphony` | ``32`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`AnimationCallbackModeDiscrete` | :ref:`callback_mode_discrete` | ``1`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`AnimationCallbackModeMethod` | :ref:`callback_mode_method` | ``0`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`AnimationCallbackModeProcess` | :ref:`callback_mode_process` | ``1`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`deterministic` | ``false`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`reset_on_save` | ``true`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`root_motion_local` | ``false`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`NodePath` | :ref:`root_motion_track` | ``NodePath("")`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`NodePath` | :ref:`root_node` | ``NodePath("..")`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`_post_process_key_value`\ (\ animation\: :ref:`Animation`, track\: :ref:`int`, value\: :ref:`Variant`, object_id\: :ref:`int`, object_sub_idx\: :ref:`int`\ ) |virtual| |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`add_animation_library`\ (\ name\: :ref:`StringName`, library\: :ref:`AnimationLibrary`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`advance`\ (\ delta\: :ref:`float`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`capture`\ (\ name\: :ref:`StringName`, duration\: :ref:`float`, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_caches`\ (\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`find_animation`\ (\ animation\: :ref:`Animation`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`find_animation_library`\ (\ animation\: :ref:`Animation`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Animation` | :ref:`get_animation`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationLibrary` | :ref:`get_animation_library`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_animation_library_list`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_animation_list`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_root_motion_position`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_root_motion_position_accumulator`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Quaternion` | :ref:`get_root_motion_rotation`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Quaternion` | :ref:`get_root_motion_rotation_accumulator`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_root_motion_scale`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_root_motion_scale_accumulator`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_animation`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_animation_library`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_animation_library`\ (\ name\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`rename_animation_library`\ (\ name\: :ref:`StringName`, newname\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_AnimationMixer_signal_animation_finished: + +.. rst-class:: classref-signal + +**animation_finished**\ (\ anim_name\: :ref:`StringName`\ ) :ref:`🔗` + +Notifies when an animation finished playing. + +\ **Note:** This signal is not emitted if an animation is looping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_signal_animation_libraries_updated: + +.. rst-class:: classref-signal + +**animation_libraries_updated**\ (\ ) :ref:`🔗` + +Notifies when the animation libraries have changed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_signal_animation_list_changed: + +.. rst-class:: classref-signal + +**animation_list_changed**\ (\ ) :ref:`🔗` + +Notifies when an animation list is changed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_signal_animation_started: + +.. rst-class:: classref-signal + +**animation_started**\ (\ anim_name\: :ref:`StringName`\ ) :ref:`🔗` + +Notifies when an animation starts playing. + +\ **Note:** This signal is not emitted if an animation is looping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_signal_caches_cleared: + +.. rst-class:: classref-signal + +**caches_cleared**\ (\ ) :ref:`🔗` + +Notifies when the caches have been cleared, either automatically, or manually via :ref:`clear_caches()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_signal_mixer_applied: + +.. rst-class:: classref-signal + +**mixer_applied**\ (\ ) :ref:`🔗` + +Notifies when the blending result related have been applied to the target objects. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_signal_mixer_updated: + +.. rst-class:: classref-signal + +**mixer_updated**\ (\ ) :ref:`🔗` + +Notifies when the property related process have been updated. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AnimationMixer_AnimationCallbackModeProcess: + +.. rst-class:: classref-enumeration + +enum **AnimationCallbackModeProcess**: :ref:`🔗` + +.. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS: + +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationCallbackModeProcess` **ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS** = ``0`` + +Process animation during physics frames (see :ref:`Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS`). This is especially useful when animating physics bodies. + +.. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_IDLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationCallbackModeProcess` **ANIMATION_CALLBACK_MODE_PROCESS_IDLE** = ``1`` + +Process animation during process frames (see :ref:`Node.NOTIFICATION_INTERNAL_PROCESS`). + +.. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_MANUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationCallbackModeProcess` **ANIMATION_CALLBACK_MODE_PROCESS_MANUAL** = ``2`` + +Do not process animation. Use :ref:`advance()` to process the animation manually. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AnimationMixer_AnimationCallbackModeMethod: + +.. rst-class:: classref-enumeration + +enum **AnimationCallbackModeMethod**: :ref:`🔗` + +.. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_METHOD_DEFERRED: + +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationCallbackModeMethod` **ANIMATION_CALLBACK_MODE_METHOD_DEFERRED** = ``0`` + +Batch method calls during the animation process, then do the calls after events are processed. This avoids bugs involving deleting nodes or modifying the AnimationPlayer while playing. + +.. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationCallbackModeMethod` **ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE** = ``1`` + +Make method calls immediately when reached in the animation. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AnimationMixer_AnimationCallbackModeDiscrete: + +.. rst-class:: classref-enumeration + +enum **AnimationCallbackModeDiscrete**: :ref:`🔗` + +.. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT: + +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationCallbackModeDiscrete` **ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT** = ``0`` + +An :ref:`Animation.UPDATE_DISCRETE` track value takes precedence when blending :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track values and :ref:`Animation.UPDATE_DISCRETE` track values. + +.. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationCallbackModeDiscrete` **ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE** = ``1`` + +An :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track value takes precedence when blending the :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track values and the :ref:`Animation.UPDATE_DISCRETE` track values. This is the default behavior for :ref:`AnimationPlayer`. + +.. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS: + +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationCallbackModeDiscrete` **ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS** = ``2`` + +Always treat the :ref:`Animation.UPDATE_DISCRETE` track value as :ref:`Animation.UPDATE_CONTINUOUS` with :ref:`Animation.INTERPOLATION_NEAREST`. This is the default behavior for :ref:`AnimationTree`. + +If a value track has un-interpolatable type key values, it is internally converted to use :ref:`ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE` with :ref:`Animation.UPDATE_DISCRETE`. + +Un-interpolatable type list: + +- :ref:`@GlobalScope.TYPE_NIL`\ + +- :ref:`@GlobalScope.TYPE_NODE_PATH`\ + +- :ref:`@GlobalScope.TYPE_RID`\ + +- :ref:`@GlobalScope.TYPE_OBJECT`\ + +- :ref:`@GlobalScope.TYPE_CALLABLE`\ + +- :ref:`@GlobalScope.TYPE_SIGNAL`\ + +- :ref:`@GlobalScope.TYPE_DICTIONARY`\ + +- :ref:`@GlobalScope.TYPE_PACKED_BYTE_ARRAY`\ + +\ :ref:`@GlobalScope.TYPE_BOOL` and :ref:`@GlobalScope.TYPE_INT` are treated as :ref:`@GlobalScope.TYPE_FLOAT` during blending and rounded when the result is retrieved. + +It is same for arrays and vectors with them such as :ref:`@GlobalScope.TYPE_PACKED_INT32_ARRAY` or :ref:`@GlobalScope.TYPE_VECTOR2I`, they are treated as :ref:`@GlobalScope.TYPE_PACKED_FLOAT32_ARRAY` or :ref:`@GlobalScope.TYPE_VECTOR2`. Also note that for arrays, the size is also interpolated. + +\ :ref:`@GlobalScope.TYPE_STRING` and :ref:`@GlobalScope.TYPE_STRING_NAME` are interpolated between character codes and lengths, but note that there is a difference in algorithm between interpolation between keys and interpolation by blending. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimationMixer_property_active: + +.. rst-class:: classref-property + +:ref:`bool` **active** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_active**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_active**\ (\ ) + +If ``true``, the **AnimationMixer** will be processing. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_audio_max_polyphony: + +.. rst-class:: classref-property + +:ref:`int` **audio_max_polyphony** = ``32`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_audio_max_polyphony**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_audio_max_polyphony**\ (\ ) + +The number of possible simultaneous sounds for each of the assigned AudioStreamPlayers. + +For example, if this value is ``32`` and the animation has two audio tracks, the two :ref:`AudioStreamPlayer`\ s assigned can play simultaneously up to ``32`` voices each. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_callback_mode_discrete: + +.. rst-class:: classref-property + +:ref:`AnimationCallbackModeDiscrete` **callback_mode_discrete** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_callback_mode_discrete**\ (\ value\: :ref:`AnimationCallbackModeDiscrete`\ ) +- :ref:`AnimationCallbackModeDiscrete` **get_callback_mode_discrete**\ (\ ) + +Ordinarily, tracks can be set to :ref:`Animation.UPDATE_DISCRETE` to update infrequently, usually when using nearest interpolation. + +However, when blending with :ref:`Animation.UPDATE_CONTINUOUS` several results are considered. The :ref:`callback_mode_discrete` specify it explicitly. See also :ref:`AnimationCallbackModeDiscrete`. + +To make the blended results look good, it is recommended to set this to :ref:`ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS` to update every frame during blending. Other values exist for compatibility and they are fine if there is no blending, but not so, may produce artifacts. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_callback_mode_method: + +.. rst-class:: classref-property + +:ref:`AnimationCallbackModeMethod` **callback_mode_method** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_callback_mode_method**\ (\ value\: :ref:`AnimationCallbackModeMethod`\ ) +- :ref:`AnimationCallbackModeMethod` **get_callback_mode_method**\ (\ ) + +The call mode used for "Call Method" tracks. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_callback_mode_process: + +.. rst-class:: classref-property + +:ref:`AnimationCallbackModeProcess` **callback_mode_process** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_callback_mode_process**\ (\ value\: :ref:`AnimationCallbackModeProcess`\ ) +- :ref:`AnimationCallbackModeProcess` **get_callback_mode_process**\ (\ ) + +The process notification in which to update animations. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_deterministic: + +.. rst-class:: classref-property + +:ref:`bool` **deterministic** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_deterministic**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_deterministic**\ (\ ) + +If ``true``, the blending uses the deterministic algorithm. The total weight is not normalized and the result is accumulated with an initial value (``0`` or a ``"RESET"`` animation if present). + +This means that if the total amount of blending is ``0.0``, the result is equal to the ``"RESET"`` animation. + +If the number of tracks between the blended animations is different, the animation with the missing track is treated as if it had the initial value. + +If ``false``, The blend does not use the deterministic algorithm. The total weight is normalized and always ``1.0``. If the number of tracks between the blended animations is different, nothing is done about the animation that is missing a track. + +\ **Note:** In :ref:`AnimationTree`, the blending with :ref:`AnimationNodeAdd2`, :ref:`AnimationNodeAdd3`, :ref:`AnimationNodeSub2` or the weight greater than ``1.0`` may produce unexpected results. + +For example, if :ref:`AnimationNodeAdd2` blends two nodes with the amount ``1.0``, then total weight is ``2.0`` but it will be normalized to make the total amount ``1.0`` and the result will be equal to :ref:`AnimationNodeBlend2` with the amount ``0.5``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_reset_on_save: + +.. rst-class:: classref-property + +:ref:`bool` **reset_on_save** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_reset_on_save_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_reset_on_save_enabled**\ (\ ) + +This is used by the editor. If set to ``true``, the scene will be saved with the effects of the reset animation (the animation with the key ``"RESET"``) applied as if it had been seeked to time 0, with the editor keeping the values that the scene had before saving. + +This makes it more convenient to preview and edit animations in the editor, as changes to the scene will not be saved as long as they are set in the reset animation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_root_motion_local: + +.. rst-class:: classref-property + +:ref:`bool` **root_motion_local** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_root_motion_local**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_root_motion_local**\ (\ ) + +If ``true``, :ref:`get_root_motion_position()` value is extracted as a local translation value before blending. In other words, it is treated like the translation is done after the rotation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_root_motion_track: + +.. rst-class:: classref-property + +:ref:`NodePath` **root_motion_track** = ``NodePath("")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_root_motion_track**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_root_motion_track**\ (\ ) + +The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. The :ref:`root_motion_track` uses the same format as :ref:`Animation.track_set_path()`, but note that a bone must be specified. + +If the track has type :ref:`Animation.TYPE_POSITION_3D`, :ref:`Animation.TYPE_ROTATION_3D`, or :ref:`Animation.TYPE_SCALE_3D` the transformation will be canceled visually, and the animation will appear to stay in place. See also :ref:`get_root_motion_position()`, :ref:`get_root_motion_rotation()`, :ref:`get_root_motion_scale()`, and :ref:`RootMotionView`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_property_root_node: + +.. rst-class:: classref-property + +:ref:`NodePath` **root_node** = ``NodePath("..")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_root_node**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_root_node**\ (\ ) + +The node which node path references will travel from. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AnimationMixer_private_method__post_process_key_value: + +.. rst-class:: classref-method + +:ref:`Variant` **_post_process_key_value**\ (\ animation\: :ref:`Animation`, track\: :ref:`int`, value\: :ref:`Variant`, object_id\: :ref:`int`, object_sub_idx\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` + +A virtual function for processing after getting a key during playback. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_add_animation_library: + +.. rst-class:: classref-method + +:ref:`Error` **add_animation_library**\ (\ name\: :ref:`StringName`, library\: :ref:`AnimationLibrary`\ ) :ref:`🔗` + +Adds ``library`` to the animation player, under the key ``name``. + +AnimationMixer has a global library by default with an empty string as key. For adding an animation to the global library: + + +.. tabs:: + + .. code-tab:: gdscript + + var global_library = mixer.get_animation_library("") + global_library.add_animation("animation_name", animation_resource) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_advance: + +.. rst-class:: classref-method + +|void| **advance**\ (\ delta\: :ref:`float`\ ) :ref:`🔗` + +Manually advance the animations by the specified time (in seconds). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_capture: + +.. rst-class:: classref-method + +|void| **capture**\ (\ name\: :ref:`StringName`, duration\: :ref:`float`, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) :ref:`🔗` + +If the animation track specified by ``name`` has an option :ref:`Animation.UPDATE_CAPTURE`, stores current values of the objects indicated by the track path as a cache. If there is already a captured cache, the old cache is discarded. + +After this it will interpolate with current animation blending result during the playback process for the time specified by ``duration``, working like a crossfade. + +You can specify ``trans_type`` as the curve for the interpolation. For better results, it may be appropriate to specify :ref:`Tween.TRANS_LINEAR` for cases where the first key of the track begins with a non-zero value or where the key value does not change, and :ref:`Tween.TRANS_QUAD` for cases where the key value changes linearly. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_clear_caches: + +.. rst-class:: classref-method + +|void| **clear_caches**\ (\ ) :ref:`🔗` + +**AnimationMixer** caches animated nodes. It may not notice if a node disappears; :ref:`clear_caches()` forces it to update the cache again. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_find_animation: + +.. rst-class:: classref-method + +:ref:`StringName` **find_animation**\ (\ animation\: :ref:`Animation`\ ) |const| :ref:`🔗` + +Returns the key of ``animation`` or an empty :ref:`StringName` if not found. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_find_animation_library: + +.. rst-class:: classref-method + +:ref:`StringName` **find_animation_library**\ (\ animation\: :ref:`Animation`\ ) |const| :ref:`🔗` + +Returns the key for the :ref:`AnimationLibrary` that contains ``animation`` or an empty :ref:`StringName` if not found. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_animation: + +.. rst-class:: classref-method + +:ref:`Animation` **get_animation**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the :ref:`Animation` with the key ``name``. If the animation does not exist, ``null`` is returned and an error is logged. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_animation_library: + +.. rst-class:: classref-method + +:ref:`AnimationLibrary` **get_animation_library**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the first :ref:`AnimationLibrary` with key ``name`` or ``null`` if not found. + +To get the **AnimationMixer**'s global animation library, use ``get_animation_library("")``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_animation_library_list: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`StringName`\] **get_animation_library_list**\ (\ ) |const| :ref:`🔗` + +Returns the list of stored library keys. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_animation_list: + +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_animation_list**\ (\ ) |const| :ref:`🔗` + +Returns the list of stored animation keys. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_root_motion_position: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_root_motion_position**\ (\ ) |const| :ref:`🔗` + +Retrieve the motion delta of position with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. + +If :ref:`root_motion_track` is not a path to a track of type :ref:`Animation.TYPE_POSITION_3D`, returns ``Vector3(0, 0, 0)``. + +See also :ref:`root_motion_track` and :ref:`RootMotionView`. + +The most basic example is applying position to :ref:`CharacterBody3D`: + + +.. tabs:: + + .. code-tab:: gdscript + + var current_rotation + + func _process(delta): + if Input.is_action_just_pressed("animate"): + current_rotation = get_quaternion() + state_machine.travel("Animate") + var velocity = current_rotation * animation_tree.get_root_motion_position() / delta + set_velocity(velocity) + move_and_slide() + + + +By using this in combination with :ref:`get_root_motion_rotation_accumulator()`, you can apply the root motion position more correctly to account for the rotation of the node. + + +.. tabs:: + + .. code-tab:: gdscript + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation()) + var velocity = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta + set_velocity(velocity) + move_and_slide() + + + +If :ref:`root_motion_local` is ``true``, returns the pre-multiplied translation value with the inverted rotation. + +In this case, the code can be written as follows: + + +.. tabs:: + + .. code-tab:: gdscript + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation()) + var velocity = get_quaternion() * animation_tree.get_root_motion_position() / delta + set_velocity(velocity) + move_and_slide() + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_root_motion_position_accumulator: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_root_motion_position_accumulator**\ (\ ) |const| :ref:`🔗` + +Retrieve the blended value of the position tracks with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. + +This is useful in cases where you want to respect the initial key values of the animation. + +For example, if an animation with only one key ``Vector3(0, 0, 0)`` is played in the previous frame and then an animation with only one key ``Vector3(1, 0, 1)`` is played in the next frame, the difference can be calculated as follows: + + +.. tabs:: + + .. code-tab:: gdscript + + var prev_root_motion_position_accumulator + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_position_accumulator = animation_tree.get_root_motion_position_accumulator() + var difference = current_root_motion_position_accumulator - prev_root_motion_position_accumulator + prev_root_motion_position_accumulator = current_root_motion_position_accumulator + transform.origin += difference + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_root_motion_rotation: + +.. rst-class:: classref-method + +:ref:`Quaternion` **get_root_motion_rotation**\ (\ ) |const| :ref:`🔗` + +Retrieve the motion delta of rotation with the :ref:`root_motion_track` as a :ref:`Quaternion` that can be used elsewhere. + +If :ref:`root_motion_track` is not a path to a track of type :ref:`Animation.TYPE_ROTATION_3D`, returns ``Quaternion(0, 0, 0, 1)``. + +See also :ref:`root_motion_track` and :ref:`RootMotionView`. + +The most basic example is applying rotation to :ref:`CharacterBody3D`: + + +.. tabs:: + + .. code-tab:: gdscript + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation()) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_root_motion_rotation_accumulator: + +.. rst-class:: classref-method + +:ref:`Quaternion` **get_root_motion_rotation_accumulator**\ (\ ) |const| :ref:`🔗` + +Retrieve the blended value of the rotation tracks with the :ref:`root_motion_track` as a :ref:`Quaternion` that can be used elsewhere. + +This is necessary to apply the root motion position correctly, taking rotation into account. See also :ref:`get_root_motion_position()`. + +Also, this is useful in cases where you want to respect the initial key values of the animation. + +For example, if an animation with only one key ``Quaternion(0, 0, 0, 1)`` is played in the previous frame and then an animation with only one key ``Quaternion(0, 0.707, 0, 0.707)`` is played in the next frame, the difference can be calculated as follows: + + +.. tabs:: + + .. code-tab:: gdscript + + var prev_root_motion_rotation_accumulator + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_rotation_accumulator = animation_tree.get_root_motion_rotation_accumulator() + var difference = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator + prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator + transform.basis *= Basis(difference) + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_root_motion_scale: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_root_motion_scale**\ (\ ) |const| :ref:`🔗` + +Retrieve the motion delta of scale with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. + +If :ref:`root_motion_track` is not a path to a track of type :ref:`Animation.TYPE_SCALE_3D`, returns ``Vector3(0, 0, 0)``. + +See also :ref:`root_motion_track` and :ref:`RootMotionView`. + +The most basic example is applying scale to :ref:`CharacterBody3D`: + + +.. tabs:: + + .. code-tab:: gdscript + + var current_scale = Vector3(1, 1, 1) + var scale_accum = Vector3(1, 1, 1) + + func _process(delta): + if Input.is_action_just_pressed("animate"): + current_scale = get_scale() + scale_accum = Vector3(1, 1, 1) + state_machine.travel("Animate") + scale_accum += animation_tree.get_root_motion_scale() + set_scale(current_scale * scale_accum) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_get_root_motion_scale_accumulator: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_root_motion_scale_accumulator**\ (\ ) |const| :ref:`🔗` + +Retrieve the blended value of the scale tracks with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. + +For example, if an animation with only one key ``Vector3(1, 1, 1)`` is played in the previous frame and then an animation with only one key ``Vector3(2, 2, 2)`` is played in the next frame, the difference can be calculated as follows: + + +.. tabs:: + + .. code-tab:: gdscript + + var prev_root_motion_scale_accumulator + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_scale_accumulator = animation_tree.get_root_motion_scale_accumulator() + var difference = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator + prev_root_motion_scale_accumulator = current_root_motion_scale_accumulator + transform.basis = transform.basis.scaled(difference) + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_has_animation: + +.. rst-class:: classref-method + +:ref:`bool` **has_animation**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns ``true`` if the **AnimationMixer** stores an :ref:`Animation` with key ``name``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_has_animation_library: + +.. rst-class:: classref-method + +:ref:`bool` **has_animation_library**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns ``true`` if the **AnimationMixer** stores an :ref:`AnimationLibrary` with key ``name``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_remove_animation_library: + +.. rst-class:: classref-method + +|void| **remove_animation_library**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Removes the :ref:`AnimationLibrary` associated with the key ``name``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_method_rename_animation_library: + +.. rst-class:: classref-method + +|void| **rename_animation_library**\ (\ name\: :ref:`StringName`, newname\: :ref:`StringName`\ ) :ref:`🔗` + +Moves the :ref:`AnimationLibrary` associated with the key ``name`` to the key ``newname``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnode.rst b/classes/class_animationnode.rst index b9710bcbb7a..04bd61362a0 100644 --- a/classes/class_animationnode.rst +++ b/classes/class_animationnode.rst @@ -1,281 +1,522 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNode.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNode.xml. .. _class_AnimationNode: AnimationNode ============= -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AnimationNodeAdd2`, :ref:`AnimationNodeAdd3`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, :ref:`AnimationNodeOutput`, :ref:`AnimationNodeTimeScale`, :ref:`AnimationNodeTimeSeek`, :ref:`AnimationNodeTransition`, :ref:`AnimationRootNode` +**Inherited By:** :ref:`AnimationNodeExtension`, :ref:`AnimationNodeOutput`, :ref:`AnimationNodeSync`, :ref:`AnimationNodeTimeScale`, :ref:`AnimationNodeTimeSeek`, :ref:`AnimationRootNode` -Base resource for :ref:`AnimationTree` nodes. +Base class for :ref:`AnimationTree` nodes. Not related to scene nodes. + +.. rst-class:: classref-introduction-group Description ----------- Base resource for :ref:`AnimationTree` nodes. In general, it's not used directly, but you can create custom ones with custom blending formulas. -Inherit this when creating nodes mainly for use in :ref:`AnimationNodeBlendTree`, otherwise :ref:`AnimationRootNode` should be used instead. +Inherit this when creating animation nodes mainly for use in :ref:`AnimationNodeBlendTree`, otherwise :ref:`AnimationRootNode` should be used instead. + +You can access the time information as read-only parameter which is processed and stored in the previous frame for all nodes except :ref:`AnimationNodeOutput`. + +\ **Note:** If multiple inputs exist in the **AnimationNode**, which time information takes precedence depends on the type of **AnimationNode**. + +:: + + var current_length = $AnimationTree["parameters/AnimationNodeName/current_length"] + var current_position = $AnimationTree["parameters/AnimationNodeName/current_position"] + var current_delta = $AnimationTree["parameters/AnimationNodeName/current_delta"] + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------+--------------------------------------------------------------------+ -| :ref:`bool` | :ref:`filter_enabled` | -+-------------------------+--------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------+--------------------------------------------------------------------+ + | :ref:`bool` | :ref:`filter_enabled` | + +-------------------------+--------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_input` **(** :ref:`String` name **)** | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`blend_animation` **(** :ref:`StringName` animation, :ref:`float` time, :ref:`float` delta, :ref:`bool` seeked, :ref:`float` blend **)** | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`blend_input` **(** :ref:`int` input_index, :ref:`float` time, :ref:`bool` seek, :ref:`float` blend, :ref:`FilterAction` filter=0, :ref:`bool` optimize=true **)** | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`blend_node` **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`float` time, :ref:`bool` seek, :ref:`float` blend, :ref:`FilterAction` filter=0, :ref:`bool` optimize=true **)** | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_caption` **(** **)** virtual | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Object` | :ref:`get_child_by_name` **(** :ref:`String` name **)** virtual | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Dictionary` | :ref:`get_child_nodes` **(** **)** virtual | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_input_count` **(** **)** const | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_input_name` **(** :ref:`int` input **)** | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`get_parameter` **(** :ref:`StringName` name **)** const | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`get_parameter_default_value` **(** :ref:`StringName` name **)** virtual | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_parameter_list` **(** **)** virtual | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_filter` **(** **)** virtual | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_path_filtered` **(** :ref:`NodePath` path **)** const | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`process` **(** :ref:`float` time, :ref:`bool` seek **)** virtual | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_input` **(** :ref:`int` index **)** | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_filter_path` **(** :ref:`NodePath` path, :ref:`bool` enable **)** | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_parameter` **(** :ref:`StringName` name, :ref:`Variant` value **)** | -+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`_get_caption`\ (\ ) |virtual| |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationNode` | :ref:`_get_child_by_name`\ (\ name\: :ref:`StringName`\ ) |virtual| |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`_get_child_nodes`\ (\ ) |virtual| |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`_get_parameter_default_value`\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`_get_parameter_list`\ (\ ) |virtual| |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_has_filter`\ (\ ) |virtual| |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_is_parameter_read_only`\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_process`\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`add_input`\ (\ name\: :ref:`String`\ ) | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`blend_animation`\ (\ animation\: :ref:`StringName`, time\: :ref:`float`, delta\: :ref:`float`, seeked\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, looped_flag\: :ref:`LoopedFlag` = 0\ ) | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`blend_input`\ (\ input_index\: :ref:`int`, time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, filter\: :ref:`FilterAction` = 0, sync\: :ref:`bool` = true, test_only\: :ref:`bool` = false\ ) | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`blend_node`\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, filter\: :ref:`FilterAction` = 0, sync\: :ref:`bool` = true, test_only\: :ref:`bool` = false\ ) | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`find_input`\ (\ name\: :ref:`String`\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_input_count`\ (\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_input_name`\ (\ input\: :ref:`int`\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get_parameter`\ (\ name\: :ref:`StringName`\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_processing_animation_tree_instance_id`\ (\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_path_filtered`\ (\ path\: :ref:`NodePath`\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_process_testing`\ (\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_input`\ (\ index\: :ref:`int`\ ) | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_filter_path`\ (\ path\: :ref:`NodePath`, enable\: :ref:`bool`\ ) | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`set_input_name`\ (\ input\: :ref:`int`, name\: :ref:`String`\ ) | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_parameter`\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- -.. _class_AnimationNode_signal_removed_from_graph: +.. _class_AnimationNode_signal_animation_node_removed: + +.. rst-class:: classref-signal + +**animation_node_removed**\ (\ object_id\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` + +Emitted by nodes that inherit from this class and that have an internal tree when one of their animation nodes removes. The animation nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, and :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNode_signal_animation_node_renamed: + +.. rst-class:: classref-signal -- **removed_from_graph** **(** **)** +**animation_node_renamed**\ (\ object_id\: :ref:`int`, old_name\: :ref:`String`, new_name\: :ref:`String`\ ) :ref:`🔗` -Called when the node was removed from the graph. +Emitted by nodes that inherit from this class and that have an internal tree when one of their animation node names changes. The animation nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, and :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNode_signal_tree_changed: -- **tree_changed** **(** **)** +.. rst-class:: classref-signal + +**tree_changed**\ (\ ) :ref:`🔗` + +Emitted by nodes that inherit from this class and that have an internal tree when one of their animation nodes changes. The animation nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, :ref:`AnimationNodeBlendTree` and :ref:`AnimationNodeTransition`. + +.. rst-class:: classref-section-separator + +---- -Emitted by nodes that inherit from this class and that have an internal tree when one of their nodes changes. The nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, and :ref:`AnimationNodeBlendTree`. +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_AnimationNode_FilterAction: +.. rst-class:: classref-enumeration + +enum **FilterAction**: :ref:`🔗` + .. _class_AnimationNode_constant_FILTER_IGNORE: +.. rst-class:: classref-enumeration-constant + +:ref:`FilterAction` **FILTER_IGNORE** = ``0`` + +Do not use filtering. + .. _class_AnimationNode_constant_FILTER_PASS: +.. rst-class:: classref-enumeration-constant + +:ref:`FilterAction` **FILTER_PASS** = ``1`` + +Paths matching the filter will be allowed to pass. + .. _class_AnimationNode_constant_FILTER_STOP: +.. rst-class:: classref-enumeration-constant + +:ref:`FilterAction` **FILTER_STOP** = ``2`` + +Paths matching the filter will be discarded. + .. _class_AnimationNode_constant_FILTER_BLEND: -enum **FilterAction**: +.. rst-class:: classref-enumeration-constant -- **FILTER_IGNORE** = **0** --- Do not use filtering. +:ref:`FilterAction` **FILTER_BLEND** = ``3`` -- **FILTER_PASS** = **1** --- Paths matching the filter will be allowed to pass. +Paths matching the filter will be blended (by the blend value). -- **FILTER_STOP** = **2** --- Paths matching the filter will be discarded. +.. rst-class:: classref-section-separator + +---- -- **FILTER_BLEND** = **3** --- Paths matching the filter will be blended (by the blend value). +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AnimationNode_property_filter_enabled: -- :ref:`bool` **filter_enabled** +.. rst-class:: classref-property -+----------+---------------------------+ -| *Setter* | set_filter_enabled(value) | -+----------+---------------------------+ -| *Getter* | is_filter_enabled() | -+----------+---------------------------+ +:ref:`bool` **filter_enabled** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_filter_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_filter_enabled**\ (\ ) If ``true``, filtering is enabled. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- -.. _class_AnimationNode_method_add_input: +.. _class_AnimationNode_private_method__get_caption: + +.. rst-class:: classref-method -- void **add_input** **(** :ref:`String` name **)** +:ref:`String` **_get_caption**\ (\ ) |virtual| |const| :ref:`🔗` -Adds an input to the node. This is only useful for nodes created for use in an :ref:`AnimationNodeBlendTree`. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to override the text caption for this animation node. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_blend_animation: +.. _class_AnimationNode_private_method__get_child_by_name: + +.. rst-class:: classref-method + +:ref:`AnimationNode` **_get_child_by_name**\ (\ name\: :ref:`StringName`\ ) |virtual| |const| :ref:`🔗` -- void **blend_animation** **(** :ref:`StringName` animation, :ref:`float` time, :ref:`float` delta, :ref:`bool` seeked, :ref:`float` blend **)** +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return a child animation node by its ``name``. -Blend an animation by ``blend`` amount (name must be valid in the linked :ref:`AnimationPlayer`). A ``time`` and ``delta`` may be passed, as well as whether ``seek`` happened. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_blend_input: +.. _class_AnimationNode_private_method__get_child_nodes: + +.. rst-class:: classref-method -- :ref:`float` **blend_input** **(** :ref:`int` input_index, :ref:`float` time, :ref:`bool` seek, :ref:`float` blend, :ref:`FilterAction` filter=0, :ref:`bool` optimize=true **)** +:ref:`Dictionary` **_get_child_nodes**\ (\ ) |virtual| |const| :ref:`🔗` -Blend an input. This is only useful for nodes created for an :ref:`AnimationNodeBlendTree`. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute. A filter mode may be optionally passed (see :ref:`FilterAction` for options). +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return all child animation nodes in order as a ``name: node`` dictionary. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_blend_node: +.. _class_AnimationNode_private_method__get_parameter_default_value: -- :ref:`float` **blend_node** **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`float` time, :ref:`bool` seek, :ref:`float` blend, :ref:`FilterAction` filter=0, :ref:`bool` optimize=true **)** +.. rst-class:: classref-method -Blend another animation node (in case this node contains children animation nodes). This function is only useful if you inherit from :ref:`AnimationRootNode` instead, else editors will not display your node for addition. +:ref:`Variant` **_get_parameter_default_value**\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| :ref:`🔗` + +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return the default value of a ``parameter``. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_get_caption: +.. _class_AnimationNode_private_method__get_parameter_list: + +.. rst-class:: classref-method + +:ref:`Array` **_get_parameter_list**\ (\ ) |virtual| |const| :ref:`🔗` -- :ref:`String` **get_caption** **(** **)** virtual +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return a list of the properties on this animation node. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. Format is similar to :ref:`Object.get_property_list()`. -Gets the text caption for this node (used by some editors). +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_get_child_by_name: +.. _class_AnimationNode_private_method__has_filter: -- :ref:`Object` **get_child_by_name** **(** :ref:`String` name **)** virtual +.. rst-class:: classref-method -Gets a child node by index (used by editors inheriting from :ref:`AnimationRootNode`). +:ref:`bool` **_has_filter**\ (\ ) |virtual| |const| :ref:`🔗` + +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return whether the blend tree editor should display filter editing on this animation node. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_get_child_nodes: +.. _class_AnimationNode_private_method__is_parameter_read_only: + +.. rst-class:: classref-method + +:ref:`bool` **_is_parameter_read_only**\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| :ref:`🔗` -- :ref:`Dictionary` **get_child_nodes** **(** **)** virtual +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return whether the ``parameter`` is read-only. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. -Gets all children nodes in order as a ``name: node`` dictionary. Only useful when inheriting :ref:`AnimationRootNode`. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_get_input_count: +.. _class_AnimationNode_private_method__process: + +.. rst-class:: classref-method + +:ref:`float` **_process**\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| :ref:`🔗` + +**Deprecated:** Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future. -- :ref:`int` **get_input_count** **(** **)** const +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to run some code when this animation node is processed. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute. -Amount of inputs in this node, only useful for nodes that go into :ref:`AnimationNodeBlendTree`. +Here, call the :ref:`blend_input()`, :ref:`blend_node()` or :ref:`blend_animation()` functions. You can also use :ref:`get_parameter()` and :ref:`set_parameter()` to modify local memory. + +This function should return the delta. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_get_input_name: +.. _class_AnimationNode_method_add_input: -- :ref:`String` **get_input_name** **(** :ref:`int` input **)** +.. rst-class:: classref-method -Gets the name of an input by index. +:ref:`bool` **add_input**\ (\ name\: :ref:`String`\ ) :ref:`🔗` + +Adds an input to the animation node. This is only useful for animation nodes created for use in an :ref:`AnimationNodeBlendTree`. If the addition fails, returns ``false``. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_get_parameter: +.. _class_AnimationNode_method_blend_animation: + +.. rst-class:: classref-method + +|void| **blend_animation**\ (\ animation\: :ref:`StringName`, time\: :ref:`float`, delta\: :ref:`float`, seeked\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, looped_flag\: :ref:`LoopedFlag` = 0\ ) :ref:`🔗` + +Blends an animation by ``blend`` amount (name must be valid in the linked :ref:`AnimationPlayer`). A ``time`` and ``delta`` may be passed, as well as whether ``seeked`` happened. + +A ``looped_flag`` is used by internal processing immediately after the loop. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNode_method_blend_input: + +.. rst-class:: classref-method + +:ref:`float` **blend_input**\ (\ input_index\: :ref:`int`, time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, filter\: :ref:`FilterAction` = 0, sync\: :ref:`bool` = true, test_only\: :ref:`bool` = false\ ) :ref:`🔗` -- :ref:`Variant` **get_parameter** **(** :ref:`StringName` name **)** const +Blends an input. This is only useful for animation nodes created for an :ref:`AnimationNodeBlendTree`. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute. A filter mode may be optionally passed. -Gets the value of a parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_get_parameter_default_value: +.. _class_AnimationNode_method_blend_node: + +.. rst-class:: classref-method -- :ref:`Variant` **get_parameter_default_value** **(** :ref:`StringName` name **)** virtual +:ref:`float` **blend_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, filter\: :ref:`FilterAction` = 0, sync\: :ref:`bool` = true, test_only\: :ref:`bool` = false\ ) :ref:`🔗` -Gets the default value of a parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. +Blend another animation node (in case this animation node contains child animation nodes). This function is only useful if you inherit from :ref:`AnimationRootNode` instead, otherwise editors will not display your animation node for addition. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_get_parameter_list: +.. _class_AnimationNode_method_find_input: + +.. rst-class:: classref-method -- :ref:`Array` **get_parameter_list** **(** **)** virtual +:ref:`int` **find_input**\ (\ name\: :ref:`String`\ ) |const| :ref:`🔗` -Gets the property information for parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. Format is similar to :ref:`Object.get_property_list`. +Returns the input index which corresponds to ``name``. If not found, returns ``-1``. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_has_filter: +.. _class_AnimationNode_method_get_input_count: -- :ref:`bool` **has_filter** **(** **)** virtual +.. rst-class:: classref-method -Returns ``true`` whether you want the blend tree editor to display filter editing on this node. +:ref:`int` **get_input_count**\ (\ ) |const| :ref:`🔗` + +Amount of inputs in this animation node, only useful for animation nodes that go into :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNode_method_get_input_name: + +.. rst-class:: classref-method + +:ref:`String` **get_input_name**\ (\ input\: :ref:`int`\ ) |const| :ref:`🔗` + +Gets the name of an input by index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNode_method_get_parameter: + +.. rst-class:: classref-method + +:ref:`Variant` **get_parameter**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Gets the value of a parameter. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNode_method_get_processing_animation_tree_instance_id: + +.. rst-class:: classref-method + +:ref:`int` **get_processing_animation_tree_instance_id**\ (\ ) |const| :ref:`🔗` + +Returns the object id of the :ref:`AnimationTree` that owns this node. + +\ **Note:** This method should only be called from within the :ref:`AnimationNodeExtension._process_animation_node()` method, and will return an invalid id otherwise. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNode_method_is_path_filtered: -- :ref:`bool` **is_path_filtered** **(** :ref:`NodePath` path **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_path_filtered**\ (\ path\: :ref:`NodePath`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given path is filtered. -Returns ``true`` whether a given path is filtered. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNode_method_process: +.. _class_AnimationNode_method_is_process_testing: -- void **process** **(** :ref:`float` time, :ref:`bool` seek **)** virtual +.. rst-class:: classref-method -User-defined callback called when a custom node is processed. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute. +:ref:`bool` **is_process_testing**\ (\ ) |const| :ref:`🔗` -Here, call the :ref:`blend_input`, :ref:`blend_node` or :ref:`blend_animation` functions. You can also use :ref:`get_parameter` and :ref:`set_parameter` to modify local memory. +Returns ``true`` if this animation node is being processed in test-only mode. -This function should return the time left for the current animation to finish (if unsure, pass the value from the main blend being called). +.. rst-class:: classref-item-separator ---- .. _class_AnimationNode_method_remove_input: -- void **remove_input** **(** :ref:`int` index **)** +.. rst-class:: classref-method + +|void| **remove_input**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Removes an input, call this only when inactive. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNode_method_set_filter_path: -- void **set_filter_path** **(** :ref:`NodePath` path, :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_filter_path**\ (\ path\: :ref:`NodePath`, enable\: :ref:`bool`\ ) :ref:`🔗` Adds or removes a path for the filter. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNode_method_set_input_name: + +.. rst-class:: classref-method + +:ref:`bool` **set_input_name**\ (\ input\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` + +Sets the name of the input at the given ``input`` index. If the setting fails, returns ``false``. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNode_method_set_parameter: -- void **set_parameter** **(** :ref:`StringName` name, :ref:`Variant` value **)** +.. rst-class:: classref-method + +|void| **set_parameter**\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) :ref:`🔗` -Sets a custom parameter. These are used as local storage, because resources can be reused across the tree or scenes. +Sets a custom parameter. These are used as local memory, because resources can be reused across the tree or scenes. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeadd2.rst b/classes/class_animationnodeadd2.rst index 0e6f7004c08..4b4a283653c 100644 --- a/classes/class_animationnodeadd2.rst +++ b/classes/class_animationnodeadd2.rst @@ -1,49 +1,43 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeAdd2.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeAdd2.xml. .. _class_AnimationNodeAdd2: AnimationNodeAdd2 ================= -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Blends two animations additively inside of an :ref:`AnimationNodeBlendTree`. +.. rst-class:: classref-introduction-group + Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations additively based on an amount value in the ``[0.0, 1.0]`` range. - -Tutorials ---------- - -- :doc:`../tutorials/animation/animation_tree` +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations additively based on the amount value. -Properties ----------- +If the amount is greater than ``1.0``, the animation connected to "in" port is blended with the amplified animation connected to "add" port. -+-------------------------+----------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`sync` | ``false`` | -+-------------------------+----------------------------------------------------+-----------+ +If the amount is less than ``0.0``, the animation connected to "in" port is blended with the inverted animation connected to "add" port. -Property Descriptions ---------------------- +.. rst-class:: classref-introduction-group -.. _class_AnimationNodeAdd2_property_sync: - -- :ref:`bool` **sync** - -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_use_sync(value) | -+-----------+---------------------+ -| *Getter* | is_using_sync() | -+-----------+---------------------+ - -If ``true``, sets the ``optimization`` to ``false`` when calling :ref:`AnimationNode.blend_input`, forcing the blended animations to update every frame. +Tutorials +--------- +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeadd3.rst b/classes/class_animationnodeadd3.rst index 061e7c17df1..05c5c9c05f3 100644 --- a/classes/class_animationnodeadd3.rst +++ b/classes/class_animationnodeadd3.rst @@ -1,57 +1,51 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeAdd3.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeAdd3.xml. .. _class_AnimationNodeAdd3: AnimationNodeAdd3 ================= -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Blends two of three animations additively inside of an :ref:`AnimationNodeBlendTree`. +.. rst-class:: classref-introduction-group + Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations together additively out of three based on a value in the ``[-1.0, 1.0]`` range. +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations out of three additively out of three based on the amount value. -This node has three inputs: +This animation node has three inputs: - The base animation to add to -- A -add animation to blend with when the blend amount is in the ``[-1.0, 0.0]`` range. - -- A +add animation to blend with when the blend amount is in the ``[0.0, 1.0]`` range - -Tutorials ---------- +- A "-add" animation to blend with when the blend amount is negative -- :doc:`../tutorials/animation/animation_tree` +- A "+add" animation to blend with when the blend amount is positive -Properties ----------- +If the absolute value of the amount is greater than ``1.0``, the animation connected to "in" port is blended with the amplified animation connected to "-add"/"+add" port. -+-------------------------+----------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`sync` | ``false`` | -+-------------------------+----------------------------------------------------+-----------+ +.. rst-class:: classref-introduction-group -Property Descriptions ---------------------- - -.. _class_AnimationNodeAdd3_property_sync: - -- :ref:`bool` **sync** +Tutorials +--------- -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_use_sync(value) | -+-----------+---------------------+ -| *Getter* | is_using_sync() | -+-----------+---------------------+ +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -If ``true``, sets the ``optimization`` to ``false`` when calling :ref:`AnimationNode.blend_input`, forcing the blended animations to update every frame. +- `Third Person Shooter (TPS) Demo `__ +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeanimation.rst b/classes/class_animationnodeanimation.rst index f60ff766e65..e0fa3591ccb 100644 --- a/classes/class_animationnodeanimation.rst +++ b/classes/class_animationnodeanimation.rst @@ -1,49 +1,251 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeAnimation.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeAnimation.xml. .. _class_AnimationNodeAnimation: AnimationNodeAnimation ====================== -**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input animation to use in an :ref:`AnimationNodeBlendTree`. +An input animation for an :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-introduction-group Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. Only features one output set using the :ref:`animation` property. Use it as an input for :ref:`AnimationNode` that blend animations together. +A resource to add to an :ref:`AnimationNodeBlendTree`. Only has one output port using the :ref:`animation` property. Used as an input for :ref:`AnimationNode`\ s that blend animations together. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +- `3D Platformer Demo `__ + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------------------+-------------------------------------------------------------------+---------+ -| :ref:`StringName` | :ref:`animation` | ``@""`` | -+-------------------------------------+-------------------------------------------------------------------+---------+ +.. table:: + :widths: auto + + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`advance_on_start` | ``false`` | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`StringName` | :ref:`animation` | ``&""`` | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`LoopMode` | :ref:`loop_mode` | | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`PlayMode` | :ref:`play_mode` | ``0`` | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`start_offset` | | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`stretch_time_scale` | | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`timeline_length` | | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`use_custom_timeline` | ``false`` | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AnimationNodeAnimation_PlayMode: + +.. rst-class:: classref-enumeration + +enum **PlayMode**: :ref:`🔗` + +.. _class_AnimationNodeAnimation_constant_PLAY_MODE_FORWARD: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlayMode` **PLAY_MODE_FORWARD** = ``0`` + +Plays animation in forward direction. + +.. _class_AnimationNodeAnimation_constant_PLAY_MODE_BACKWARD: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlayMode` **PLAY_MODE_BACKWARD** = ``1`` + +Plays animation in backward direction. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- +.. _class_AnimationNodeAnimation_property_advance_on_start: + +.. rst-class:: classref-property + +:ref:`bool` **advance_on_start** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_advance_on_start**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_advance_on_start**\ (\ ) + +If ``true``, on receiving a request to play an animation from the start, the first frame is not drawn, but only processed, and playback starts from the next frame. + +See also the notes of :ref:`AnimationPlayer.play()`. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeAnimation_property_animation: -- :ref:`StringName` **animation** +.. rst-class:: classref-property -+-----------+----------------------+ -| *Default* | ``@""`` | -+-----------+----------------------+ -| *Setter* | set_animation(value) | -+-----------+----------------------+ -| *Getter* | get_animation() | -+-----------+----------------------+ +:ref:`StringName` **animation** = ``&""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_animation**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_animation**\ (\ ) Animation to use as an output. It is one of the animations provided by :ref:`AnimationTree.anim_player`. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_loop_mode: + +.. rst-class:: classref-property + +:ref:`LoopMode` **loop_mode** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode`\ ) +- :ref:`LoopMode` **get_loop_mode**\ (\ ) + +If :ref:`use_custom_timeline` is ``true``, override the loop settings of the original :ref:`Animation` resource with the value. + +\ **Note:** If the :ref:`Animation.loop_mode` isn't set to looping, the :ref:`Animation.track_set_interpolation_loop_wrap()` option will not be respected. If you cannot get the expected behavior, consider duplicating the :ref:`Animation` resource and changing the loop settings. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_play_mode: + +.. rst-class:: classref-property + +:ref:`PlayMode` **play_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_play_mode**\ (\ value\: :ref:`PlayMode`\ ) +- :ref:`PlayMode` **get_play_mode**\ (\ ) + +Determines the playback direction of the animation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_start_offset: + +.. rst-class:: classref-property + +:ref:`float` **start_offset** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_start_offset**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_start_offset**\ (\ ) + +If :ref:`use_custom_timeline` is ``true``, offset the start position of the animation. + +This is useful for adjusting which foot steps first in 3D walking animations. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_stretch_time_scale: + +.. rst-class:: classref-property + +:ref:`bool` **stretch_time_scale** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stretch_time_scale**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_stretching_time_scale**\ (\ ) + +If ``true``, scales the time so that the length specified in :ref:`timeline_length` is one cycle. + +This is useful for matching the periods of walking and running animations. + +If ``false``, the original animation length is respected. If you set the loop to :ref:`loop_mode`, the animation will loop in :ref:`timeline_length`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_timeline_length: + +.. rst-class:: classref-property + +:ref:`float` **timeline_length** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_timeline_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_timeline_length**\ (\ ) + +If :ref:`use_custom_timeline` is ``true``, offset the start position of the animation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_use_custom_timeline: + +.. rst-class:: classref-property + +:ref:`bool` **use_custom_timeline** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_custom_timeline**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_using_custom_timeline**\ (\ ) + +If ``true``, :ref:`AnimationNode` provides an animation based on the :ref:`Animation` resource with some parameters adjusted. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeblend2.rst b/classes/class_animationnodeblend2.rst index 8e829a6e3d5..4affaacd955 100644 --- a/classes/class_animationnodeblend2.rst +++ b/classes/class_animationnodeblend2.rst @@ -1,49 +1,45 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeBlend2.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeBlend2.xml. .. _class_AnimationNodeBlend2: AnimationNodeBlend2 =================== -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Blends two animations linearly inside of an :ref:`AnimationNodeBlendTree`. +.. rst-class:: classref-introduction-group + Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations linearly based on an amount value in the ``[0.0, 1.0]`` range. - -Tutorials ---------- - -- :doc:`../tutorials/animation/animation_tree` - -Properties ----------- +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations linearly based on the amount value. -+-------------------------+------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`sync` | ``false`` | -+-------------------------+------------------------------------------------------+-----------+ +In general, the blend value should be in the ``[0.0, 1.0]`` range. Values outside of this range can blend amplified or inverted animations, however, :ref:`AnimationNodeAdd2` works better for this purpose. -Property Descriptions ---------------------- +.. rst-class:: classref-introduction-group -.. _class_AnimationNodeBlend2_property_sync: +Tutorials +--------- -- :ref:`bool` **sync** +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_use_sync(value) | -+-----------+---------------------+ -| *Getter* | is_using_sync() | -+-----------+---------------------+ +- `3D Platformer Demo `__ -If ``true``, sets the ``optimization`` to ``false`` when calling :ref:`AnimationNode.blend_input`, forcing the blended animations to update every frame. +- `Third Person Shooter (TPS) Demo `__ +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeblend3.rst b/classes/class_animationnodeblend3.rst index d2905646a55..c8f86ae6f73 100644 --- a/classes/class_animationnodeblend3.rst +++ b/classes/class_animationnodeblend3.rst @@ -1,57 +1,49 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeBlend3.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeBlend3.xml. .. _class_AnimationNodeBlend3: AnimationNodeBlend3 =================== -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Blends two of three animations linearly inside of an :ref:`AnimationNodeBlendTree`. +.. rst-class:: classref-introduction-group + Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations together linearly out of three based on a value in the ``[-1.0, 1.0]`` range. - -This node has three inputs: - -- The base animation +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations out of three linearly out of three based on the amount value. -- A -blend animation to blend with when the blend amount is in the ``[-1.0, 0.0]`` range. +This animation node has three inputs: -- A +blend animation to blend with when the blend amount is in the ``[0.0, 1.0]`` range - -Tutorials ---------- +- The base animation to blend with -- :doc:`../tutorials/animation/animation_tree` +- A "-blend" animation to blend with when the blend amount is negative value -Properties ----------- +- A "+blend" animation to blend with when the blend amount is positive value -+-------------------------+------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`sync` | ``false`` | -+-------------------------+------------------------------------------------------+-----------+ +In general, the blend value should be in the ``[-1.0, 1.0]`` range. Values outside of this range can blend amplified animations, however, :ref:`AnimationNodeAdd3` works better for this purpose. -Property Descriptions ---------------------- +.. rst-class:: classref-introduction-group -.. _class_AnimationNodeBlend3_property_sync: - -- :ref:`bool` **sync** - -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_use_sync(value) | -+-----------+---------------------+ -| *Getter* | is_using_sync() | -+-----------+---------------------+ - -If ``true``, sets the ``optimization`` to ``false`` when calling :ref:`AnimationNode.blend_input`, forcing the blended animations to update every frame. +Tutorials +--------- +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeblendspace1d.rst b/classes/class_animationnodeblendspace1d.rst index f2921b2fb7c..85157dd62d3 100644 --- a/classes/class_animationnodeblendspace1d.rst +++ b/classes/class_animationnodeblendspace1d.rst @@ -1,185 +1,326 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeBlendSpace1D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeBlendSpace1D.xml. .. _class_AnimationNodeBlendSpace1D: AnimationNodeBlendSpace1D ========================= -**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Blends linearly between two of any number of :ref:`AnimationNode` of any type placed on a virtual axis. +A set of :ref:`AnimationRootNode`\ s placed on a virtual axis, crossfading between the two adjacent ones. Used by :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. +A resource used by :ref:`AnimationNodeBlendTree`. -This is a virtual axis on which you can add any type of :ref:`AnimationNode` using :ref:`add_blend_point`. +\ **AnimationNodeBlendSpace1D** represents a virtual axis on which any type of :ref:`AnimationRootNode`\ s can be added using :ref:`add_blend_point()`. Outputs the linear blend of the two :ref:`AnimationRootNode`\ s adjacent to the current value. -Outputs the linear blend of the two :ref:`AnimationNode`\ s closest to the node's current value. +You can set the extents of the axis with :ref:`min_space` and :ref:`max_space`. -You can set the extents of the axis using the :ref:`min_space` and :ref:`max_space`. +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------+--------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`max_space` | ``1.0`` | -+-----------------------------+--------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`min_space` | ``-1.0`` | -+-----------------------------+--------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`snap` | ``0.1`` | -+-----------------------------+--------------------------------------------------------------------------+-------------+ -| :ref:`String` | :ref:`value_label` | ``"value"`` | -+-----------------------------+--------------------------------------------------------------------------+-------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------+--------------------------------------------------------------------------+-------------+ + | :ref:`BlendMode` | :ref:`blend_mode` | ``0`` | + +------------------------------------------------------------+--------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`max_space` | ``1.0`` | + +------------------------------------------------------------+--------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`min_space` | ``-1.0`` | + +------------------------------------------------------------+--------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`snap` | ``0.1`` | + +------------------------------------------------------------+--------------------------------------------------------------------------+-------------+ + | :ref:`bool` | :ref:`sync` | ``false`` | + +------------------------------------------------------------+--------------------------------------------------------------------------+-------------+ + | :ref:`String` | :ref:`value_label` | ``"value"`` | + +------------------------------------------------------------+--------------------------------------------------------------------------+-------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_blend_point` **(** :ref:`AnimationRootNode` node, :ref:`float` pos, :ref:`int` at_index=-1 **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_blend_point_count` **(** **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AnimationRootNode` | :ref:`get_blend_point_node` **(** :ref:`int` point **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_blend_point_position` **(** :ref:`int` point **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_blend_point` **(** :ref:`int` point **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_blend_point_node` **(** :ref:`int` point, :ref:`AnimationRootNode` node **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_blend_point_position` **(** :ref:`int` point, :ref:`float` pos **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_blend_point`\ (\ node\: :ref:`AnimationRootNode`, pos\: :ref:`float`, at_index\: :ref:`int` = -1\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_blend_point_count`\ (\ ) |const| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationRootNode` | :ref:`get_blend_point_node`\ (\ point\: :ref:`int`\ ) |const| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_blend_point_position`\ (\ point\: :ref:`int`\ ) |const| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_blend_point`\ (\ point\: :ref:`int`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_blend_point_node`\ (\ point\: :ref:`int`, node\: :ref:`AnimationRootNode`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_blend_point_position`\ (\ point\: :ref:`int`, pos\: :ref:`float`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AnimationNodeBlendSpace1D_BlendMode: + +.. rst-class:: classref-enumeration + +enum **BlendMode**: :ref:`🔗` + +.. _class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_INTERPOLATED: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_INTERPOLATED** = ``0`` + +The interpolation between animations is linear. + +.. _class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_DISCRETE: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_DISCRETE** = ``1`` + +The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations. + +.. _class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_DISCRETE_CARRY: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_DISCRETE_CARRY** = ``2`` + +Similar to :ref:`BLEND_MODE_DISCRETE`, but starts the new animation at the last animation's playback position. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- +.. _class_AnimationNodeBlendSpace1D_property_blend_mode: + +.. rst-class:: classref-property + +:ref:`BlendMode` **blend_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_blend_mode**\ (\ value\: :ref:`BlendMode`\ ) +- :ref:`BlendMode` **get_blend_mode**\ (\ ) + +Controls the interpolation between animations. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeBlendSpace1D_property_max_space: -- :ref:`float` **max_space** +.. rst-class:: classref-property + +:ref:`float` **max_space** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``1.0`` | -+-----------+----------------------+ -| *Setter* | set_max_space(value) | -+-----------+----------------------+ -| *Getter* | get_max_space() | -+-----------+----------------------+ +- |void| **set_max_space**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_max_space**\ (\ ) -The blend space's axis's upper limit for the points' position. See :ref:`add_blend_point`. +The blend space's axis's upper limit for the points' position. See :ref:`add_blend_point()`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendSpace1D_property_min_space: -- :ref:`float` **min_space** +.. rst-class:: classref-property + +:ref:`float` **min_space** = ``-1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``-1.0`` | -+-----------+----------------------+ -| *Setter* | set_min_space(value) | -+-----------+----------------------+ -| *Getter* | get_min_space() | -+-----------+----------------------+ +- |void| **set_min_space**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_min_space**\ (\ ) -The blend space's axis's lower limit for the points' position. See :ref:`add_blend_point`. +The blend space's axis's lower limit for the points' position. See :ref:`add_blend_point()`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendSpace1D_property_snap: -- :ref:`float` **snap** +.. rst-class:: classref-property + +:ref:`float` **snap** = ``0.1`` :ref:`🔗` -+-----------+-----------------+ -| *Default* | ``0.1`` | -+-----------+-----------------+ -| *Setter* | set_snap(value) | -+-----------+-----------------+ -| *Getter* | get_snap() | -+-----------+-----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_snap**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_snap**\ (\ ) Position increment to snap to when moving a point on the axis. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeBlendSpace1D_property_sync: + +.. rst-class:: classref-property + +:ref:`bool` **sync** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_sync**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_using_sync**\ (\ ) + +If ``false``, the blended animations' frame are stopped when the blend value is ``0``. + +If ``true``, forcing the blended animations to advance frame. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace1D_property_value_label: -- :ref:`String` **value_label** +.. rst-class:: classref-property + +:ref:`String` **value_label** = ``"value"`` :ref:`🔗` -+-----------+------------------------+ -| *Default* | ``"value"`` | -+-----------+------------------------+ -| *Setter* | set_value_label(value) | -+-----------+------------------------+ -| *Getter* | get_value_label() | -+-----------+------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_value_label**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_value_label**\ (\ ) Label of the virtual axis of the blend space. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- .. _class_AnimationNodeBlendSpace1D_method_add_blend_point: -- void **add_blend_point** **(** :ref:`AnimationRootNode` node, :ref:`float` pos, :ref:`int` at_index=-1 **)** +.. rst-class:: classref-method + +|void| **add_blend_point**\ (\ node\: :ref:`AnimationRootNode`, pos\: :ref:`float`, at_index\: :ref:`int` = -1\ ) :ref:`🔗` Adds a new point that represents a ``node`` on the virtual axis at a given position set by ``pos``. You can insert it at a specific index using the ``at_index`` argument. If you use the default value for ``at_index``, the point is inserted at the end of the blend points array. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace1D_method_get_blend_point_count: -- :ref:`int` **get_blend_point_count** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_blend_point_count**\ (\ ) |const| :ref:`🔗` Returns the number of points on the blend axis. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace1D_method_get_blend_point_node: -- :ref:`AnimationRootNode` **get_blend_point_node** **(** :ref:`int` point **)** const +.. rst-class:: classref-method + +:ref:`AnimationRootNode` **get_blend_point_node**\ (\ point\: :ref:`int`\ ) |const| :ref:`🔗` Returns the :ref:`AnimationNode` referenced by the point at index ``point``. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace1D_method_get_blend_point_position: -- :ref:`float` **get_blend_point_position** **(** :ref:`int` point **)** const +.. rst-class:: classref-method + +:ref:`float` **get_blend_point_position**\ (\ point\: :ref:`int`\ ) |const| :ref:`🔗` Returns the position of the point at index ``point``. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace1D_method_remove_blend_point: -- void **remove_blend_point** **(** :ref:`int` point **)** +.. rst-class:: classref-method + +|void| **remove_blend_point**\ (\ point\: :ref:`int`\ ) :ref:`🔗` Removes the point at index ``point`` from the blend axis. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace1D_method_set_blend_point_node: -- void **set_blend_point_node** **(** :ref:`int` point, :ref:`AnimationRootNode` node **)** +.. rst-class:: classref-method + +|void| **set_blend_point_node**\ (\ point\: :ref:`int`, node\: :ref:`AnimationRootNode`\ ) :ref:`🔗` Changes the :ref:`AnimationNode` referenced by the point at index ``point``. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace1D_method_set_blend_point_position: -- void **set_blend_point_position** **(** :ref:`int` point, :ref:`float` pos **)** +.. rst-class:: classref-method + +|void| **set_blend_point_position**\ (\ point\: :ref:`int`, pos\: :ref:`float`\ ) :ref:`🔗` Updates the position of the point at index ``point`` on the blend axis. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeblendspace2d.rst b/classes/class_animationnodeblendspace2d.rst index df5a476a3dd..12bdec3c7de 100644 --- a/classes/class_animationnodeblendspace2d.rst +++ b/classes/class_animationnodeblendspace2d.rst @@ -1,305 +1,439 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeBlendSpace2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeBlendSpace2D.xml. .. _class_AnimationNodeBlendSpace2D: AnimationNodeBlendSpace2D ========================= -**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Blends linearly between three :ref:`AnimationNode` of any type placed in a 2D space. +A set of :ref:`AnimationRootNode`\ s placed on 2D coordinates, crossfading between the three adjacent ones. Used by :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. +A resource used by :ref:`AnimationNodeBlendTree`. + +\ **AnimationNodeBlendSpace2D** represents a virtual 2D space on which :ref:`AnimationRootNode`\ s are placed. Outputs the linear blend of the three adjacent animations using a :ref:`Vector2` weight. Adjacent in this context means the three :ref:`AnimationRootNode`\ s making up the triangle that contains the current value. -This node allows you to blend linearly between three animations using a :ref:`Vector2` weight. +You can add vertices to the blend space with :ref:`add_blend_point()` and automatically triangulate it by setting :ref:`auto_triangles` to ``true``. Otherwise, use :ref:`add_triangle()` and :ref:`remove_triangle()` to triangulate the blend space by hand. -You can add vertices to the blend space with :ref:`add_blend_point` and automatically triangulate it by setting :ref:`auto_triangles` to ``true``. Otherwise, use :ref:`add_triangle` and :ref:`remove_triangle` to create up the blend space by hand. +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`auto_triangles` | ``true`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------+ -| :ref:`BlendMode` | :ref:`blend_mode` | ``0`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------+ -| :ref:`Vector2` | :ref:`max_space` | ``Vector2( 1, 1 )`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------+ -| :ref:`Vector2` | :ref:`min_space` | ``Vector2( -1, -1 )`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------+ -| :ref:`Vector2` | :ref:`snap` | ``Vector2( 0.1, 0.1 )`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------+ -| :ref:`String` | :ref:`x_label` | ``"x"`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------+ -| :ref:`String` | :ref:`y_label` | ``"y"`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`auto_triangles` | ``true`` | + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + | :ref:`BlendMode` | :ref:`blend_mode` | ``0`` | + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector2` | :ref:`max_space` | ``Vector2(1, 1)`` | + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector2` | :ref:`min_space` | ``Vector2(-1, -1)`` | + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector2` | :ref:`snap` | ``Vector2(0.1, 0.1)`` | + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`sync` | ``false`` | + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + | :ref:`String` | :ref:`x_label` | ``"x"`` | + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + | :ref:`String` | :ref:`y_label` | ``"y"`` | + +------------------------------------------------------------+--------------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_blend_point` **(** :ref:`AnimationRootNode` node, :ref:`Vector2` pos, :ref:`int` at_index=-1 **)** | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_triangle` **(** :ref:`int` x, :ref:`int` y, :ref:`int` z, :ref:`int` at_index=-1 **)** | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_blend_point_count` **(** **)** const | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AnimationRootNode` | :ref:`get_blend_point_node` **(** :ref:`int` point **)** const | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_blend_point_position` **(** :ref:`int` point **)** const | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_triangle_count` **(** **)** const | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_triangle_point` **(** :ref:`int` triangle, :ref:`int` point **)** | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_blend_point` **(** :ref:`int` point **)** | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_triangle` **(** :ref:`int` triangle **)** | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_blend_point_node` **(** :ref:`int` point, :ref:`AnimationRootNode` node **)** | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_blend_point_position` **(** :ref:`int` point, :ref:`Vector2` pos **)** | -+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_blend_point`\ (\ node\: :ref:`AnimationRootNode`, pos\: :ref:`Vector2`, at_index\: :ref:`int` = -1\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_triangle`\ (\ x\: :ref:`int`, y\: :ref:`int`, z\: :ref:`int`, at_index\: :ref:`int` = -1\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_blend_point_count`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationRootNode` | :ref:`get_blend_point_node`\ (\ point\: :ref:`int`\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_blend_point_position`\ (\ point\: :ref:`int`\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_triangle_count`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_triangle_point`\ (\ triangle\: :ref:`int`, point\: :ref:`int`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_blend_point`\ (\ point\: :ref:`int`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_triangle`\ (\ triangle\: :ref:`int`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_blend_point_node`\ (\ point\: :ref:`int`, node\: :ref:`AnimationRootNode`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_blend_point_position`\ (\ point\: :ref:`int`, pos\: :ref:`Vector2`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_AnimationNodeBlendSpace2D_signal_triangles_updated: -- **triangles_updated** **(** **)** +.. rst-class:: classref-signal + +**triangles_updated**\ (\ ) :ref:`🔗` Emitted every time the blend space's triangles are created, removed, or when one of their vertices changes position. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Enumerations ------------ .. _enum_AnimationNodeBlendSpace2D_BlendMode: +.. rst-class:: classref-enumeration + +enum **BlendMode**: :ref:`🔗` + .. _class_AnimationNodeBlendSpace2D_constant_BLEND_MODE_INTERPOLATED: +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_INTERPOLATED** = ``0`` + +The interpolation between animations is linear. + .. _class_AnimationNodeBlendSpace2D_constant_BLEND_MODE_DISCRETE: +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_DISCRETE** = ``1`` + +The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations. + .. _class_AnimationNodeBlendSpace2D_constant_BLEND_MODE_DISCRETE_CARRY: -enum **BlendMode**: +.. rst-class:: classref-enumeration-constant -- **BLEND_MODE_INTERPOLATED** = **0** --- The interpolation between animations is linear. +:ref:`BlendMode` **BLEND_MODE_DISCRETE_CARRY** = ``2`` -- **BLEND_MODE_DISCRETE** = **1** --- The blend space plays the animation of the node the blending position is closest to. Useful for frame-by-frame 2D animations. +Similar to :ref:`BLEND_MODE_DISCRETE`, but starts the new animation at the last animation's playback position. -- **BLEND_MODE_DISCRETE_CARRY** = **2** --- Similar to :ref:`BLEND_MODE_DISCRETE`, but starts the new animation at the last animation's playback position. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AnimationNodeBlendSpace2D_property_auto_triangles: -- :ref:`bool` **auto_triangles** +.. rst-class:: classref-property + +:ref:`bool` **auto_triangles** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------------+ -| *Default* | ``true`` | -+-----------+---------------------------+ -| *Setter* | set_auto_triangles(value) | -+-----------+---------------------------+ -| *Getter* | get_auto_triangles() | -+-----------+---------------------------+ +- |void| **set_auto_triangles**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_auto_triangles**\ (\ ) -If ``true``, the blend space is triangulated automatically. The mesh updates every time you add or remove points with :ref:`add_blend_point` and :ref:`remove_blend_point`. +If ``true``, the blend space is triangulated automatically. The mesh updates every time you add or remove points with :ref:`add_blend_point()` and :ref:`remove_blend_point()`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendSpace2D_property_blend_mode: -- :ref:`BlendMode` **blend_mode** +.. rst-class:: classref-property + +:ref:`BlendMode` **blend_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_blend_mode(value) | -+-----------+-----------------------+ -| *Getter* | get_blend_mode() | -+-----------+-----------------------+ +- |void| **set_blend_mode**\ (\ value\: :ref:`BlendMode`\ ) +- :ref:`BlendMode` **get_blend_mode**\ (\ ) -Controls the interpolation between animations. See :ref:`BlendMode` constants. +Controls the interpolation between animations. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendSpace2D_property_max_space: -- :ref:`Vector2` **max_space** +.. rst-class:: classref-property + +:ref:`Vector2` **max_space** = ``Vector2(1, 1)`` :ref:`🔗` -+-----------+----------------------+ -| *Default* | ``Vector2( 1, 1 )`` | -+-----------+----------------------+ -| *Setter* | set_max_space(value) | -+-----------+----------------------+ -| *Getter* | get_max_space() | -+-----------+----------------------+ +.. rst-class:: classref-property-setget -The blend space's X and Y axes' upper limit for the points' position. See :ref:`add_blend_point`. +- |void| **set_max_space**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_max_space**\ (\ ) + +The blend space's X and Y axes' upper limit for the points' position. See :ref:`add_blend_point()`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendSpace2D_property_min_space: -- :ref:`Vector2` **min_space** +.. rst-class:: classref-property + +:ref:`Vector2` **min_space** = ``Vector2(-1, -1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_min_space**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_min_space**\ (\ ) -+-----------+-----------------------+ -| *Default* | ``Vector2( -1, -1 )`` | -+-----------+-----------------------+ -| *Setter* | set_min_space(value) | -+-----------+-----------------------+ -| *Getter* | get_min_space() | -+-----------+-----------------------+ +The blend space's X and Y axes' lower limit for the points' position. See :ref:`add_blend_point()`. -The blend space's X and Y axes' lower limit for the points' position. See :ref:`add_blend_point`. +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendSpace2D_property_snap: -- :ref:`Vector2` **snap** +.. rst-class:: classref-property -+-----------+-------------------------+ -| *Default* | ``Vector2( 0.1, 0.1 )`` | -+-----------+-------------------------+ -| *Setter* | set_snap(value) | -+-----------+-------------------------+ -| *Getter* | get_snap() | -+-----------+-------------------------+ +:ref:`Vector2` **snap** = ``Vector2(0.1, 0.1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_snap**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_snap**\ (\ ) Position increment to snap to when moving a point. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeBlendSpace2D_property_sync: + +.. rst-class:: classref-property + +:ref:`bool` **sync** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_sync**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_using_sync**\ (\ ) + +If ``false``, the blended animations' frame are stopped when the blend value is ``0``. + +If ``true``, forcing the blended animations to advance frame. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_property_x_label: -- :ref:`String` **x_label** +.. rst-class:: classref-property + +:ref:`String` **x_label** = ``"x"`` :ref:`🔗` -+-----------+--------------------+ -| *Default* | ``"x"`` | -+-----------+--------------------+ -| *Setter* | set_x_label(value) | -+-----------+--------------------+ -| *Getter* | get_x_label() | -+-----------+--------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_x_label**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_x_label**\ (\ ) Name of the blend space's X axis. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_property_y_label: -- :ref:`String` **y_label** +.. rst-class:: classref-property + +:ref:`String` **y_label** = ``"y"`` :ref:`🔗` -+-----------+--------------------+ -| *Default* | ``"y"`` | -+-----------+--------------------+ -| *Setter* | set_y_label(value) | -+-----------+--------------------+ -| *Getter* | get_y_label() | -+-----------+--------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_y_label**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_y_label**\ (\ ) Name of the blend space's Y axis. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- .. _class_AnimationNodeBlendSpace2D_method_add_blend_point: -- void **add_blend_point** **(** :ref:`AnimationRootNode` node, :ref:`Vector2` pos, :ref:`int` at_index=-1 **)** +.. rst-class:: classref-method + +|void| **add_blend_point**\ (\ node\: :ref:`AnimationRootNode`, pos\: :ref:`Vector2`, at_index\: :ref:`int` = -1\ ) :ref:`🔗` Adds a new point that represents a ``node`` at the position set by ``pos``. You can insert it at a specific index using the ``at_index`` argument. If you use the default value for ``at_index``, the point is inserted at the end of the blend points array. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_add_triangle: -- void **add_triangle** **(** :ref:`int` x, :ref:`int` y, :ref:`int` z, :ref:`int` at_index=-1 **)** +.. rst-class:: classref-method + +|void| **add_triangle**\ (\ x\: :ref:`int`, y\: :ref:`int`, z\: :ref:`int`, at_index\: :ref:`int` = -1\ ) :ref:`🔗` Creates a new triangle using three points ``x``, ``y``, and ``z``. Triangles can overlap. You can insert the triangle at a specific index using the ``at_index`` argument. If you use the default value for ``at_index``, the point is inserted at the end of the blend points array. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_get_blend_point_count: -- :ref:`int` **get_blend_point_count** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_blend_point_count**\ (\ ) |const| :ref:`🔗` Returns the number of points in the blend space. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_get_blend_point_node: -- :ref:`AnimationRootNode` **get_blend_point_node** **(** :ref:`int` point **)** const +.. rst-class:: classref-method + +:ref:`AnimationRootNode` **get_blend_point_node**\ (\ point\: :ref:`int`\ ) |const| :ref:`🔗` Returns the :ref:`AnimationRootNode` referenced by the point at index ``point``. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_get_blend_point_position: -- :ref:`Vector2` **get_blend_point_position** **(** :ref:`int` point **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **get_blend_point_position**\ (\ point\: :ref:`int`\ ) |const| :ref:`🔗` Returns the position of the point at index ``point``. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_get_triangle_count: -- :ref:`int` **get_triangle_count** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_triangle_count**\ (\ ) |const| :ref:`🔗` Returns the number of triangles in the blend space. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_get_triangle_point: -- :ref:`int` **get_triangle_point** **(** :ref:`int` triangle, :ref:`int` point **)** +.. rst-class:: classref-method + +:ref:`int` **get_triangle_point**\ (\ triangle\: :ref:`int`, point\: :ref:`int`\ ) :ref:`🔗` Returns the position of the point at index ``point`` in the triangle of index ``triangle``. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_remove_blend_point: -- void **remove_blend_point** **(** :ref:`int` point **)** +.. rst-class:: classref-method + +|void| **remove_blend_point**\ (\ point\: :ref:`int`\ ) :ref:`🔗` Removes the point at index ``point`` from the blend space. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_remove_triangle: -- void **remove_triangle** **(** :ref:`int` triangle **)** +.. rst-class:: classref-method + +|void| **remove_triangle**\ (\ triangle\: :ref:`int`\ ) :ref:`🔗` Removes the triangle at index ``triangle`` from the blend space. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_set_blend_point_node: -- void **set_blend_point_node** **(** :ref:`int` point, :ref:`AnimationRootNode` node **)** +.. rst-class:: classref-method + +|void| **set_blend_point_node**\ (\ point\: :ref:`int`, node\: :ref:`AnimationRootNode`\ ) :ref:`🔗` Changes the :ref:`AnimationNode` referenced by the point at index ``point``. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendSpace2D_method_set_blend_point_position: -- void **set_blend_point_position** **(** :ref:`int` point, :ref:`Vector2` pos **)** +.. rst-class:: classref-method + +|void| **set_blend_point_position**\ (\ point\: :ref:`int`, pos\: :ref:`Vector2`\ ) :ref:`🔗` -Updates the position of the point at index ``point`` on the blend axis. +Updates the position of the point at index ``point`` in the blend space. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeblendtree.rst b/classes/class_animationnodeblendtree.rst index b32c843ed14..eb4c125b785 100644 --- a/classes/class_animationnodeblendtree.rst +++ b/classes/class_animationnodeblendtree.rst @@ -1,172 +1,304 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeBlendTree.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeBlendTree.xml. .. _class_AnimationNodeBlendTree: AnimationNodeBlendTree ====================== -**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`AnimationTree` node resource that contains many blend type nodes. +A sub-tree of many type :ref:`AnimationNode`\ s used for complex animations. Used by :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group Description ----------- -This node may contain a sub-tree of any other blend type nodes, such as mix, blend2, blend3, one shot, etc. This is one of the most commonly used roots. +This animation node may contain a sub-tree of any other type animation nodes, such as :ref:`AnimationNodeTransition`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, etc. This is one of the most commonly used animation node roots. + +An :ref:`AnimationNodeOutput` node named ``output`` is created by default. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------------+-------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`graph_offset` | ``Vector2( 0, 0 )`` | -+-------------------------------+-------------------------------------------------------------------------+---------------------+ +.. table:: + :widths: auto + + +-------------------------------+-------------------------------------------------------------------------+-------------------+ + | :ref:`Vector2` | :ref:`graph_offset` | ``Vector2(0, 0)`` | + +-------------------------------+-------------------------------------------------------------------------+-------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_node` **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`Vector2` position=Vector2( 0, 0 ) **)** | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`connect_node` **(** :ref:`StringName` input_node, :ref:`int` input_index, :ref:`StringName` output_node **)** | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`disconnect_node` **(** :ref:`StringName` input_node, :ref:`int` input_index **)** | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AnimationNode` | :ref:`get_node` **(** :ref:`StringName` name **)** const | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_node_position` **(** :ref:`StringName` name **)** const | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_node` **(** :ref:`StringName` name **)** const | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_node` **(** :ref:`StringName` name **)** | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`rename_node` **(** :ref:`StringName` name, :ref:`StringName` new_name **)** | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_node_position` **(** :ref:`StringName` name, :ref:`Vector2` position **)** | -+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_node`\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`connect_node`\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`, output_node\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`disconnect_node`\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationNode` | :ref:`get_node`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_node_list`\ (\ ) |const| | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_node_position`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_node`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_node`\ (\ name\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`rename_node`\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_node_position`\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_AnimationNodeBlendTree_signal_node_changed: + +.. rst-class:: classref-signal + +**node_changed**\ (\ node_name\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when the input port information is changed. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Constants --------- .. _class_AnimationNodeBlendTree_constant_CONNECTION_OK: +.. rst-class:: classref-constant + +**CONNECTION_OK** = ``0`` :ref:`🔗` + +The connection was successful. + .. _class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_NO_INPUT: +.. rst-class:: classref-constant + +**CONNECTION_ERROR_NO_INPUT** = ``1`` :ref:`🔗` + +The input node is ``null``. + .. _class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_NO_INPUT_INDEX: +.. rst-class:: classref-constant + +**CONNECTION_ERROR_NO_INPUT_INDEX** = ``2`` :ref:`🔗` + +The specified input port is out of range. + .. _class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_NO_OUTPUT: +.. rst-class:: classref-constant + +**CONNECTION_ERROR_NO_OUTPUT** = ``3`` :ref:`🔗` + +The output node is ``null``. + .. _class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_SAME_NODE: +.. rst-class:: classref-constant + +**CONNECTION_ERROR_SAME_NODE** = ``4`` :ref:`🔗` + +Input and output nodes are the same. + .. _class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_CONNECTION_EXISTS: -- **CONNECTION_OK** = **0** --- The connection was successful. +.. rst-class:: classref-constant -- **CONNECTION_ERROR_NO_INPUT** = **1** --- The input node is ``null``. +**CONNECTION_ERROR_CONNECTION_EXISTS** = ``5`` :ref:`🔗` -- **CONNECTION_ERROR_NO_INPUT_INDEX** = **2** --- The specified input port is out of range. +The specified connection already exists. -- **CONNECTION_ERROR_NO_OUTPUT** = **3** --- The output node is ``null``. +.. rst-class:: classref-section-separator -- **CONNECTION_ERROR_SAME_NODE** = **4** --- Input and output nodes are the same. +---- -- **CONNECTION_ERROR_CONNECTION_EXISTS** = **5** --- The specified connection already exists. +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AnimationNodeBlendTree_property_graph_offset: -- :ref:`Vector2` **graph_offset** +.. rst-class:: classref-property + +:ref:`Vector2` **graph_offset** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``Vector2( 0, 0 )`` | -+-----------+-------------------------+ -| *Setter* | set_graph_offset(value) | -+-----------+-------------------------+ -| *Getter* | get_graph_offset() | -+-----------+-------------------------+ +- |void| **set_graph_offset**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_graph_offset**\ (\ ) + +The global offset of all sub animation nodes. + +.. rst-class:: classref-section-separator + +---- -The global offset of all sub-nodes. +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AnimationNodeBlendTree_method_add_node: -- void **add_node** **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`Vector2` position=Vector2( 0, 0 ) **)** +.. rst-class:: classref-method -Adds an :ref:`AnimationNode` at the given ``position``. The ``name`` is used to identify the created sub-node later. +|void| **add_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) :ref:`🔗` + +Adds an :ref:`AnimationNode` at the given ``position``. The ``name`` is used to identify the created sub animation node later. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendTree_method_connect_node: -- void **connect_node** **(** :ref:`StringName` input_node, :ref:`int` input_index, :ref:`StringName` output_node **)** +.. rst-class:: classref-method + +|void| **connect_node**\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`, output_node\: :ref:`StringName`\ ) :ref:`🔗` Connects the output of an :ref:`AnimationNode` as input for another :ref:`AnimationNode`, at the input port specified by ``input_index``. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeBlendTree_method_disconnect_node: -- void **disconnect_node** **(** :ref:`StringName` input_node, :ref:`int` input_index **)** +.. rst-class:: classref-method -Disconnects the node connected to the specified input. +|void| **disconnect_node**\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`\ ) :ref:`🔗` + +Disconnects the animation node connected to the specified input. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendTree_method_get_node: -- :ref:`AnimationNode` **get_node** **(** :ref:`StringName` name **)** const +.. rst-class:: classref-method + +:ref:`AnimationNode` **get_node**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the sub animation node with the specified ``name``. -Returns the sub-node with the specified ``name``. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeBlendTree_method_get_node_list: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`StringName`\] **get_node_list**\ (\ ) |const| :ref:`🔗` + +Returns a list containing the names of all sub animation nodes in this blend tree. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendTree_method_get_node_position: -- :ref:`Vector2` **get_node_position** **(** :ref:`StringName` name **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **get_node_position**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns the position of the sub-node with the specified ``name``. +Returns the position of the sub animation node with the specified ``name``. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendTree_method_has_node: -- :ref:`bool` **has_node** **(** :ref:`StringName` name **)** const +.. rst-class:: classref-method + +:ref:`bool` **has_node**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns ``true`` if a sub-node with specified ``name`` exists. +Returns ``true`` if a sub animation node with specified ``name`` exists. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendTree_method_remove_node: -- void **remove_node** **(** :ref:`StringName` name **)** +.. rst-class:: classref-method + +|void| **remove_node**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` -Removes a sub-node. +Removes a sub animation node. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendTree_method_rename_node: -- void **rename_node** **(** :ref:`StringName` name, :ref:`StringName` new_name **)** +.. rst-class:: classref-method + +|void| **rename_node**\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` -Changes the name of a sub-node. +Changes the name of a sub animation node. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeBlendTree_method_set_node_position: -- void **set_node_position** **(** :ref:`StringName` name, :ref:`Vector2` position **)** +.. rst-class:: classref-method + +|void| **set_node_position**\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) :ref:`🔗` -Modifies the position of a sub-node. +Modifies the position of a sub animation node. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeextension.rst b/classes/class_animationnodeextension.rst new file mode 100644 index 00000000000..f07792dfcc8 --- /dev/null +++ b/classes/class_animationnodeextension.rst @@ -0,0 +1,95 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeExtension.xml. + +.. _class_AnimationNodeExtension: + +AnimationNodeExtension +====================== + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Base class for extending :ref:`AnimationRootNode`\ s from GDScript, C#, or C++. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**AnimationNodeExtension** exposes the APIs of :ref:`AnimationRootNode` to allow users to extend it from GDScript, C#, or C++. This class is not meant to be used directly, but to be extended by other classes. It is used to create custom nodes for the :ref:`AnimationTree` system. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedFloat32Array` | :ref:`_process_animation_node`\ (\ playback_info\: :ref:`PackedFloat64Array`, test_only\: :ref:`bool`\ ) |virtual| |required| | + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_remaining_time`\ (\ node_info\: :ref:`PackedFloat32Array`, break_loop\: :ref:`bool`\ ) |static| | + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_looping`\ (\ node_info\: :ref:`PackedFloat32Array`\ ) |static| | + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AnimationNodeExtension_private_method__process_animation_node: + +.. rst-class:: classref-method + +:ref:`PackedFloat32Array` **_process_animation_node**\ (\ playback_info\: :ref:`PackedFloat64Array`, test_only\: :ref:`bool`\ ) |virtual| |required| :ref:`🔗` + +A version of the :ref:`AnimationNode._process()` method that is meant to be overridden by custom nodes. It returns a :ref:`PackedFloat32Array` with the processed animation data. + +The :ref:`PackedFloat64Array` parameter contains the playback information, containing the following values encoded as floating point numbers (in order): playback time and delta, start and end times, whether a seek was requested (encoded as a float greater than ``0``), whether the seek request was externally requested (encoded as a float greater than ``0``), the current :ref:`LoopedFlag` (encoded as a float), and the current blend weight. + +The function must return a :ref:`PackedFloat32Array` of the node's time info, containing the following values (in order): animation length, time position, delta, :ref:`LoopMode` (encoded as a float), whether the animation is about to end (encoded as a float greater than ``0``) and whether the animation is infinite (encoded as a float greater than ``0``). All values must be included in the returned array. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeExtension_method_get_remaining_time: + +.. rst-class:: classref-method + +:ref:`float` **get_remaining_time**\ (\ node_info\: :ref:`PackedFloat32Array`, break_loop\: :ref:`bool`\ ) |static| :ref:`🔗` + +Returns the animation's remaining time for the given node info. For looping animations, it will only return the remaining time if ``break_loop`` is ``true``, a large integer value will be returned otherwise. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeExtension_method_is_looping: + +.. rst-class:: classref-method + +:ref:`bool` **is_looping**\ (\ node_info\: :ref:`PackedFloat32Array`\ ) |static| :ref:`🔗` + +Returns ``true`` if the animation for the given ``node_info`` is looping. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeoneshot.rst b/classes/class_animationnodeoneshot.rst index be8bd9c0530..97b8e1ce9b4 100644 --- a/classes/class_animationnodeoneshot.rst +++ b/classes/class_animationnodeoneshot.rst @@ -1,170 +1,357 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeOneShot.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeOneShot.xml. .. _class_AnimationNodeOneShot: AnimationNodeOneShot ==================== -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Plays an animation once in :ref:`AnimationNodeBlendTree`. +Plays an animation once in an :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-introduction-group Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. This node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters. +A resource to add to an :ref:`AnimationNodeBlendTree`. This animation node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters. + +After setting the request and changing the animation playback, the one-shot node automatically clears the request on the next process frame by setting its ``request`` value to :ref:`ONE_SHOT_REQUEST_NONE`. + + +.. tabs:: + + .. code-tab:: gdscript + + # Play child animation connected to "shot" port. + animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE + + # Abort child animation connected to "shot" port. + animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT + + # Abort child animation with fading out connected to "shot" port. + animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FADE_OUT) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FADE_OUT + + # Get current state (read-only). + animation_tree.get("parameters/OneShot/active") + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/active"] + + # Get current internal state (read-only). + animation_tree.get("parameters/OneShot/internal_active") + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/internal_active"] + + .. code-tab:: csharp + + // Play child animation connected to "shot" port. + animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Fire); + + // Abort child animation connected to "shot" port. + animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Abort); + + // Abort child animation with fading out connected to "shot" port. + animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.FadeOut); + + // Get current state (read-only). + animationTree.Get("parameters/OneShot/active"); + + // Get current internal state (read-only). + animationTree.Get("parameters/OneShot/internal_active"); + + + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+-----------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`autorestart` | ``false`` | -+---------------------------+-----------------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`autorestart_delay` | ``1.0`` | -+---------------------------+-----------------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`autorestart_random_delay` | ``0.0`` | -+---------------------------+-----------------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`fadein_time` | ``0.1`` | -+---------------------------+-----------------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`fadeout_time` | ``0.1`` | -+---------------------------+-----------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`sync` | ``false`` | -+---------------------------+-----------------------------------------------------------------------------------------------+-----------+ - -Methods -------- - -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`MixMode` | :ref:`get_mix_mode` **(** **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_mix_mode` **(** :ref:`MixMode` mode **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`autorestart` | ``false`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`autorestart_delay` | ``1.0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`autorestart_random_delay` | ``0.0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`break_loop_at_end` | ``false`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`Curve` | :ref:`fadein_curve` | | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`fadein_time` | ``0.0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`Curve` | :ref:`fadeout_curve` | | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`fadeout_time` | ``0.0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`MixMode` | :ref:`mix_mode` | ``0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ +.. _enum_AnimationNodeOneShot_OneShotRequest: + +.. rst-class:: classref-enumeration + +enum **OneShotRequest**: :ref:`🔗` + +.. _class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`OneShotRequest` **ONE_SHOT_REQUEST_NONE** = ``0`` + +The default state of the request. Nothing is done. + +.. _class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_FIRE: + +.. rst-class:: classref-enumeration-constant + +:ref:`OneShotRequest` **ONE_SHOT_REQUEST_FIRE** = ``1`` + +The request to play the animation connected to "shot" port. + +.. _class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_ABORT: + +.. rst-class:: classref-enumeration-constant + +:ref:`OneShotRequest` **ONE_SHOT_REQUEST_ABORT** = ``2`` + +The request to stop the animation connected to "shot" port. + +.. _class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_FADE_OUT: + +.. rst-class:: classref-enumeration-constant + +:ref:`OneShotRequest` **ONE_SHOT_REQUEST_FADE_OUT** = ``3`` + +The request to fade out the animation connected to "shot" port. + +.. rst-class:: classref-item-separator + +---- + .. _enum_AnimationNodeOneShot_MixMode: +.. rst-class:: classref-enumeration + +enum **MixMode**: :ref:`🔗` + .. _class_AnimationNodeOneShot_constant_MIX_MODE_BLEND: +.. rst-class:: classref-enumeration-constant + +:ref:`MixMode` **MIX_MODE_BLEND** = ``0`` + +Blends two animations. See also :ref:`AnimationNodeBlend2`. + .. _class_AnimationNodeOneShot_constant_MIX_MODE_ADD: -enum **MixMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`MixMode` **MIX_MODE_ADD** = ``1`` -- **MIX_MODE_BLEND** = **0** +Blends two animations additively. See also :ref:`AnimationNodeAdd2`. -- **MIX_MODE_ADD** = **1** +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AnimationNodeOneShot_property_autorestart: -- :ref:`bool` **autorestart** +.. rst-class:: classref-property + +:ref:`bool` **autorestart** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``false`` | -+-----------+------------------------+ -| *Setter* | set_autorestart(value) | -+-----------+------------------------+ -| *Getter* | has_autorestart() | -+-----------+------------------------+ +- |void| **set_autorestart**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **has_autorestart**\ (\ ) If ``true``, the sub-animation will restart automatically after finishing. +In other words, to start auto restarting, the animation must be played once with the :ref:`ONE_SHOT_REQUEST_FIRE` request. The :ref:`ONE_SHOT_REQUEST_ABORT` request stops the auto restarting, but it does not disable the :ref:`autorestart` itself. So, the :ref:`ONE_SHOT_REQUEST_FIRE` request will start auto restarting again. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeOneShot_property_autorestart_delay: -- :ref:`float` **autorestart_delay** +.. rst-class:: classref-property + +:ref:`float` **autorestart_delay** = ``1.0`` :ref:`🔗` -+-----------+------------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------------+ -| *Setter* | set_autorestart_delay(value) | -+-----------+------------------------------+ -| *Getter* | get_autorestart_delay() | -+-----------+------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_autorestart_delay**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_autorestart_delay**\ (\ ) The delay after which the automatic restart is triggered, in seconds. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeOneShot_property_autorestart_random_delay: -- :ref:`float` **autorestart_random_delay** +.. rst-class:: classref-property + +:ref:`float` **autorestart_random_delay** = ``0.0`` :ref:`🔗` -+-----------+-------------------------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------------------------+ -| *Setter* | set_autorestart_random_delay(value) | -+-----------+-------------------------------------+ -| *Getter* | get_autorestart_random_delay() | -+-----------+-------------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_autorestart_random_delay**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_autorestart_random_delay**\ (\ ) If :ref:`autorestart` is ``true``, a random additional delay (in seconds) between 0 and this value will be added to :ref:`autorestart_delay`. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeOneShot_property_break_loop_at_end: + +.. rst-class:: classref-property + +:ref:`bool` **break_loop_at_end** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_break_loop_at_end**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_loop_broken_at_end**\ (\ ) + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeOneShot_property_fadein_curve: + +.. rst-class:: classref-property + +:ref:`Curve` **fadein_curve** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_fadein_curve**\ (\ value\: :ref:`Curve`\ ) +- :ref:`Curve` **get_fadein_curve**\ (\ ) + +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeOneShot_property_fadein_time: -- :ref:`float` **fadein_time** +.. rst-class:: classref-property + +:ref:`float` **fadein_time** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_fadein_time**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_fadein_time**\ (\ ) + +The fade-in duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a cross-fade that starts at 0 second and ends at 1 second during the animation. + +\ **Note:** **AnimationNodeOneShot** transitions the current state after the fading has finished. -+-----------+------------------------+ -| *Default* | ``0.1`` | -+-----------+------------------------+ -| *Setter* | set_fadein_time(value) | -+-----------+------------------------+ -| *Getter* | get_fadein_time() | -+-----------+------------------------+ +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNodeOneShot_property_fadeout_time: +.. _class_AnimationNodeOneShot_property_fadeout_curve: + +.. rst-class:: classref-property + +:ref:`Curve` **fadeout_curve** :ref:`🔗` -- :ref:`float` **fadeout_time** +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``0.1`` | -+-----------+-------------------------+ -| *Setter* | set_fadeout_time(value) | -+-----------+-------------------------+ -| *Getter* | get_fadeout_time() | -+-----------+-------------------------+ +- |void| **set_fadeout_curve**\ (\ value\: :ref:`Curve`\ ) +- :ref:`Curve` **get_fadeout_curve**\ (\ ) + +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNodeOneShot_property_sync: +.. _class_AnimationNodeOneShot_property_fadeout_time: + +.. rst-class:: classref-property + +:ref:`float` **fadeout_time** = ``0.0`` :ref:`🔗` -- :ref:`bool` **sync** +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_use_sync(value) | -+-----------+---------------------+ -| *Getter* | is_using_sync() | -+-----------+---------------------+ +- |void| **set_fadeout_time**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_fadeout_time**\ (\ ) -Method Descriptions -------------------- +The fade-out duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a cross-fade that starts at 4 second and ends at 5 second during the animation. -.. _class_AnimationNodeOneShot_method_get_mix_mode: +\ **Note:** **AnimationNodeOneShot** transitions the current state after the fading has finished. -- :ref:`MixMode` **get_mix_mode** **(** **)** const +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNodeOneShot_method_set_mix_mode: +.. _class_AnimationNodeOneShot_property_mix_mode: + +.. rst-class:: classref-property + +:ref:`MixMode` **mix_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mix_mode**\ (\ value\: :ref:`MixMode`\ ) +- :ref:`MixMode` **get_mix_mode**\ (\ ) -- void **set_mix_mode** **(** :ref:`MixMode` mode **)** +The blend type. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeoutput.rst b/classes/class_animationnodeoutput.rst index ab5c4937d36..36c14f1c809 100644 --- a/classes/class_animationnodeoutput.rst +++ b/classes/class_animationnodeoutput.rst @@ -1,20 +1,43 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeOutput.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeOutput.xml. .. _class_AnimationNodeOutput: AnimationNodeOutput =================== -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Generic output node to be added to :ref:`AnimationNodeBlendTree`. +The animation output node of an :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A node created automatically in an :ref:`AnimationNodeBlendTree` that outputs the final animation. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +- `3D Platformer Demo `__ + +- `Third Person Shooter (TPS) Demo `__ +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodestatemachine.rst b/classes/class_animationnodestatemachine.rst index 143b57eea4b..3724360ee36 100644 --- a/classes/class_animationnodestatemachine.rst +++ b/classes/class_animationnodestatemachine.rst @@ -1,266 +1,462 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeStateMachine.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeStateMachine.xml. .. _class_AnimationNodeStateMachine: AnimationNodeStateMachine ========================= -**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -State machine for control of animations. +A state machine with multiple :ref:`AnimationRootNode`\ s, used by :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group Description ----------- -Contains multiple nodes representing animation states, connected in a graph. Node transitions can be configured to happen automatically or via code, using a shortest-path algorithm. Retrieve the :ref:`AnimationNodeStateMachinePlayback` object from the :ref:`AnimationTree` node to control it programmatically. +Contains multiple :ref:`AnimationRootNode`\ s representing animation states, connected in a graph. State transitions can be configured to happen automatically or via code, using a shortest-path algorithm. Retrieve the :ref:`AnimationNodeStateMachinePlayback` object from the :ref:`AnimationTree` node to control it programmatically. + -**Example:** +.. tabs:: -:: + .. code-tab:: gdscript var state_machine = $AnimationTree.get("parameters/playback") state_machine.travel("some_state") + .. code-tab:: csharp + + var stateMachine = GetNode("AnimationTree").Get("parameters/playback") as AnimationNodeStateMachinePlayback; + stateMachine.Travel("some_state"); + + + +.. rst-class:: classref-introduction-group + Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`allow_transition_to_self` | ``false`` | + +--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`reset_ends` | ``false`` | + +--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`StateMachineType` | :ref:`state_machine_type` | ``0`` | + +--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_node` **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`Vector2` position=Vector2( 0, 0 ) **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_transition` **(** :ref:`StringName` from, :ref:`StringName` to, :ref:`AnimationNodeStateMachineTransition` transition **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_end_node` **(** **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_graph_offset` **(** **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AnimationNode` | :ref:`get_node` **(** :ref:`StringName` name **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_node_name` **(** :ref:`AnimationNode` node **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_node_position` **(** :ref:`StringName` name **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_start_node` **(** **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AnimationNodeStateMachineTransition` | :ref:`get_transition` **(** :ref:`int` idx **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_transition_count` **(** **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_transition_from` **(** :ref:`int` idx **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_transition_to` **(** :ref:`int` idx **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_node` **(** :ref:`StringName` name **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_transition` **(** :ref:`StringName` from, :ref:`StringName` to **)** const | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_node` **(** :ref:`StringName` name **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_transition` **(** :ref:`StringName` from, :ref:`StringName` to **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_transition_by_index` **(** :ref:`int` idx **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`rename_node` **(** :ref:`StringName` name, :ref:`StringName` new_name **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`replace_node` **(** :ref:`StringName` name, :ref:`AnimationNode` node **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_end_node` **(** :ref:`StringName` name **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_graph_offset` **(** :ref:`Vector2` offset **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_node_position` **(** :ref:`StringName` name, :ref:`Vector2` position **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_start_node` **(** :ref:`StringName` name **)** | -+---------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_node`\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_transition`\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`, transition\: :ref:`AnimationNodeStateMachineTransition`\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_graph_offset`\ (\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationNode` | :ref:`get_node`\ (\ name\: :ref:`StringName`\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_node_list`\ (\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_node_name`\ (\ node\: :ref:`AnimationNode`\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_node_position`\ (\ name\: :ref:`StringName`\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationNodeStateMachineTransition` | :ref:`get_transition`\ (\ idx\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_transition_count`\ (\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_transition_from`\ (\ idx\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_transition_to`\ (\ idx\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_node`\ (\ name\: :ref:`StringName`\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_transition`\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_node`\ (\ name\: :ref:`StringName`\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_transition`\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_transition_by_index`\ (\ idx\: :ref:`int`\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`rename_node`\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`replace_node`\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_graph_offset`\ (\ offset\: :ref:`Vector2`\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_node_position`\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AnimationNodeStateMachine_StateMachineType: + +.. rst-class:: classref-enumeration + +enum **StateMachineType**: :ref:`🔗` + +.. _class_AnimationNodeStateMachine_constant_STATE_MACHINE_TYPE_ROOT: + +.. rst-class:: classref-enumeration-constant + +:ref:`StateMachineType` **STATE_MACHINE_TYPE_ROOT** = ``0`` + +Seeking to the beginning is treated as playing from the start state. Transition to the end state is treated as exiting the state machine. + +.. _class_AnimationNodeStateMachine_constant_STATE_MACHINE_TYPE_NESTED: + +.. rst-class:: classref-enumeration-constant + +:ref:`StateMachineType` **STATE_MACHINE_TYPE_NESTED** = ``1`` + +Seeking to the beginning is treated as seeking to the beginning of the animation in the current state. Transition to the end state, or the absence of transitions in each state, is treated as exiting the state machine. + +.. _class_AnimationNodeStateMachine_constant_STATE_MACHINE_TYPE_GROUPED: + +.. rst-class:: classref-enumeration-constant + +:ref:`StateMachineType` **STATE_MACHINE_TYPE_GROUPED** = ``2`` + +This is a grouped state machine that can be controlled from a parent state machine. It does not work independently. There must be a state machine with :ref:`state_machine_type` of :ref:`STATE_MACHINE_TYPE_ROOT` or :ref:`STATE_MACHINE_TYPE_NESTED` in the parent or ancestor. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimationNodeStateMachine_property_allow_transition_to_self: + +.. rst-class:: classref-property + +:ref:`bool` **allow_transition_to_self** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_allow_transition_to_self**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_allow_transition_to_self**\ (\ ) + +If ``true``, allows teleport to the self state with :ref:`AnimationNodeStateMachinePlayback.travel()`. When the reset option is enabled in :ref:`AnimationNodeStateMachinePlayback.travel()`, the animation is restarted. If ``false``, nothing happens on the teleportation to the self state. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachine_property_reset_ends: + +.. rst-class:: classref-property + +:ref:`bool` **reset_ends** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_reset_ends**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **are_ends_reset**\ (\ ) + +If ``true``, treat the cross-fade to the start and end nodes as a blend with the RESET animation. + +In most cases, when additional cross-fades are performed in the parent :ref:`AnimationNode` of the state machine, setting this property to ``false`` and matching the cross-fade time of the parent :ref:`AnimationNode` and the state machine's start node and end node gives good results. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachine_property_state_machine_type: + +.. rst-class:: classref-property + +:ref:`StateMachineType` **state_machine_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_state_machine_type**\ (\ value\: :ref:`StateMachineType`\ ) +- :ref:`StateMachineType` **get_state_machine_type**\ (\ ) + +This property can define the process of transitions for different use cases. See also :ref:`StateMachineType`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AnimationNodeStateMachine_method_add_node: -- void **add_node** **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`Vector2` position=Vector2( 0, 0 ) **)** +.. rst-class:: classref-method -Adds a new node to the graph. The ``position`` is used for display in the editor. +|void| **add_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) :ref:`🔗` + +Adds a new animation node to the graph. The ``position`` is used for display in the editor. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_add_transition: -- void **add_transition** **(** :ref:`StringName` from, :ref:`StringName` to, :ref:`AnimationNodeStateMachineTransition` transition **)** +.. rst-class:: classref-method -Adds a transition between the given nodes. - ----- +|void| **add_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`, transition\: :ref:`AnimationNodeStateMachineTransition`\ ) :ref:`🔗` -.. _class_AnimationNodeStateMachine_method_get_end_node: +Adds a transition between the given animation nodes. -- :ref:`String` **get_end_node** **(** **)** const - -Returns the graph's end node. +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_get_graph_offset: -- :ref:`Vector2` **get_graph_offset** **(** **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **get_graph_offset**\ (\ ) |const| :ref:`🔗` Returns the draw offset of the graph. Used for display in the editor. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachine_method_get_node: -- :ref:`AnimationNode` **get_node** **(** :ref:`StringName` name **)** const +.. rst-class:: classref-method + +:ref:`AnimationNode` **get_node**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the animation node with the given name. +.. rst-class:: classref-item-separator + ---- -.. _class_AnimationNodeStateMachine_method_get_node_name: +.. _class_AnimationNodeStateMachine_method_get_node_list: -- :ref:`StringName` **get_node_name** **(** :ref:`AnimationNode` node **)** const +.. rst-class:: classref-method -Returns the given animation node's name. +:ref:`Array`\[:ref:`StringName`\] **get_node_list**\ (\ ) |const| :ref:`🔗` + +Returns a list containing the names of all animation nodes in this state machine. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNodeStateMachine_method_get_node_position: +.. _class_AnimationNodeStateMachine_method_get_node_name: + +.. rst-class:: classref-method -- :ref:`Vector2` **get_node_position** **(** :ref:`StringName` name **)** const +:ref:`StringName` **get_node_name**\ (\ node\: :ref:`AnimationNode`\ ) |const| :ref:`🔗` + +Returns the given animation node's name. -Returns the given node's coordinates. Used for display in the editor. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNodeStateMachine_method_get_start_node: +.. _class_AnimationNodeStateMachine_method_get_node_position: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_node_position**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` -- :ref:`String` **get_start_node** **(** **)** const +Returns the given animation node's coordinates. Used for display in the editor. -Returns the graph's end node. +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_get_transition: -- :ref:`AnimationNodeStateMachineTransition` **get_transition** **(** :ref:`int` idx **)** const +.. rst-class:: classref-method + +:ref:`AnimationNodeStateMachineTransition` **get_transition**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given transition. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachine_method_get_transition_count: -- :ref:`int` **get_transition_count** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_transition_count**\ (\ ) |const| :ref:`🔗` Returns the number of connections in the graph. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachine_method_get_transition_from: -- :ref:`StringName` **get_transition_from** **(** :ref:`int` idx **)** const +.. rst-class:: classref-method + +:ref:`StringName` **get_transition_from**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given transition's start node. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachine_method_get_transition_to: -- :ref:`StringName` **get_transition_to** **(** :ref:`int` idx **)** const +.. rst-class:: classref-method + +:ref:`StringName` **get_transition_to**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given transition's end node. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachine_method_has_node: -- :ref:`bool` **has_node** **(** :ref:`StringName` name **)** const +.. rst-class:: classref-method + +:ref:`bool` **has_node**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns ``true`` if the graph contains the given node. +Returns ``true`` if the graph contains the given animation node. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_has_transition: -- :ref:`bool` **has_transition** **(** :ref:`StringName` from, :ref:`StringName` to **)** const +.. rst-class:: classref-method + +:ref:`bool` **has_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns ``true`` if there is a transition between the given nodes. +Returns ``true`` if there is a transition between the given animation nodes. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_remove_node: -- void **remove_node** **(** :ref:`StringName` name **)** +.. rst-class:: classref-method + +|void| **remove_node**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Deletes the given animation node from the graph. -Deletes the given node from the graph. +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_remove_transition: -- void **remove_transition** **(** :ref:`StringName` from, :ref:`StringName` to **)** +.. rst-class:: classref-method -Deletes the transition between the two specified nodes. +|void| **remove_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`\ ) :ref:`🔗` + +Deletes the transition between the two specified animation nodes. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_remove_transition_by_index: -- void **remove_transition_by_index** **(** :ref:`int` idx **)** +.. rst-class:: classref-method + +|void| **remove_transition_by_index**\ (\ idx\: :ref:`int`\ ) :ref:`🔗` Deletes the given transition by index. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachine_method_rename_node: -- void **rename_node** **(** :ref:`StringName` name, :ref:`StringName` new_name **)** +.. rst-class:: classref-method -Renames the given node. +|void| **rename_node**\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` + +Renames the given animation node. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_replace_node: -- void **replace_node** **(** :ref:`StringName` name, :ref:`AnimationNode` node **)** - ----- +.. rst-class:: classref-method -.. _class_AnimationNodeStateMachine_method_set_end_node: +|void| **replace_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`\ ) :ref:`🔗` -- void **set_end_node** **(** :ref:`StringName` name **)** +Replaces the given animation node with a new animation node. -Sets the given node as the graph end point. +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachine_method_set_graph_offset: -- void **set_graph_offset** **(** :ref:`Vector2` offset **)** +.. rst-class:: classref-method + +|void| **set_graph_offset**\ (\ offset\: :ref:`Vector2`\ ) :ref:`🔗` Sets the draw offset of the graph. Used for display in the editor. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachine_method_set_node_position: -- void **set_node_position** **(** :ref:`StringName` name, :ref:`Vector2` position **)** - -Sets the node's coordinates. Used for display in the editor. - ----- - -.. _class_AnimationNodeStateMachine_method_set_start_node: +.. rst-class:: classref-method -- void **set_start_node** **(** :ref:`StringName` name **)** +|void| **set_node_position**\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) :ref:`🔗` -Sets the given node as the graph start point. +Sets the animation node's coordinates. Used for display in the editor. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodestatemachineplayback.rst b/classes/class_animationnodestatemachineplayback.rst index 4017277bf90..3eb264a8213 100644 --- a/classes/class_animationnodestatemachineplayback.rst +++ b/classes/class_animationnodestatemachineplayback.rst @@ -1,105 +1,318 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeStateMachinePlayback.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeStateMachinePlayback.xml. .. _class_AnimationNodeStateMachinePlayback: AnimationNodeStateMachinePlayback ================================= -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Playback control for :ref:`AnimationNodeStateMachine`. +Provides playback control for an :ref:`AnimationNodeStateMachine`. + +.. rst-class:: classref-introduction-group Description ----------- Allows control of :ref:`AnimationTree` state machines created with :ref:`AnimationNodeStateMachine`. Retrieve with ``$AnimationTree.get("parameters/playback")``. -**Example:** -:: +.. tabs:: + + .. code-tab:: gdscript var state_machine = $AnimationTree.get("parameters/playback") state_machine.travel("some_state") + .. code-tab:: csharp + + var stateMachine = GetNode("AnimationTree").Get("parameters/playback").As(); + stateMachine.Travel("some_state"); + + + +.. rst-class:: classref-introduction-group + Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------+-------------------------+-----------------+ -| :ref:`bool` | resource_local_to_scene | **O:** ``true`` | -+-------------------------+-------------------------+-----------------+ +.. table:: + :widths: auto + + +-------------------------+-------------------------+---------------------------------------------------------------------------------------+ + | :ref:`bool` | resource_local_to_scene | ``true`` (overrides :ref:`Resource`) | + +-------------------------+-------------------------+---------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_current_node` **(** **)** const | -+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_travel_path` **(** **)** const | -+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_playing` **(** **)** const | -+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`start` **(** :ref:`StringName` node **)** | -+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop` **(** **)** | -+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`travel` **(** :ref:`StringName` to_node **)** | -+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_current_length`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_current_node`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_current_play_position`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_fading_from_length`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_fading_from_node`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_fading_from_play_position`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_fading_length`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_fading_position`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_travel_path`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`next`\ (\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`start`\ (\ node\: :ref:`StringName`, reset\: :ref:`bool` = true\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`travel`\ (\ to_node\: :ref:`StringName`, reset_on_teleport\: :ref:`bool` = true\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_AnimationNodeStateMachinePlayback_signal_state_finished: + +.. rst-class:: classref-signal + +**state_finished**\ (\ state\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when the ``state`` finishes playback. If ``state`` is a state machine set to grouped mode, its signals are passed through with its name prefixed. + +If there is a crossfade, this will be fired when the influence of the :ref:`get_fading_from_node()` animation is no longer present. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_signal_state_started: + +.. rst-class:: classref-signal + +**state_started**\ (\ state\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when the ``state`` starts playback. If ``state`` is a state machine set to grouped mode, its signals are passed through with its name prefixed. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- +.. _class_AnimationNodeStateMachinePlayback_method_get_current_length: + +.. rst-class:: classref-method + +:ref:`float` **get_current_length**\ (\ ) |const| :ref:`🔗` + +Returns the current state length. + +\ **Note:** It is possible that any :ref:`AnimationRootNode` can be nodes as well as animations. This means that there can be multiple animations within a single state. Which animation length has priority depends on the nodes connected inside it. Also, if a transition does not reset, the remaining length at that point will be returned. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeStateMachinePlayback_method_get_current_node: -- :ref:`StringName` **get_current_node** **(** **)** const +.. rst-class:: classref-method + +:ref:`StringName` **get_current_node**\ (\ ) |const| :ref:`🔗` Returns the currently playing animation state. +\ **Note:** When using a cross-fade, the current state changes to the next state immediately after the cross-fade begins. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_method_get_current_play_position: + +.. rst-class:: classref-method + +:ref:`float` **get_current_play_position**\ (\ ) |const| :ref:`🔗` + +Returns the playback position within the current animation state. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_method_get_fading_from_length: + +.. rst-class:: classref-method + +:ref:`float` **get_fading_from_length**\ (\ ) |const| :ref:`🔗` + +Returns the playback state length of the node from :ref:`get_fading_from_node()`. Returns ``0`` if no animation fade is occurring. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_method_get_fading_from_node: + +.. rst-class:: classref-method + +:ref:`StringName` **get_fading_from_node**\ (\ ) |const| :ref:`🔗` + +Returns the starting state of currently fading animation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_method_get_fading_from_play_position: + +.. rst-class:: classref-method + +:ref:`float` **get_fading_from_play_position**\ (\ ) |const| :ref:`🔗` + +Returns the playback position of the node from :ref:`get_fading_from_node()`. Returns ``0`` if no animation fade is occurring. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_method_get_fading_length: + +.. rst-class:: classref-method + +:ref:`float` **get_fading_length**\ (\ ) |const| :ref:`🔗` + +Returns the length of the current fade animation. Returns ``0`` if no animation fade is occurring. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_method_get_fading_position: + +.. rst-class:: classref-method + +:ref:`float` **get_fading_position**\ (\ ) |const| :ref:`🔗` + +Returns the playback position of the current fade animation. Returns ``0`` if no animation fade is occurring. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachinePlayback_method_get_travel_path: -- :ref:`PackedStringArray` **get_travel_path** **(** **)** const +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`StringName`\] **get_travel_path**\ (\ ) |const| :ref:`🔗` Returns the current travel path as computed internally by the A\* algorithm. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachinePlayback_method_is_playing: -- :ref:`bool` **is_playing** **(** **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` Returns ``true`` if an animation is playing. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_method_next: + +.. rst-class:: classref-method + +|void| **next**\ (\ ) :ref:`🔗` + +If there is a next path by travel or auto advance, immediately transitions from the current state to the next state. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachinePlayback_method_start: -- void **start** **(** :ref:`StringName` node **)** +.. rst-class:: classref-method + +|void| **start**\ (\ node\: :ref:`StringName`, reset\: :ref:`bool` = true\ ) :ref:`🔗` Starts playing the given animation. +If ``reset`` is ``true``, the animation is played from the beginning. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachinePlayback_method_stop: -- void **stop** **(** **)** +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`🔗` Stops the currently playing animation. +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachinePlayback_method_travel: -- void **travel** **(** :ref:`StringName` to_node **)** +.. rst-class:: classref-method + +|void| **travel**\ (\ to_node\: :ref:`StringName`, reset_on_teleport\: :ref:`bool` = true\ ) :ref:`🔗` Transitions from the current state to another one, following the shortest path. +If the path does not connect from the current state, the animation will play after the state teleports. + +If ``reset_on_teleport`` is ``true``, the animation is played from the beginning when the travel cause a teleportation. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodestatemachinetransition.rst b/classes/class_animationnodestatemachinetransition.rst index 706cbf8c259..b80c84889be 100644 --- a/classes/class_animationnodestatemachinetransition.rst +++ b/classes/class_animationnodestatemachinetransition.rst @@ -1,166 +1,332 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeStateMachineTransition.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeStateMachineTransition.xml. .. _class_AnimationNodeStateMachineTransition: AnimationNodeStateMachineTransition =================================== -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` +A transition within an :ref:`AnimationNodeStateMachine` connecting two :ref:`AnimationRootNode`\ s. +.. rst-class:: classref-introduction-group + +Description +----------- + +The path generated when using :ref:`AnimationNodeStateMachinePlayback.travel()` is limited to the nodes connected by **AnimationNodeStateMachineTransition**. + +You can set the timing and conditions of the transition in detail. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. rst-class:: classref-reftable-group Properties ---------- -+------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------+ -| :ref:`StringName` | :ref:`advance_condition` | ``@""`` | -+------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`auto_advance` | ``false`` | -+------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`disabled` | ``false`` | -+------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------+ -| :ref:`int` | :ref:`priority` | ``1`` | -+------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------+ -| :ref:`SwitchMode` | :ref:`switch_mode` | ``0`` | -+------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`xfade_time` | ``0.0`` | -+------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------+ +.. table:: + :widths: auto + + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`StringName` | :ref:`advance_condition` | ``&""`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`advance_expression` | ``""`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`AdvanceMode` | :ref:`advance_mode` | ``1`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`break_loop_at_end` | ``false`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`priority` | ``1`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`reset` | ``true`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`SwitchMode` | :ref:`switch_mode` | ``0`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`Curve` | :ref:`xfade_curve` | | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`xfade_time` | ``0.0`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_AnimationNodeStateMachineTransition_signal_advance_condition_changed: -- **advance_condition_changed** **(** **)** +.. rst-class:: classref-signal + +**advance_condition_changed**\ (\ ) :ref:`🔗` Emitted when :ref:`advance_condition` is changed. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Enumerations ------------ .. _enum_AnimationNodeStateMachineTransition_SwitchMode: +.. rst-class:: classref-enumeration + +enum **SwitchMode**: :ref:`🔗` + .. _class_AnimationNodeStateMachineTransition_constant_SWITCH_MODE_IMMEDIATE: +.. rst-class:: classref-enumeration-constant + +:ref:`SwitchMode` **SWITCH_MODE_IMMEDIATE** = ``0`` + +Switch to the next state immediately. The current state will end and blend into the beginning of the new one. + .. _class_AnimationNodeStateMachineTransition_constant_SWITCH_MODE_SYNC: +.. rst-class:: classref-enumeration-constant + +:ref:`SwitchMode` **SWITCH_MODE_SYNC** = ``1`` + +Switch to the next state immediately, but will seek the new state to the playback position of the old state. + .. _class_AnimationNodeStateMachineTransition_constant_SWITCH_MODE_AT_END: -enum **SwitchMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`SwitchMode` **SWITCH_MODE_AT_END** = ``2`` + +Wait for the current state playback to end, then switch to the beginning of the next state animation. -- **SWITCH_MODE_IMMEDIATE** = **0** --- Switch to the next state immediately. The current state will end and blend into the beginning of the new one. +.. rst-class:: classref-item-separator -- **SWITCH_MODE_SYNC** = **1** --- Switch to the next state immediately, but will seek the new state to the playback position of the old state. +---- + +.. _enum_AnimationNodeStateMachineTransition_AdvanceMode: + +.. rst-class:: classref-enumeration + +enum **AdvanceMode**: :ref:`🔗` + +.. _class_AnimationNodeStateMachineTransition_constant_ADVANCE_MODE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`AdvanceMode` **ADVANCE_MODE_DISABLED** = ``0`` + +Don't use this transition. + +.. _class_AnimationNodeStateMachineTransition_constant_ADVANCE_MODE_ENABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`AdvanceMode` **ADVANCE_MODE_ENABLED** = ``1`` + +Only use this transition during :ref:`AnimationNodeStateMachinePlayback.travel()`. -- **SWITCH_MODE_AT_END** = **2** --- Wait for the current state playback to end, then switch to the beginning of the next state animation. +.. _class_AnimationNodeStateMachineTransition_constant_ADVANCE_MODE_AUTO: + +.. rst-class:: classref-enumeration-constant + +:ref:`AdvanceMode` **ADVANCE_MODE_AUTO** = ``2`` + +Automatically use this transition if the :ref:`advance_condition` and :ref:`advance_expression` checks are ``true`` (if assigned). + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AnimationNodeStateMachineTransition_property_advance_condition: -- :ref:`StringName` **advance_condition** +.. rst-class:: classref-property + +:ref:`StringName` **advance_condition** = ``&""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_advance_condition**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_advance_condition**\ (\ ) + +Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the :ref:`AnimationTree` that can be controlled from code (see `Using AnimationTree <../tutorials/animation/animation_tree.html#controlling-from-code>`__). For example, if :ref:`AnimationTree.tree_root` is an :ref:`AnimationNodeStateMachine` and :ref:`advance_condition` is set to ``"idle"``: -+-----------+------------------------------+ -| *Default* | ``@""`` | -+-----------+------------------------------+ -| *Setter* | set_advance_condition(value) | -+-----------+------------------------------+ -| *Getter* | get_advance_condition() | -+-----------+------------------------------+ -Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the :ref:`AnimationTree` that can be controlled from code (see `https://docs.godotengine.org/en/latest/tutorials/animation/animation_tree.html#controlling-from-code `_). For example, if :ref:`AnimationTree.tree_root` is an :ref:`AnimationNodeStateMachine` and :ref:`advance_condition` is set to ``"idle"``: +.. tabs:: -:: + .. code-tab:: gdscript - $animation_tree["parameters/conditions/idle"] = is_on_floor and (linear_velocity.x == 0) + $animation_tree.set("parameters/conditions/idle", is_on_floor and (linear_velocity.x == 0)) + + .. code-tab:: csharp + + GetNode("animation_tree").Set("parameters/conditions/idle", IsOnFloor && (LinearVelocity.X == 0)); + + + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNodeStateMachineTransition_property_auto_advance: +.. _class_AnimationNodeStateMachineTransition_property_advance_expression: + +.. rst-class:: classref-property -- :ref:`bool` **auto_advance** +:ref:`String` **advance_expression** = ``""`` :ref:`🔗` -+-----------+-------------------------+ -| *Default* | ``false`` | -+-----------+-------------------------+ -| *Setter* | set_auto_advance(value) | -+-----------+-------------------------+ -| *Getter* | has_auto_advance() | -+-----------+-------------------------+ +.. rst-class:: classref-property-setget -Turn on the transition automatically when this state is reached. This works best with :ref:`SWITCH_MODE_AT_END`. +- |void| **set_advance_expression**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_advance_expression**\ (\ ) + +Use an expression as a condition for state machine transitions. It is possible to create complex animation advance conditions for switching between states and gives much greater flexibility for creating complex state machines by directly interfacing with the script code. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNodeStateMachineTransition_property_disabled: +.. _class_AnimationNodeStateMachineTransition_property_advance_mode: + +.. rst-class:: classref-property -- :ref:`bool` **disabled** +:ref:`AdvanceMode` **advance_mode** = ``1`` :ref:`🔗` -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_disabled(value) | -+-----------+---------------------+ -| *Getter* | is_disabled() | -+-----------+---------------------+ +.. rst-class:: classref-property-setget -Don't use this transition during :ref:`AnimationNodeStateMachinePlayback.travel` or :ref:`auto_advance`. +- |void| **set_advance_mode**\ (\ value\: :ref:`AdvanceMode`\ ) +- :ref:`AdvanceMode` **get_advance_mode**\ (\ ) + +Determines whether the transition should be disabled, enabled when using :ref:`AnimationNodeStateMachinePlayback.travel()`, or traversed automatically if the :ref:`advance_condition` and :ref:`advance_expression` checks are ``true`` (if assigned). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachineTransition_property_break_loop_at_end: + +.. rst-class:: classref-property + +:ref:`bool` **break_loop_at_end** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_break_loop_at_end**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_loop_broken_at_end**\ (\ ) + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachineTransition_property_priority: -- :ref:`int` **priority** +.. rst-class:: classref-property + +:ref:`int` **priority** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_priority**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_priority**\ (\ ) -+-----------+---------------------+ -| *Default* | ``1`` | -+-----------+---------------------+ -| *Setter* | set_priority(value) | -+-----------+---------------------+ -| *Getter* | get_priority() | -+-----------+---------------------+ +Lower priority transitions are preferred when travelling through the tree via :ref:`AnimationNodeStateMachinePlayback.travel()` or :ref:`advance_mode` is set to :ref:`ADVANCE_MODE_AUTO`. -Lower priority transitions are preferred when travelling through the tree via :ref:`AnimationNodeStateMachinePlayback.travel` or :ref:`auto_advance`. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachineTransition_property_reset: + +.. rst-class:: classref-property + +:ref:`bool` **reset** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_reset**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_reset**\ (\ ) + +If ``true``, the destination animation is played back from the beginning when switched. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeStateMachineTransition_property_switch_mode: -- :ref:`SwitchMode` **switch_mode** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``0`` | -+-----------+------------------------+ -| *Setter* | set_switch_mode(value) | -+-----------+------------------------+ -| *Getter* | get_switch_mode() | -+-----------+------------------------+ +:ref:`SwitchMode` **switch_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_switch_mode**\ (\ value\: :ref:`SwitchMode`\ ) +- :ref:`SwitchMode` **get_switch_mode**\ (\ ) The transition type. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachineTransition_property_xfade_curve: + +.. rst-class:: classref-property + +:ref:`Curve` **xfade_curve** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_xfade_curve**\ (\ value\: :ref:`Curve`\ ) +- :ref:`Curve` **get_xfade_curve**\ (\ ) + +Ease curve for better control over cross-fade between this state and the next. Should be a unit :ref:`Curve`. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationNodeStateMachineTransition_property_xfade_time: -- :ref:`float` **xfade_time** +.. rst-class:: classref-property + +:ref:`float` **xfade_time** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------+ -| *Default* | ``0.0`` | -+-----------+-----------------------+ -| *Setter* | set_xfade_time(value) | -+-----------+-----------------------+ -| *Getter* | get_xfade_time() | -+-----------+-----------------------+ +- |void| **set_xfade_time**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_xfade_time**\ (\ ) The time to cross-fade between this state and the next. +\ **Note:** :ref:`AnimationNodeStateMachine` transitions the current state immediately after the start of the fading. The precise remaining time can only be inferred from the main animation. When :ref:`AnimationNodeOutput` is considered as the most upstream, so the :ref:`xfade_time` is not scaled depending on the downstream delta. See also :ref:`AnimationNodeOneShot.fadeout_time`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodesub2.rst b/classes/class_animationnodesub2.rst new file mode 100644 index 00000000000..e627557c414 --- /dev/null +++ b/classes/class_animationnodesub2.rst @@ -0,0 +1,45 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeSub2.xml. + +.. _class_AnimationNodeSub2: + +AnimationNodeSub2 +================= + +**Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Blends two animations subtractively inside of an :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations subtractively based on the amount value. + +This animation node is usually used for pre-calculation to cancel out any extra poses from the animation for the "add" animation source in :ref:`AnimationNodeAdd2` or :ref:`AnimationNodeAdd3`. + +In general, the blend value should be in the ``[0.0, 1.0]`` range, but values outside of this range can be used for amplified or inverted animations. + +\ **Note:** This calculation is different from using a negative value in :ref:`AnimationNodeAdd2`, since the transformation matrices do not satisfy the commutative law. **AnimationNodeSub2** multiplies the transformation matrix of the inverted animation from the left side, while negative :ref:`AnimationNodeAdd2` multiplies it from the right side. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`AnimationTree <../tutorials/animation/animation_tree>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodesync.rst b/classes/class_animationnodesync.rst new file mode 100644 index 00000000000..5de060b0fc3 --- /dev/null +++ b/classes/class_animationnodesync.rst @@ -0,0 +1,77 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeSync.xml. + +.. _class_AnimationNodeSync: + +AnimationNodeSync +================= + +**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +**Inherited By:** :ref:`AnimationNodeAdd2`, :ref:`AnimationNodeAdd3`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, :ref:`AnimationNodeSub2`, :ref:`AnimationNodeTransition` + +Base class for :ref:`AnimationNode`\ s with multiple input ports that must be synchronized. + +.. rst-class:: classref-introduction-group + +Description +----------- + +An animation node used to combine, mix, or blend two or more animations together while keeping them synchronized within an :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+----------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`sync` | ``false`` | + +-------------------------+----------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimationNodeSync_property_sync: + +.. rst-class:: classref-property + +:ref:`bool` **sync** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_sync**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_using_sync**\ (\ ) + +If ``false``, the blended animations' frame are stopped when the blend value is ``0``. + +If ``true``, forcing the blended animations to advance frame. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodetimescale.rst b/classes/class_animationnodetimescale.rst index a169254cb9d..6c865f463af 100644 --- a/classes/class_animationnodetimescale.rst +++ b/classes/class_animationnodetimescale.rst @@ -1,25 +1,41 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeTimeScale.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeTimeScale.xml. .. _class_AnimationNodeTimeScale: AnimationNodeTimeScale ====================== -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A time-scaling animation node to be used with :ref:`AnimationTree`. +A time-scaling animation node used in :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group Description ----------- -Allows scaling the speed of the animation (or reversing it) in any children nodes. Setting it to 0 will pause the animation. +Allows to scale the speed of the animation (or reverse it) in any child :ref:`AnimationNode`\ s. Setting it to ``0.0`` will pause the animation. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +- `3D Platformer Demo `__ +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodetimeseek.rst b/classes/class_animationnodetimeseek.rst index 94ed1abac41..0d7c2fe2d3a 100644 --- a/classes/class_animationnodetimeseek.rst +++ b/classes/class_animationnodetimeseek.rst @@ -1,25 +1,100 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeTimeSeek.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeTimeSeek.xml. .. _class_AnimationNodeTimeSeek: AnimationNodeTimeSeek ===================== -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A time-seeking animation node to be used with :ref:`AnimationTree`. +A time-seeking animation node used in :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group Description ----------- -This node can be used to cause a seek command to happen to any sub-children of the graph. After setting the time, this value returns to -1. +This animation node can be used to cause a seek command to happen to any sub-children of the animation graph. Use to play an :ref:`Animation` from the start or a certain playback position inside the :ref:`AnimationNodeBlendTree`. + +After setting the time and changing the animation playback, the time seek node automatically goes into sleep mode on the next process frame by setting its ``seek_request`` value to ``-1.0``. + + +.. tabs:: + + .. code-tab:: gdscript + + # Play child animation from the start. + animation_tree.set("parameters/TimeSeek/seek_request", 0.0) + # Alternative syntax (same result as above). + animation_tree["parameters/TimeSeek/seek_request"] = 0.0 + + # Play child animation from 12 second timestamp. + animation_tree.set("parameters/TimeSeek/seek_request", 12.0) + # Alternative syntax (same result as above). + animation_tree["parameters/TimeSeek/seek_request"] = 12.0 + + .. code-tab:: csharp + + // Play child animation from the start. + animationTree.Set("parameters/TimeSeek/seek_request", 0.0); + + // Play child animation from 12 second timestamp. + animationTree.Set("parameters/TimeSeek/seek_request", 12.0); + + + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+------------------------------------------------------------------------------+----------+ + | :ref:`bool` | :ref:`explicit_elapse` | ``true`` | + +-------------------------+------------------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimationNodeTimeSeek_property_explicit_elapse: + +.. rst-class:: classref-property + +:ref:`bool` **explicit_elapse** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_explicit_elapse**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_explicit_elapse**\ (\ ) + +If ``true``, some processes are executed to handle keys between seeks, such as calculating root motion and finding the nearest discrete key. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodetransition.rst b/classes/class_animationnodetransition.rst index 4878bc86c20..719de4008be 100644 --- a/classes/class_animationnodetransition.rst +++ b/classes/class_animationnodetransition.rst @@ -1,105 +1,272 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationNodeTransition.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeTransition.xml. .. _class_AnimationNodeTransition: AnimationNodeTransition ======================= -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A generic animation transition node for :ref:`AnimationTree`. +A transition within an :ref:`AnimationTree` connecting two :ref:`AnimationNode`\ s. + +.. rst-class:: classref-introduction-group Description ----------- Simple state machine for cases which don't require a more advanced :ref:`AnimationNodeStateMachine`. Animations can be connected to the inputs and transition times can be specified. +After setting the request and changing the animation playback, the transition node automatically clears the request on the next process frame by setting its ``transition_request`` value to empty. + +\ **Note:** When using a cross-fade, ``current_state`` and ``current_index`` change to the next state immediately after the cross-fade begins. + + +.. tabs:: + + .. code-tab:: gdscript + + # Play child animation connected to "state_2" port. + animation_tree.set("parameters/Transition/transition_request", "state_2") + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/transition_request"] = "state_2" + + # Get current state name (read-only). + animation_tree.get("parameters/Transition/current_state") + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/current_state"] + + # Get current state index (read-only). + animation_tree.get("parameters/Transition/current_index") + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/current_index"] + + .. code-tab:: csharp + + // Play child animation connected to "state_2" port. + animationTree.Set("parameters/Transition/transition_request", "state_2"); + + // Get current state name (read-only). + animationTree.Get("parameters/Transition/current_state"); + + // Get current state index (read-only). + animationTree.Get("parameters/Transition/current_index"); + + + +.. rst-class:: classref-introduction-group + Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +- `3D Platformer Demo `__ + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+------------------------------------------------------------------------+---------+ -| :ref:`int` | :ref:`input_count` | ``0`` | -+---------------------------+------------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`xfade_time` | ``0.0`` | -+---------------------------+------------------------------------------------------------------------+---------+ +.. table:: + :widths: auto + + +---------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`allow_transition_to_self` | ``false`` | + +---------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`input_count` | ``0`` | + +---------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`Curve` | :ref:`xfade_curve` | | + +---------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`xfade_time` | ``0.0`` | + +---------------------------+--------------------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_input_caption` **(** :ref:`int` input **)** const | -+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_input_set_as_auto_advance` **(** :ref:`int` input **)** const | -+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_input_as_auto_advance` **(** :ref:`int` input, :ref:`bool` enable **)** | -+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_input_caption` **(** :ref:`int` input, :ref:`String` caption **)** | -+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_input_loop_broken_at_end`\ (\ input\: :ref:`int`\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_input_reset`\ (\ input\: :ref:`int`\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_input_set_as_auto_advance`\ (\ input\: :ref:`int`\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_input_as_auto_advance`\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_input_break_loop_at_end`\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_input_reset`\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- +.. _class_AnimationNodeTransition_property_allow_transition_to_self: + +.. rst-class:: classref-property + +:ref:`bool` **allow_transition_to_self** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_allow_transition_to_self**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_allow_transition_to_self**\ (\ ) + +If ``true``, allows transition to the self state. When the reset option is enabled in input, the animation is restarted. If ``false``, nothing happens on the transition to the self state. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeTransition_property_input_count: -- :ref:`int` **input_count** +.. rst-class:: classref-property + +:ref:`int` **input_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------------+ -| *Default* | ``0`` | -+-----------+---------------------------+ -| *Setter* | set_enabled_inputs(value) | -+-----------+---------------------------+ -| *Getter* | get_enabled_inputs() | -+-----------+---------------------------+ +- |void| **set_input_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_input_count**\ (\ ) -The number of available input ports for this node. +The number of enabled input ports for this animation node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeTransition_property_xfade_curve: + +.. rst-class:: classref-property + +:ref:`Curve` **xfade_curve** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_xfade_curve**\ (\ value\: :ref:`Curve`\ ) +- :ref:`Curve` **get_xfade_curve**\ (\ ) + +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeTransition_property_xfade_time: -- :ref:`float` **xfade_time** +.. rst-class:: classref-property + +:ref:`float` **xfade_time** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------------+ -| *Default* | ``0.0`` | -+-----------+----------------------------+ -| *Setter* | set_cross_fade_time(value) | -+-----------+----------------------------+ -| *Getter* | get_cross_fade_time() | -+-----------+----------------------------+ +- |void| **set_xfade_time**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_xfade_time**\ (\ ) Cross-fading time (in seconds) between each animation connected to the inputs. +\ **Note:** **AnimationNodeTransition** transitions the current state immediately after the start of the fading. The precise remaining time can only be inferred from the main animation. When :ref:`AnimationNodeOutput` is considered as the most upstream, so the :ref:`xfade_time` is not scaled depending on the downstream delta. See also :ref:`AnimationNodeOneShot.fadeout_time`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- -.. _class_AnimationNodeTransition_method_get_input_caption: +.. _class_AnimationNodeTransition_method_is_input_loop_broken_at_end: + +.. rst-class:: classref-method + +:ref:`bool` **is_input_loop_broken_at_end**\ (\ input\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether the animation breaks the loop at the end of the loop cycle for transition. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeTransition_method_is_input_reset: + +.. rst-class:: classref-method + +:ref:`bool` **is_input_reset**\ (\ input\: :ref:`int`\ ) |const| :ref:`🔗` -- :ref:`String` **get_input_caption** **(** :ref:`int` input **)** const +Returns whether the animation restarts when the animation transitions from the other animation. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeTransition_method_is_input_set_as_auto_advance: -- :ref:`bool` **is_input_set_as_auto_advance** **(** :ref:`int` input **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_input_set_as_auto_advance**\ (\ input\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if auto-advance is enabled for the given ``input`` index. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationNodeTransition_method_set_input_as_auto_advance: -- void **set_input_as_auto_advance** **(** :ref:`int` input, :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_input_as_auto_advance**\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` + +Enables or disables auto-advance for the given ``input`` index. If enabled, state changes to the next input after playing the animation once. If enabled for the last input state, it loops to the first. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationNodeTransition_method_set_input_caption: +.. _class_AnimationNodeTransition_method_set_input_break_loop_at_end: + +.. rst-class:: classref-method + +|void| **set_input_break_loop_at_end**\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeTransition_method_set_input_reset: + +.. rst-class:: classref-method + +|void| **set_input_reset**\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` -- void **set_input_caption** **(** :ref:`int` input, :ref:`String` caption **)** +If ``true``, the destination animation is restarted when the animation transitions. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationplayer.rst b/classes/class_animationplayer.rst index a7bfbc0b871..e2f5e67a851 100644 --- a/classes/class_animationplayer.rst +++ b/classes/class_animationplayer.rst @@ -1,523 +1,933 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationPlayer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationPlayer.xml. .. _class_AnimationPlayer: AnimationPlayer =============== -**Inherits:** :ref:`Node` **<** :ref:`Object` +**Inherits:** :ref:`AnimationMixer` **<** :ref:`Node` **<** :ref:`Object` -Container and player of :ref:`Animation` resources. +A node used for animation playback. + +.. rst-class:: classref-introduction-group Description ----------- -An animation player is used for general-purpose playback of :ref:`Animation` resources. It contains a dictionary of animations (referenced by name) and custom blend times between their transitions. Additionally, animations can be played and blended in different channels. +An animation player is used for general-purpose playback of animations. It contains a dictionary of :ref:`AnimationLibrary` resources and custom blend times between animation transitions. + +Some methods and properties use a single key to reference an animation directly. These keys are formatted as the key for the library, followed by a forward slash, then the key for the animation within the library, for example ``"movement/run"``. If the library's key is an empty string (known as the default library), the forward slash is omitted, being the same key used by the library. -``AnimationPlayer`` is more suited than :ref:`Tween` for animations where you know the final values in advance. For example, fading a screen in and out is more easily done with an ``AnimationPlayer`` node thanks to the animation tools provided by the editor. That particular example can also be implemented with a :ref:`Tween` node, but it requires doing everything by code. +\ **AnimationPlayer** is better-suited than :ref:`Tween` for more complex animations, for example ones with non-trivial timings. It can also be used over :ref:`Tween` if the animation track editor is more convenient than doing it in code. -Updating the target properties of animations occurs at process time. +Updating the target properties of animations occurs at the process frame. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/index` +- :doc:`2D Sprite animation <../tutorials/2d/2d_sprite_animation>` + +- :doc:`Animation documentation index <../tutorials/animation/index>` + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`String` | :ref:`assigned_animation` | | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`String` | :ref:`autoplay` | ``""`` | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`String` | :ref:`current_animation` | ``""`` | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`float` | :ref:`current_animation_length` | | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`float` | :ref:`current_animation_position` | | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`AnimationMethodCallMode` | :ref:`method_call_mode` | ``0`` | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`bool` | :ref:`playback_active` | | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`float` | :ref:`playback_default_blend_time` | ``0.0`` | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`AnimationProcessMode` | :ref:`playback_process_mode` | ``1`` | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`float` | :ref:`playback_speed` | ``1.0`` | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ -| :ref:`NodePath` | :ref:`root_node` | ``NodePath("..")`` | -+------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+--------------------+ +.. table:: + :widths: auto + + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`StringName` | :ref:`assigned_animation` | | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`StringName` | :ref:`autoplay` | ``&""`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`StringName` | :ref:`current_animation` | ``&""`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`current_animation_length` | | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`current_animation_position` | | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`movie_quit_on_finish` | ``false`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`playback_auto_capture` | ``true`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`playback_auto_capture_duration` | ``-1.0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`EaseType` | :ref:`playback_auto_capture_ease_type` | ``0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`TransitionType` | :ref:`playback_auto_capture_transition_type` | ``0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`playback_default_blend_time` | ``0.0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`speed_scale` | ``1.0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`add_animation` **(** :ref:`StringName` name, :ref:`Animation` animation **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`advance` **(** :ref:`float` delta **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`animation_get_next` **(** :ref:`StringName` anim_from **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`animation_set_next` **(** :ref:`StringName` anim_from, :ref:`StringName` anim_to **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_caches` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_queue` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`find_animation` **(** :ref:`Animation` animation **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Animation` | :ref:`get_animation` **(** :ref:`StringName` name **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_animation_list` **(** **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_blend_time` **(** :ref:`StringName` anim_from, :ref:`StringName` anim_to **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_playing_speed` **(** **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_queue` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_animation` **(** :ref:`StringName` name **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_playing` **(** **)** const | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`play` **(** :ref:`StringName` name="", :ref:`float` custom_blend=-1, :ref:`float` custom_speed=1.0, :ref:`bool` from_end=false **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`play_backwards` **(** :ref:`StringName` name="", :ref:`float` custom_blend=-1 **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`queue` **(** :ref:`StringName` name **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_animation` **(** :ref:`StringName` name **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`rename_animation` **(** :ref:`StringName` name, :ref:`StringName` newname **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`seek` **(** :ref:`float` seconds, :ref:`bool` update=false **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_blend_time` **(** :ref:`StringName` anim_from, :ref:`StringName` anim_to, :ref:`float` sec **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop` **(** :ref:`bool` reset=true **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`animation_get_next`\ (\ animation_from\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`animation_set_next`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_queue`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationMethodCallMode` | :ref:`get_method_call_mode`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playing_speed`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationProcessCallback` | :ref:`get_process_callback`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_queue`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`get_root`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_section_end_time`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_section_start_time`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_section`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_animation_active`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`pause`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_backwards`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section`\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_backwards`\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_with_markers`\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_with_markers_backwards`\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_with_capture`\ (\ name\: :ref:`StringName` = &"", duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`queue`\ (\ name\: :ref:`StringName`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`reset_section`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seek`\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_method_call_mode`\ (\ mode\: :ref:`AnimationMethodCallMode`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_process_callback`\ (\ mode\: :ref:`AnimationProcessCallback`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_root`\ (\ path\: :ref:`NodePath`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_section`\ (\ start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_section_with_markers`\ (\ start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &""\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ keep_state\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_AnimationPlayer_signal_animation_changed: -- **animation_changed** **(** :ref:`StringName` old_name, :ref:`StringName` new_name **)** +.. rst-class:: classref-signal -If the currently being played animation changes, this signal will notify of such change. - ----- +**animation_changed**\ (\ old_name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` -.. _class_AnimationPlayer_signal_animation_finished: +Emitted when a queued animation plays after the previous animation finished. See also :ref:`queue()`. -- **animation_finished** **(** :ref:`StringName` anim_name **)** +\ **Note:** The signal is not emitted when the animation is changed via :ref:`play()` or by an :ref:`AnimationTree`. -Notifies when an animation finished playing. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_signal_animation_started: +.. _class_AnimationPlayer_signal_current_animation_changed: -- **animation_started** **(** :ref:`StringName` anim_name **)** +.. rst-class:: classref-signal -Notifies when an animation starts playing. +**current_animation_changed**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` ----- +Emitted when :ref:`current_animation` changes. -.. _class_AnimationPlayer_signal_caches_cleared: +.. rst-class:: classref-section-separator -- **caches_cleared** **(** **)** +---- -Notifies when the caches have been cleared, either automatically, or manually via :ref:`clear_caches`. +.. rst-class:: classref-descriptions-group Enumerations ------------ -.. _enum_AnimationPlayer_AnimationProcessMode: +.. _enum_AnimationPlayer_AnimationProcessCallback: + +.. rst-class:: classref-enumeration + +enum **AnimationProcessCallback**: :ref:`🔗` .. _class_AnimationPlayer_constant_ANIMATION_PROCESS_PHYSICS: +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationProcessCallback` **ANIMATION_PROCESS_PHYSICS** = ``0`` + +**Deprecated:** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS`. + + + .. _class_AnimationPlayer_constant_ANIMATION_PROCESS_IDLE: +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationProcessCallback` **ANIMATION_PROCESS_IDLE** = ``1`` + +**Deprecated:** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE`. + + + .. _class_AnimationPlayer_constant_ANIMATION_PROCESS_MANUAL: -enum **AnimationProcessMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationProcessCallback` **ANIMATION_PROCESS_MANUAL** = ``2`` + +**Deprecated:** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL`. -- **ANIMATION_PROCESS_PHYSICS** = **0** --- Process animation during the physics process. This is especially useful when animating physics bodies. -- **ANIMATION_PROCESS_IDLE** = **1** --- Process animation during the idle process. -- **ANIMATION_PROCESS_MANUAL** = **2** --- Do not process animation. Use :ref:`advance` to process the animation manually. +.. rst-class:: classref-item-separator ---- .. _enum_AnimationPlayer_AnimationMethodCallMode: +.. rst-class:: classref-enumeration + +enum **AnimationMethodCallMode**: :ref:`🔗` + .. _class_AnimationPlayer_constant_ANIMATION_METHOD_CALL_DEFERRED: +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationMethodCallMode` **ANIMATION_METHOD_CALL_DEFERRED** = ``0`` + +**Deprecated:** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED`. + + + .. _class_AnimationPlayer_constant_ANIMATION_METHOD_CALL_IMMEDIATE: -enum **AnimationMethodCallMode**: +.. rst-class:: classref-enumeration-constant -- **ANIMATION_METHOD_CALL_DEFERRED** = **0** --- Batch method calls during the animation process, then do the calls after events are processed. This avoids bugs involving deleting nodes or modifying the AnimationPlayer while playing. +:ref:`AnimationMethodCallMode` **ANIMATION_METHOD_CALL_IMMEDIATE** = ``1`` -- **ANIMATION_METHOD_CALL_IMMEDIATE** = **1** --- Make method calls immediately when reached in the animation. +**Deprecated:** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE`. + + + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AnimationPlayer_property_assigned_animation: -- :ref:`String` **assigned_animation** +.. rst-class:: classref-property + +:ref:`StringName` **assigned_animation** :ref:`🔗` + +.. rst-class:: classref-property-setget -+----------+-------------------------------+ -| *Setter* | set_assigned_animation(value) | -+----------+-------------------------------+ -| *Getter* | get_assigned_animation() | -+----------+-------------------------------+ +- |void| **set_assigned_animation**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_assigned_animation**\ (\ ) -If playing, the current animation; otherwise, the animation last played. When set, would change the animation, but would not play it unless currently playing. See also :ref:`current_animation`. +If playing, the current animation's key, otherwise, the animation last played. When set, this changes the animation, but will not play it unless already playing. See also :ref:`current_animation`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_autoplay: -- :ref:`String` **autoplay** +.. rst-class:: classref-property + +:ref:`StringName` **autoplay** = ``&""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_autoplay**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_autoplay**\ (\ ) -+-----------+---------------------+ -| *Default* | ``""`` | -+-----------+---------------------+ -| *Setter* | set_autoplay(value) | -+-----------+---------------------+ -| *Getter* | get_autoplay() | -+-----------+---------------------+ +The key of the animation to play when the scene loads. -The name of the animation to play when the scene loads. +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_current_animation: -- :ref:`String` **current_animation** +.. rst-class:: classref-property + +:ref:`StringName` **current_animation** = ``&""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_current_animation**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_current_animation**\ (\ ) + +The key of the currently playing animation. If no animation is playing, the property's value is an empty string. Changing this value does not restart the animation. See :ref:`play()` for more information on playing animations. -+-----------+------------------------------+ -| *Default* | ``""`` | -+-----------+------------------------------+ -| *Setter* | set_current_animation(value) | -+-----------+------------------------------+ -| *Getter* | get_current_animation() | -+-----------+------------------------------+ +\ **Note:** While this property appears in the Inspector, it's not meant to be edited, and it's not saved in the scene. This property is mainly used to get the currently playing animation, and internally for animation playback tracks. For more information, see :ref:`Animation`. -The name of the current animation, "" if not playing anything. When being set, does not restart the animation. See also :ref:`play`. +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_current_animation_length: -- :ref:`float` **current_animation_length** +.. rst-class:: classref-property -+----------+--------------------------------+ -| *Getter* | get_current_animation_length() | -+----------+--------------------------------+ +:ref:`float` **current_animation_length** :ref:`🔗` -The length (in seconds) of the currently being played animation. +.. rst-class:: classref-property-setget + +- :ref:`float` **get_current_animation_length**\ (\ ) + +The length (in seconds) of the currently playing animation. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_current_animation_position: -- :ref:`float` **current_animation_position** +.. rst-class:: classref-property + +:ref:`float` **current_animation_position** :ref:`🔗` -+----------+----------------------------------+ -| *Getter* | get_current_animation_position() | -+----------+----------------------------------+ +.. rst-class:: classref-property-setget + +- :ref:`float` **get_current_animation_position**\ (\ ) The position (in seconds) of the currently playing animation. +.. rst-class:: classref-item-separator + ---- -.. _class_AnimationPlayer_property_method_call_mode: +.. _class_AnimationPlayer_property_movie_quit_on_finish: + +.. rst-class:: classref-property + +:ref:`bool` **movie_quit_on_finish** = ``false`` :ref:`🔗` -- :ref:`AnimationMethodCallMode` **method_call_mode** +.. rst-class:: classref-property-setget -+-----------+-----------------------------+ -| *Default* | ``0`` | -+-----------+-----------------------------+ -| *Setter* | set_method_call_mode(value) | -+-----------+-----------------------------+ -| *Getter* | get_method_call_mode() | -+-----------+-----------------------------+ +- |void| **set_movie_quit_on_finish_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_movie_quit_on_finish_enabled**\ (\ ) -The call mode to use for Call Method tracks. +If ``true`` and the engine is running in Movie Maker mode (see :ref:`MovieWriter`), exits the engine with :ref:`SceneTree.quit()` as soon as an animation is done playing in this **AnimationPlayer**. A message is printed when the engine quits for this reason. + +\ **Note:** This obeys the same logic as the :ref:`AnimationMixer.animation_finished` signal, so it will not quit the engine if the animation is set to be looping. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_property_playback_active: +.. _class_AnimationPlayer_property_playback_auto_capture: + +.. rst-class:: classref-property + +:ref:`bool` **playback_auto_capture** = ``true`` :ref:`🔗` -- :ref:`bool` **playback_active** +.. rst-class:: classref-property-setget -+----------+-------------------+ -| *Setter* | set_active(value) | -+----------+-------------------+ -| *Getter* | is_active() | -+----------+-------------------+ +- |void| **set_auto_capture**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_auto_capture**\ (\ ) -If ``true``, updates animations in response to process-related notifications. +If ``true``, performs :ref:`AnimationMixer.capture()` before playback automatically. This means just :ref:`play_with_capture()` is executed with default arguments instead of :ref:`play()`. + +\ **Note:** Capture interpolation is only performed if the animation contains a capture track. See also :ref:`Animation.UPDATE_CAPTURE`. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_property_playback_default_blend_time: +.. _class_AnimationPlayer_property_playback_auto_capture_duration: -- :ref:`float` **playback_default_blend_time** +.. rst-class:: classref-property -+-----------+-------------------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------------------+ -| *Setter* | set_default_blend_time(value) | -+-----------+-------------------------------+ -| *Getter* | get_default_blend_time() | -+-----------+-------------------------------+ +:ref:`float` **playback_auto_capture_duration** = ``-1.0`` :ref:`🔗` -The default time in which to blend animations. Ranges from 0 to 4096 with 0.01 precision. +.. rst-class:: classref-property-setget + +- |void| **set_auto_capture_duration**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_auto_capture_duration**\ (\ ) + +See also :ref:`play_with_capture()` and :ref:`AnimationMixer.capture()`. + +If :ref:`playback_auto_capture_duration` is negative value, the duration is set to the interval between the current position and the first key. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_property_playback_process_mode: +.. _class_AnimationPlayer_property_playback_auto_capture_ease_type: + +.. rst-class:: classref-property + +:ref:`EaseType` **playback_auto_capture_ease_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`AnimationProcessMode` **playback_process_mode** +- |void| **set_auto_capture_ease_type**\ (\ value\: :ref:`EaseType`\ ) +- :ref:`EaseType` **get_auto_capture_ease_type**\ (\ ) -+-----------+-----------------------------------+ -| *Default* | ``1`` | -+-----------+-----------------------------------+ -| *Setter* | set_animation_process_mode(value) | -+-----------+-----------------------------------+ -| *Getter* | get_animation_process_mode() | -+-----------+-----------------------------------+ +The ease type of the capture interpolation. See also :ref:`EaseType`. -The process notification in which to update animations. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_property_playback_speed: +.. _class_AnimationPlayer_property_playback_auto_capture_transition_type: -- :ref:`float` **playback_speed** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_speed_scale(value) | -+-----------+------------------------+ -| *Getter* | get_speed_scale() | -+-----------+------------------------+ +:ref:`TransitionType` **playback_auto_capture_transition_type** = ``0`` :ref:`🔗` -The speed scaling ratio. For instance, if this value is 1, then the animation plays at normal speed. If it's 0.5, then it plays at half speed. If it's 2, then it plays at double speed. +.. rst-class:: classref-property-setget + +- |void| **set_auto_capture_transition_type**\ (\ value\: :ref:`TransitionType`\ ) +- :ref:`TransitionType` **get_auto_capture_transition_type**\ (\ ) + +The transition type of the capture interpolation. See also :ref:`TransitionType`. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_property_root_node: +.. _class_AnimationPlayer_property_playback_default_blend_time: + +.. rst-class:: classref-property + +:ref:`float` **playback_default_blend_time** = ``0.0`` :ref:`🔗` -- :ref:`NodePath` **root_node** +.. rst-class:: classref-property-setget -+-----------+--------------------+ -| *Default* | ``NodePath("..")`` | -+-----------+--------------------+ -| *Setter* | set_root(value) | -+-----------+--------------------+ -| *Getter* | get_root() | -+-----------+--------------------+ +- |void| **set_default_blend_time**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_default_blend_time**\ (\ ) + +The default time in which to blend animations. Ranges from 0 to 4096 with 0.01 precision. -The node from which node path references will travel. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_property_speed_scale: + +.. rst-class:: classref-property + +:ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_speed_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_speed_scale**\ (\ ) + +The speed scaling ratio. For example, if this value is ``1``, then the animation plays at normal speed. If it's ``0.5``, then it plays at half speed. If it's ``2``, then it plays at double speed. + +If set to a negative value, the animation is played in reverse. If set to ``0``, the animation will not advance. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_AnimationPlayer_method_add_animation: +.. _class_AnimationPlayer_method_animation_get_next: + +.. rst-class:: classref-method -- :ref:`Error` **add_animation** **(** :ref:`StringName` name, :ref:`Animation` animation **)** +:ref:`StringName` **animation_get_next**\ (\ animation_from\: :ref:`StringName`\ ) |const| :ref:`🔗` -Adds ``animation`` to the player accessible with the key ``name``. +Returns the key of the animation which is queued to play after the ``animation_from`` animation. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_advance: +.. _class_AnimationPlayer_method_animation_set_next: + +.. rst-class:: classref-method + +|void| **animation_set_next**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) :ref:`🔗` -- void **advance** **(** :ref:`float` delta **)** +Triggers the ``animation_to`` animation when the ``animation_from`` animation completes. -Shifts position in the animation timeline and immediately updates the animation. ``delta`` is the time in seconds to shift. Events between the current frame and ``delta`` are handled. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_animation_get_next: +.. _class_AnimationPlayer_method_clear_queue: -- :ref:`StringName` **animation_get_next** **(** :ref:`StringName` anim_from **)** const +.. rst-class:: classref-method -Returns the name of the next animation in the queue. +|void| **clear_queue**\ (\ ) :ref:`🔗` + +Clears all queued, unplayed animations. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_animation_set_next: +.. _class_AnimationPlayer_method_get_blend_time: + +.. rst-class:: classref-method -- void **animation_set_next** **(** :ref:`StringName` anim_from, :ref:`StringName` anim_to **)** +:ref:`float` **get_blend_time**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) |const| :ref:`🔗` -Triggers the ``anim_to`` animation when the ``anim_from`` animation completes. +Returns the blend time (in seconds) between two animations, referenced by their keys. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_clear_caches: +.. _class_AnimationPlayer_method_get_method_call_mode: + +.. rst-class:: classref-method + +:ref:`AnimationMethodCallMode` **get_method_call_mode**\ (\ ) |const| :ref:`🔗` -- void **clear_caches** **(** **)** +**Deprecated:** Use :ref:`AnimationMixer.callback_mode_method` instead. -``AnimationPlayer`` caches animated nodes. It may not notice if a node disappears; :ref:`clear_caches` forces it to update the cache again. +Returns the call mode used for "Call Method" tracks. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_clear_queue: +.. _class_AnimationPlayer_method_get_playing_speed: -- void **clear_queue** **(** **)** +.. rst-class:: classref-method -Clears all queued, unplayed animations. +:ref:`float` **get_playing_speed**\ (\ ) |const| :ref:`🔗` + +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play()` method. + +Returns a negative value if the current animation is playing backwards. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_find_animation: +.. _class_AnimationPlayer_method_get_process_callback: + +.. rst-class:: classref-method -- :ref:`StringName` **find_animation** **(** :ref:`Animation` animation **)** const +:ref:`AnimationProcessCallback` **get_process_callback**\ (\ ) |const| :ref:`🔗` -Returns the name of ``animation`` or an empty string if not found. +**Deprecated:** Use :ref:`AnimationMixer.callback_mode_process` instead. + +Returns the process notification in which to update animations. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_get_animation: +.. _class_AnimationPlayer_method_get_queue: + +.. rst-class:: classref-method -- :ref:`Animation` **get_animation** **(** :ref:`StringName` name **)** const +:ref:`Array`\[:ref:`StringName`\] **get_queue**\ (\ ) :ref:`🔗` -Returns the :ref:`Animation` with key ``name`` or ``null`` if not found. +Returns a list of the animation keys that are currently queued to play. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_get_animation_list: +.. _class_AnimationPlayer_method_get_root: + +.. rst-class:: classref-method + +:ref:`NodePath` **get_root**\ (\ ) |const| :ref:`🔗` -- :ref:`PackedStringArray` **get_animation_list** **(** **)** const +**Deprecated:** Use :ref:`AnimationMixer.root_node` instead. -Returns the list of stored animation names. +Returns the node which node path references will travel from. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_get_blend_time: +.. _class_AnimationPlayer_method_get_section_end_time: + +.. rst-class:: classref-method + +:ref:`float` **get_section_end_time**\ (\ ) |const| :ref:`🔗` -- :ref:`float` **get_blend_time** **(** :ref:`StringName` anim_from, :ref:`StringName` anim_to **)** const +Returns the end time of the section currently being played. -Gets the blend time (in seconds) between two animations, referenced by their names. +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_get_playing_speed: +.. _class_AnimationPlayer_method_get_section_start_time: + +.. rst-class:: classref-method -- :ref:`float` **get_playing_speed** **(** **)** const +:ref:`float` **get_section_start_time**\ (\ ) |const| :ref:`🔗` -Gets the actual playing speed of current animation or 0 if not playing. This speed is the :ref:`playback_speed` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play` method. +Returns the start time of the section currently being played. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_get_queue: +.. _class_AnimationPlayer_method_has_section: -- :ref:`PackedStringArray` **get_queue** **(** **)** +.. rst-class:: classref-method -Returns a list of the animation names that are currently queued to play. +:ref:`bool` **has_section**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if an animation is currently playing with a section. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_has_animation: +.. _class_AnimationPlayer_method_is_animation_active: + +.. rst-class:: classref-method + +:ref:`bool` **is_animation_active**\ (\ ) |const| :ref:`🔗` -- :ref:`bool` **has_animation** **(** :ref:`StringName` name **)** const +Returns ``true`` if the an animation is currently active. An animation is active if it was played by calling :ref:`play()` and was not finished yet, or was stopped by calling :ref:`stop()`. -Returns ``true`` if the ``AnimationPlayer`` stores an :ref:`Animation` with key ``name``. +This can be used to check whether an animation is currently paused or stopped. + +:: + + var is_paused = not is_playing() and is_animation_active() + var is_stopped = not is_playing() and not is_animation_active() + +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_is_playing: -- :ref:`bool` **is_playing** **(** **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if playing an animation. +Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale` and/or ``custom_speed`` are ``0``). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_pause: + +.. rst-class:: classref-method + +|void| **pause**\ (\ ) :ref:`🔗` + +Pauses the currently playing animation. The :ref:`current_animation_position` will be kept and calling :ref:`play()` or :ref:`play_backwards()` without arguments or with the same animation name as :ref:`assigned_animation` will resume the animation. + +See also :ref:`stop()`. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play: -- void **play** **(** :ref:`StringName` name="", :ref:`float` custom_blend=-1, :ref:`float` custom_speed=1.0, :ref:`bool` from_end=false **)** +.. rst-class:: classref-method + +|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` + +Plays the animation with key ``name``. Custom blend times and speed can be set. + +The ``from_end`` option only affects when switching to a new animation track, or if the same track but at the start or end. It does not affect resuming playback that was paused in the middle of an animation. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards()`). -Plays the animation with key ``name``. Custom blend times and speed can be set. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards`). +The **AnimationPlayer** keeps track of its current or last played animation with :ref:`assigned_animation`. If this method is called with that same animation ``name``, or with no ``name`` parameter, the assigned animation will resume playing if it was paused. -The ``AnimationPlayer`` keeps track of its current or last played animation with :ref:`assigned_animation`. If this method is called with that same animation ``name``, or with no ``name`` parameter, the assigned animation will resume playing if it was paused, or restart if it was stopped (see :ref:`stop` for both pause and stop). If the animation was already playing, it will keep playing. +\ **Note:** The animation will be updated the next time the **AnimationPlayer** is processed. If other variables are updated at the same time this is called, they may be updated too early. To perform the update immediately, call ``advance(0)``. -**Note:** The animation will be updated the next time the ``AnimationPlayer`` is processed. If other variables are updated at the same time this is called, they may be updated too early. To perform the update immediately, call ``advance(0)``. +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play_backwards: -- void **play_backwards** **(** :ref:`StringName` name="", :ref:`float` custom_blend=-1 **)** +.. rst-class:: classref-method + +|void| **play_backwards**\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` Plays the animation with key ``name`` in reverse. -This method is a shorthand for :ref:`play` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. +This method is a shorthand for :ref:`play()` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_queue: +.. _class_AnimationPlayer_method_play_section: -- void **queue** **(** :ref:`StringName` name **)** +.. rst-class:: classref-method -Queues an animation for playback once the current one is done. +|void| **play_section**\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` -**Note:** If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow. +Plays the animation with key ``name`` and the section starting from ``start_time`` and ending on ``end_time``. See also :ref:`play()`. + +Setting ``start_time`` to a value outside the range of the animation means the start of the animation will be used instead, and setting ``end_time`` to a value outside the range of the animation means the end of the animation will be used instead. ``start_time`` cannot be equal to ``end_time``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_section_backwards: + +.. rst-class:: classref-method + +|void| **play_section_backwards**\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` + +Plays the animation with key ``name`` and the section starting from ``start_time`` and ending on ``end_time`` in reverse. + +This method is a shorthand for :ref:`play_section()` with ``custom_speed = -1.0`` and ``from_end = true``, see its description for more information. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_remove_animation: +.. _class_AnimationPlayer_method_play_section_with_markers: + +.. rst-class:: classref-method + +|void| **play_section_with_markers**\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` -- void **remove_animation** **(** :ref:`StringName` name **)** +Plays the animation with key ``name`` and the section starting from ``start_marker`` and ending on ``end_marker``. -Removes the animation with key ``name``. +If the start marker is empty, the section starts from the beginning of the animation. If the end marker is empty, the section ends on the end of the animation. See also :ref:`play()`. + +.. rst-class:: classref-item-separator ---- -.. _class_AnimationPlayer_method_rename_animation: +.. _class_AnimationPlayer_method_play_section_with_markers_backwards: + +.. rst-class:: classref-method + +|void| **play_section_with_markers_backwards**\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` + +Plays the animation with key ``name`` and the section starting from ``start_marker`` and ending on ``end_marker`` in reverse. -- void **rename_animation** **(** :ref:`StringName` name, :ref:`StringName` newname **)** +This method is a shorthand for :ref:`play_section_with_markers()` with ``custom_speed = -1.0`` and ``from_end = true``, see its description for more information. -Renames an existing animation with key ``name`` to ``newname``. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_with_capture: + +.. rst-class:: classref-method + +|void| **play_with_capture**\ (\ name\: :ref:`StringName` = &"", duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) :ref:`🔗` + +See also :ref:`AnimationMixer.capture()`. + +You can use this method to use more detailed options for capture than those performed by :ref:`playback_auto_capture`. When :ref:`playback_auto_capture` is ``false``, this method is almost the same as the following: + +:: + + capture(name, duration, trans_type, ease_type) + play(name, custom_blend, custom_speed, from_end) + +If ``name`` is blank, it specifies :ref:`assigned_animation`. + +If ``duration`` is a negative value, the duration is set to the interval between the current position and the first key, when ``from_end`` is ``true``, uses the interval between the current position and the last key instead. + +\ **Note:** The ``duration`` takes :ref:`speed_scale` into account, but ``custom_speed`` does not, because the capture cache is interpolated with the blend result and the result may contain multiple animations. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_queue: + +.. rst-class:: classref-method + +|void| **queue**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Queues an animation for playback once the current animation and all previously queued animations are done. + +\ **Note:** If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_reset_section: + +.. rst-class:: classref-method + +|void| **reset_section**\ (\ ) :ref:`🔗` + +Resets the current section. Does nothing if a section has not been set. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_seek: -- void **seek** **(** :ref:`float` seconds, :ref:`bool` update=false **)** +.. rst-class:: classref-method + +|void| **seek**\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) :ref:`🔗` Seeks the animation to the ``seconds`` point in time (in seconds). If ``update`` is ``true``, the animation updates too, otherwise it updates at process time. Events between the current frame and ``seconds`` are skipped. +If ``update_only`` is ``true``, the method / audio / animation playback tracks will not be processed. + +\ **Note:** Seeking to the end of the animation doesn't emit :ref:`AnimationMixer.animation_finished`. If you want to skip animation and emit the signal, use :ref:`AnimationMixer.advance()`. + +.. rst-class:: classref-item-separator + ---- .. _class_AnimationPlayer_method_set_blend_time: -- void **set_blend_time** **(** :ref:`StringName` anim_from, :ref:`StringName` anim_to, :ref:`float` sec **)** +.. rst-class:: classref-method + +|void| **set_blend_time**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) :ref:`🔗` + +Specifies a blend time (in seconds) between two animations, referenced by their keys. -Specifies a blend time (in seconds) between two animations, referenced by their names. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_set_method_call_mode: + +.. rst-class:: classref-method + +|void| **set_method_call_mode**\ (\ mode\: :ref:`AnimationMethodCallMode`\ ) :ref:`🔗` + +**Deprecated:** Use :ref:`AnimationMixer.callback_mode_method` instead. + +Sets the call mode used for "Call Method" tracks. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_set_process_callback: + +.. rst-class:: classref-method + +|void| **set_process_callback**\ (\ mode\: :ref:`AnimationProcessCallback`\ ) :ref:`🔗` + +**Deprecated:** Use :ref:`AnimationMixer.callback_mode_process` instead. + +Sets the process notification in which to update animations. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_set_root: + +.. rst-class:: classref-method + +|void| **set_root**\ (\ path\: :ref:`NodePath`\ ) :ref:`🔗` + +**Deprecated:** Use :ref:`AnimationMixer.root_node` instead. + +Sets the node which node path references will travel from. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_set_section: + +.. rst-class:: classref-method + +|void| **set_section**\ (\ start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1\ ) :ref:`🔗` + +Changes the start and end times of the section being played. The current playback position will be clamped within the new section. See also :ref:`play_section()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_set_section_with_markers: + +.. rst-class:: classref-method + +|void| **set_section_with_markers**\ (\ start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &""\ ) :ref:`🔗` + +Changes the start and end markers of the section being played. The current playback position will be clamped within the new section. See also :ref:`play_section_with_markers()`. + +If the argument is empty, the section uses the beginning or end of the animation. If both are empty, it means that the section is not set. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_stop: -- void **stop** **(** :ref:`bool` reset=true **)** +.. rst-class:: classref-method + +|void| **stop**\ (\ keep_state\: :ref:`bool` = false\ ) :ref:`🔗` + +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause()`. -Stops or pauses the currently playing animation. If ``reset`` is ``true``, the animation position is reset to ``0`` and the playback speed is reset to ``1.0``. +If ``keep_state`` is ``true``, the animation state is not updated visually. -If ``reset`` is ``false``, the :ref:`current_animation_position` will be kept and calling :ref:`play` or :ref:`play_backwards` without arguments or with the same animation name as :ref:`assigned_animation` will resume the animation. +\ **Note:** The method / audio / animation playback tracks will not be processed by this method. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationrootnode.rst b/classes/class_animationrootnode.rst index ece1f97a691..20aea2e587a 100644 --- a/classes/class_animationrootnode.rst +++ b/classes/class_animationrootnode.rst @@ -1,17 +1,43 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationRootNode.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationRootNode.xml. .. _class_AnimationRootNode: AnimationRootNode ================= -**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` **Inherited By:** :ref:`AnimationNodeAnimation`, :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeBlendTree`, :ref:`AnimationNodeStateMachine` +Base class for :ref:`AnimationNode`\ s that hold one or multiple composite animations. Usually used for :ref:`AnimationTree.tree_root`. +.. rst-class:: classref-introduction-group +Description +----------- + +**AnimationRootNode** is a base class for :ref:`AnimationNode`\ s that hold a complete animation. A complete animation refers to the output of an :ref:`AnimationNodeOutput` in an :ref:`AnimationNodeBlendTree` or the output of another **AnimationRootNode**. Used for :ref:`AnimationTree.tree_root` or in other **AnimationRootNode**\ s. + +Examples of built-in root nodes include :ref:`AnimationNodeBlendTree` (allows blending nodes between each other using various modes), :ref:`AnimationNodeStateMachine` (allows to configure blending and transitions between nodes using a state machine pattern), :ref:`AnimationNodeBlendSpace2D` (allows linear blending between **three** :ref:`AnimationNode`\ s), :ref:`AnimationNodeBlendSpace1D` (allows linear blending only between **two** :ref:`AnimationNode`\ s). + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationtrackeditplugin.rst b/classes/class_animationtrackeditplugin.rst deleted file mode 100644 index aa91f849af4..00000000000 --- a/classes/class_animationtrackeditplugin.rst +++ /dev/null @@ -1,15 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationTrackEditPlugin.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_AnimationTrackEditPlugin: - -AnimationTrackEditPlugin -======================== - -**Inherits:** :ref:`Reference` **<** :ref:`Object` - - - diff --git a/classes/class_animationtree.rst b/classes/class_animationtree.rst index a8c6676831a..096f6de963f 100644 --- a/classes/class_animationtree.rst +++ b/classes/class_animationtree.rst @@ -1,165 +1,228 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AnimationTree.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationTree.xml. .. _class_AnimationTree: AnimationTree ============= -**Inherits:** :ref:`Node` **<** :ref:`Object` +**Inherits:** :ref:`AnimationMixer` **<** :ref:`Node` **<** :ref:`Object` -A node to be used for advanced animation transitions in an :ref:`AnimationPlayer`. +A node used for advanced animation transitions in an :ref:`AnimationPlayer`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A node used for advanced animation transitions in an :ref:`AnimationPlayer`. + +\ **Note:** When linked with an :ref:`AnimationPlayer`, several properties and methods of the corresponding :ref:`AnimationPlayer` will not function as expected. Playback and transitions should be handled using only the **AnimationTree** and its constituent :ref:`AnimationNode`\ (s). The :ref:`AnimationPlayer` node should be used solely for adding, deleting, and editing animations. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/animation/animation_tree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` + +- `Third Person Shooter (TPS) Demo `__ -- `https://github.com/godotengine/tps-demo `_ +.. rst-class:: classref-reftable-group Properties ---------- -+----------------------------------------------------------------------+--------------------------------------------------------------------------+------------------+ -| :ref:`bool` | :ref:`active` | ``false`` | -+----------------------------------------------------------------------+--------------------------------------------------------------------------+------------------+ -| :ref:`NodePath` | :ref:`anim_player` | ``NodePath("")`` | -+----------------------------------------------------------------------+--------------------------------------------------------------------------+------------------+ -| :ref:`AnimationProcessMode` | :ref:`process_mode` | ``1`` | -+----------------------------------------------------------------------+--------------------------------------------------------------------------+------------------+ -| :ref:`NodePath` | :ref:`root_motion_track` | ``NodePath("")`` | -+----------------------------------------------------------------------+--------------------------------------------------------------------------+------------------+ -| :ref:`AnimationNode` | :ref:`tree_root` | | -+----------------------------------------------------------------------+--------------------------------------------------------------------------+------------------+ +.. table:: + :widths: auto + + +-----------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`advance_expression_base_node` | ``NodePath(".")`` | + +-----------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`anim_player` | ``NodePath("")`` | + +-----------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + | :ref:`AnimationCallbackModeDiscrete` | callback_mode_discrete | ``2`` (overrides :ref:`AnimationMixer`) | + +-----------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + | :ref:`bool` | deterministic | ``true`` (overrides :ref:`AnimationMixer`) | + +-----------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + | :ref:`AnimationRootNode` | :ref:`tree_root` | | + +-----------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`advance` **(** :ref:`float` delta **)** | -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform` | :ref:`get_root_motion_transform` **(** **)** const | -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`rename_parameter` **(** :ref:`String` old_name, :ref:`String` new_name **)** | -+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationProcessCallback` | :ref:`get_process_callback`\ (\ ) |const| | + +------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_process_callback`\ (\ mode\: :ref:`AnimationProcessCallback`\ ) | + +------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_AnimationTree_signal_animation_player_changed: + +.. rst-class:: classref-signal + +**animation_player_changed**\ (\ ) :ref:`🔗` + +Emitted when the :ref:`anim_player` is changed. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ -.. _enum_AnimationTree_AnimationProcessMode: +.. _enum_AnimationTree_AnimationProcessCallback: + +.. rst-class:: classref-enumeration + +enum **AnimationProcessCallback**: :ref:`🔗` .. _class_AnimationTree_constant_ANIMATION_PROCESS_PHYSICS: +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationProcessCallback` **ANIMATION_PROCESS_PHYSICS** = ``0`` + +**Deprecated:** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS`. + + + .. _class_AnimationTree_constant_ANIMATION_PROCESS_IDLE: +.. rst-class:: classref-enumeration-constant + +:ref:`AnimationProcessCallback` **ANIMATION_PROCESS_IDLE** = ``1`` + +**Deprecated:** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE`. + + + .. _class_AnimationTree_constant_ANIMATION_PROCESS_MANUAL: -enum **AnimationProcessMode**: +.. rst-class:: classref-enumeration-constant -- **ANIMATION_PROCESS_PHYSICS** = **0** --- The animations will progress during the physics frame (i.e. :ref:`Node._physics_process`). +:ref:`AnimationProcessCallback` **ANIMATION_PROCESS_MANUAL** = ``2`` -- **ANIMATION_PROCESS_IDLE** = **1** --- The animations will progress during the idle frame (i.e. :ref:`Node._process`). +**Deprecated:** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL`. -- **ANIMATION_PROCESS_MANUAL** = **2** --- The animations will only progress manually (see :ref:`advance`). + + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- -.. _class_AnimationTree_property_active: +.. _class_AnimationTree_property_advance_expression_base_node: + +.. rst-class:: classref-property + +:ref:`NodePath` **advance_expression_base_node** = ``NodePath(".")`` :ref:`🔗` -- :ref:`bool` **active** +.. rst-class:: classref-property-setget -+-----------+-------------------+ -| *Default* | ``false`` | -+-----------+-------------------+ -| *Setter* | set_active(value) | -+-----------+-------------------+ -| *Getter* | is_active() | -+-----------+-------------------+ +- |void| **set_advance_expression_base_node**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_advance_expression_base_node**\ (\ ) -If ``true``, the ``AnimationTree`` will be processing. +The path to the :ref:`Node` used to evaluate the :ref:`AnimationNode` :ref:`Expression` if one is not explicitly specified internally. + +.. rst-class:: classref-item-separator ---- .. _class_AnimationTree_property_anim_player: -- :ref:`NodePath` **anim_player** +.. rst-class:: classref-property + +:ref:`NodePath` **anim_player** = ``NodePath("")`` :ref:`🔗` -+-----------+-----------------------------+ -| *Default* | ``NodePath("")`` | -+-----------+-----------------------------+ -| *Setter* | set_animation_player(value) | -+-----------+-----------------------------+ -| *Getter* | get_animation_player() | -+-----------+-----------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_animation_player**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_animation_player**\ (\ ) The path to the :ref:`AnimationPlayer` used for animating. ----- +.. rst-class:: classref-item-separator -.. _class_AnimationTree_property_process_mode: +---- -- :ref:`AnimationProcessMode` **process_mode** +.. _class_AnimationTree_property_tree_root: -+-----------+-------------------------+ -| *Default* | ``1`` | -+-----------+-------------------------+ -| *Setter* | set_process_mode(value) | -+-----------+-------------------------+ -| *Getter* | get_process_mode() | -+-----------+-------------------------+ +.. rst-class:: classref-property -The process mode of this ``AnimationTree``. See :ref:`AnimationProcessMode` for available modes. +:ref:`AnimationRootNode` **tree_root** :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_AnimationTree_property_root_motion_track: +- |void| **set_tree_root**\ (\ value\: :ref:`AnimationRootNode`\ ) +- :ref:`AnimationRootNode` **get_tree_root**\ (\ ) -- :ref:`NodePath` **root_motion_track** +The root animation node of this **AnimationTree**. See :ref:`AnimationRootNode`. -+-----------+------------------------------+ -| *Default* | ``NodePath("")`` | -+-----------+------------------------------+ -| *Setter* | set_root_motion_track(value) | -+-----------+------------------------------+ -| *Getter* | get_root_motion_track() | -+-----------+------------------------------+ +.. rst-class:: classref-section-separator ---- -.. _class_AnimationTree_property_tree_root: +.. rst-class:: classref-descriptions-group -- :ref:`AnimationNode` **tree_root** +Method Descriptions +------------------- -+----------+----------------------+ -| *Setter* | set_tree_root(value) | -+----------+----------------------+ -| *Getter* | get_tree_root() | -+----------+----------------------+ +.. _class_AnimationTree_method_get_process_callback: -The root animation node of this ``AnimationTree``. See :ref:`AnimationNode`. +.. rst-class:: classref-method -Method Descriptions -------------------- +:ref:`AnimationProcessCallback` **get_process_callback**\ (\ ) |const| :ref:`🔗` -.. _class_AnimationTree_method_advance: +**Deprecated:** Use :ref:`AnimationMixer.callback_mode_process` instead. -- void **advance** **(** :ref:`float` delta **)** +Returns the process notification in which to update animations. -Manually advance the animations by the specified time (in seconds). +.. rst-class:: classref-item-separator ---- -.. _class_AnimationTree_method_get_root_motion_transform: +.. _class_AnimationTree_method_set_process_callback: -- :ref:`Transform` **get_root_motion_transform** **(** **)** const +.. rst-class:: classref-method ----- +|void| **set_process_callback**\ (\ mode\: :ref:`AnimationProcessCallback`\ ) :ref:`🔗` -.. _class_AnimationTree_method_rename_parameter: +**Deprecated:** Use :ref:`AnimationMixer.callback_mode_process` instead. -- void **rename_parameter** **(** :ref:`String` old_name, :ref:`String` new_name **)** +Sets the process notification in which to update animations. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_area.rst b/classes/class_area.rst deleted file mode 100644 index d70ee938ed6..00000000000 --- a/classes/class_area.rst +++ /dev/null @@ -1,542 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Area.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_Area: - -Area -==== - -**Inherits:** :ref:`CollisionObject` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -General-purpose area node for detection and 3D physics influence. - -Description ------------ - -3D area that detects :ref:`CollisionObject` nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping). - -Properties ----------- - -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`angular_damp` | ``0.1`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`StringName` | :ref:`audio_bus_name` | ``@"Master"`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`audio_bus_override` | ``false`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`collision_layer` | ``1`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`collision_mask` | ``1`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`gravity` | ``9.8`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`gravity_distance_scale` | ``0.0`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`gravity_point` | ``false`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`Vector3` | :ref:`gravity_vec` | ``Vector3( 0, -1, 0 )`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`linear_damp` | ``0.1`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`monitorable` | ``true`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`monitoring` | ``true`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`priority` | ``0.0`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`reverb_bus_amount` | ``0.0`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`reverb_bus_enable` | ``false`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`StringName` | :ref:`reverb_bus_name` | ``@"Master"`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`reverb_bus_uniformity` | ``0.0`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`SpaceOverride` | :ref:`space_override` | ``0`` | -+-----------------------------------------------+---------------------------------------------------------------------------+-------------------------+ - -Methods -------- - -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_collision_layer_bit` **(** :ref:`int` bit **)** const | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_collision_mask_bit` **(** :ref:`int` bit **)** const | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_overlapping_areas` **(** **)** const | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_overlapping_bodies` **(** **)** const | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`overlaps_area` **(** :ref:`Node` area **)** const | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`overlaps_body` **(** :ref:`Node` body **)** const | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_collision_layer_bit` **(** :ref:`int` bit, :ref:`bool` value **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_collision_mask_bit` **(** :ref:`int` bit, :ref:`bool` value **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ - -Signals -------- - -.. _class_Area_signal_area_entered: - -- **area_entered** **(** :ref:`Area` area **)** - -Emitted when another area enters. - ----- - -.. _class_Area_signal_area_exited: - -- **area_exited** **(** :ref:`Area` area **)** - -Emitted when another area exits. - ----- - -.. _class_Area_signal_area_shape_entered: - -- **area_shape_entered** **(** :ref:`int` area_id, :ref:`Area` area, :ref:`int` area_shape, :ref:`int` self_shape **)** - -Emitted when another area enters, reporting which areas overlapped. ``shape_owner_get_owner(shape_find_owner(shape))`` returns the parent object of the owner of the ``shape``. - ----- - -.. _class_Area_signal_area_shape_exited: - -- **area_shape_exited** **(** :ref:`int` area_id, :ref:`Area` area, :ref:`int` area_shape, :ref:`int` self_shape **)** - -Emitted when another area exits, reporting which areas were overlapping. - ----- - -.. _class_Area_signal_body_entered: - -- **body_entered** **(** :ref:`Node` body **)** - -Emitted when a physics body enters. - -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). - ----- - -.. _class_Area_signal_body_exited: - -- **body_exited** **(** :ref:`Node` body **)** - -Emitted when a physics body exits. - -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). - ----- - -.. _class_Area_signal_body_shape_entered: - -- **body_shape_entered** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` area_shape **)** - -Emitted when a physics body enters, reporting which shapes overlapped. - -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). - ----- - -.. _class_Area_signal_body_shape_exited: - -- **body_shape_exited** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` area_shape **)** - -Emitted when a physics body exits, reporting which shapes were overlapping. - -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). - -Enumerations ------------- - -.. _enum_Area_SpaceOverride: - -.. _class_Area_constant_SPACE_OVERRIDE_DISABLED: - -.. _class_Area_constant_SPACE_OVERRIDE_COMBINE: - -.. _class_Area_constant_SPACE_OVERRIDE_COMBINE_REPLACE: - -.. _class_Area_constant_SPACE_OVERRIDE_REPLACE: - -.. _class_Area_constant_SPACE_OVERRIDE_REPLACE_COMBINE: - -enum **SpaceOverride**: - -- **SPACE_OVERRIDE_DISABLED** = **0** --- This area does not affect gravity/damping. - -- **SPACE_OVERRIDE_COMBINE** = **1** --- This area adds its gravity/damping values to whatever has been calculated so far (in :ref:`priority` order). - -- **SPACE_OVERRIDE_COMBINE_REPLACE** = **2** --- This area adds its gravity/damping values to whatever has been calculated so far (in :ref:`priority` order), ignoring any lower priority areas. - -- **SPACE_OVERRIDE_REPLACE** = **3** --- This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas. - -- **SPACE_OVERRIDE_REPLACE_COMBINE** = **4** --- This area replaces any gravity/damping calculated so far (in :ref:`priority` order), but keeps calculating the rest of the areas. - -Property Descriptions ---------------------- - -.. _class_Area_property_angular_damp: - -- :ref:`float` **angular_damp** - -+-----------+-------------------------+ -| *Default* | ``0.1`` | -+-----------+-------------------------+ -| *Setter* | set_angular_damp(value) | -+-----------+-------------------------+ -| *Getter* | get_angular_damp() | -+-----------+-------------------------+ - -The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. Values range from ``0`` (no damping) to ``1`` (full damping). - ----- - -.. _class_Area_property_audio_bus_name: - -- :ref:`StringName` **audio_bus_name** - -+-----------+----------------------+ -| *Default* | ``@"Master"`` | -+-----------+----------------------+ -| *Setter* | set_audio_bus(value) | -+-----------+----------------------+ -| *Getter* | get_audio_bus() | -+-----------+----------------------+ - -The name of the area's audio bus. - ----- - -.. _class_Area_property_audio_bus_override: - -- :ref:`bool` **audio_bus_override** - -+-----------+-------------------------------+ -| *Default* | ``false`` | -+-----------+-------------------------------+ -| *Setter* | set_audio_bus_override(value) | -+-----------+-------------------------------+ -| *Getter* | is_overriding_audio_bus() | -+-----------+-------------------------------+ - -If ``true``, the area's audio bus overrides the default audio bus. - ----- - -.. _class_Area_property_collision_layer: - -- :ref:`int` **collision_layer** - -+-----------+----------------------------+ -| *Default* | ``1`` | -+-----------+----------------------------+ -| *Setter* | set_collision_layer(value) | -+-----------+----------------------------+ -| *Getter* | get_collision_layer() | -+-----------+----------------------------+ - -The area's physics layer(s). Collidable objects can exist in any of 32 different layers. A contact is detected if object A is in any of the layers that object B scans, or object B is in any layers that object A scans. See also :ref:`collision_mask`. - ----- - -.. _class_Area_property_collision_mask: - -- :ref:`int` **collision_mask** - -+-----------+---------------------------+ -| *Default* | ``1`` | -+-----------+---------------------------+ -| *Setter* | set_collision_mask(value) | -+-----------+---------------------------+ -| *Getter* | get_collision_mask() | -+-----------+---------------------------+ - -The physics layers this area scans to determine collision detection. - ----- - -.. _class_Area_property_gravity: - -- :ref:`float` **gravity** - -+-----------+--------------------+ -| *Default* | ``9.8`` | -+-----------+--------------------+ -| *Setter* | set_gravity(value) | -+-----------+--------------------+ -| *Getter* | get_gravity() | -+-----------+--------------------+ - -The area's gravity intensity (ranges from -1024 to 1024). This value multiplies the gravity vector. This is useful to alter the force of gravity without altering its direction. - ----- - -.. _class_Area_property_gravity_distance_scale: - -- :ref:`float` **gravity_distance_scale** - -+-----------+-----------------------------------+ -| *Default* | ``0.0`` | -+-----------+-----------------------------------+ -| *Setter* | set_gravity_distance_scale(value) | -+-----------+-----------------------------------+ -| *Getter* | get_gravity_distance_scale() | -+-----------+-----------------------------------+ - -The falloff factor for point gravity. The greater the value, the faster gravity decreases with distance. - ----- - -.. _class_Area_property_gravity_point: - -- :ref:`bool` **gravity_point** - -+-----------+-----------------------------+ -| *Default* | ``false`` | -+-----------+-----------------------------+ -| *Setter* | set_gravity_is_point(value) | -+-----------+-----------------------------+ -| *Getter* | is_gravity_a_point() | -+-----------+-----------------------------+ - -If ``true``, gravity is calculated from a point (set via :ref:`gravity_vec`). See also :ref:`space_override`. - ----- - -.. _class_Area_property_gravity_vec: - -- :ref:`Vector3` **gravity_vec** - -+-----------+---------------------------+ -| *Default* | ``Vector3( 0, -1, 0 )`` | -+-----------+---------------------------+ -| *Setter* | set_gravity_vector(value) | -+-----------+---------------------------+ -| *Getter* | get_gravity_vector() | -+-----------+---------------------------+ - -The area's gravity vector (not normalized). If gravity is a point (see :ref:`gravity_point`), this will be the point of attraction. - ----- - -.. _class_Area_property_linear_damp: - -- :ref:`float` **linear_damp** - -+-----------+------------------------+ -| *Default* | ``0.1`` | -+-----------+------------------------+ -| *Setter* | set_linear_damp(value) | -+-----------+------------------------+ -| *Getter* | get_linear_damp() | -+-----------+------------------------+ - -The rate at which objects stop moving in this area. Represents the linear velocity lost per second. Values range from ``0`` (no damping) to ``1`` (full damping). - ----- - -.. _class_Area_property_monitorable: - -- :ref:`bool` **monitorable** - -+-----------+------------------------+ -| *Default* | ``true`` | -+-----------+------------------------+ -| *Setter* | set_monitorable(value) | -+-----------+------------------------+ -| *Getter* | is_monitorable() | -+-----------+------------------------+ - -If ``true``, other monitoring areas can detect this area. - ----- - -.. _class_Area_property_monitoring: - -- :ref:`bool` **monitoring** - -+-----------+-----------------------+ -| *Default* | ``true`` | -+-----------+-----------------------+ -| *Setter* | set_monitoring(value) | -+-----------+-----------------------+ -| *Getter* | is_monitoring() | -+-----------+-----------------------+ - -If ``true``, the area detects bodies or areas entering and exiting it. - ----- - -.. _class_Area_property_priority: - -- :ref:`float` **priority** - -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_priority(value) | -+-----------+---------------------+ -| *Getter* | get_priority() | -+-----------+---------------------+ - -The area's priority. Higher priority areas are processed first. - ----- - -.. _class_Area_property_reverb_bus_amount: - -- :ref:`float` **reverb_bus_amount** - -+-----------+--------------------------+ -| *Default* | ``0.0`` | -+-----------+--------------------------+ -| *Setter* | set_reverb_amount(value) | -+-----------+--------------------------+ -| *Getter* | get_reverb_amount() | -+-----------+--------------------------+ - -The degree to which this area applies reverb to its associated audio. Ranges from ``0`` to ``1`` with ``0.1`` precision. - ----- - -.. _class_Area_property_reverb_bus_enable: - -- :ref:`bool` **reverb_bus_enable** - -+-----------+---------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------+ -| *Setter* | set_use_reverb_bus(value) | -+-----------+---------------------------+ -| *Getter* | is_using_reverb_bus() | -+-----------+---------------------------+ - -If ``true``, the area applies reverb to its associated audio. - ----- - -.. _class_Area_property_reverb_bus_name: - -- :ref:`StringName` **reverb_bus_name** - -+-----------+-----------------------+ -| *Default* | ``@"Master"`` | -+-----------+-----------------------+ -| *Setter* | set_reverb_bus(value) | -+-----------+-----------------------+ -| *Getter* | get_reverb_bus() | -+-----------+-----------------------+ - -The reverb bus name to use for this area's associated audio. - ----- - -.. _class_Area_property_reverb_bus_uniformity: - -- :ref:`float` **reverb_bus_uniformity** - -+-----------+------------------------------+ -| *Default* | ``0.0`` | -+-----------+------------------------------+ -| *Setter* | set_reverb_uniformity(value) | -+-----------+------------------------------+ -| *Getter* | get_reverb_uniformity() | -+-----------+------------------------------+ - -The degree to which this area's reverb is a uniform effect. Ranges from ``0`` to ``1`` with ``0.1`` precision. - ----- - -.. _class_Area_property_space_override: - -- :ref:`SpaceOverride` **space_override** - -+-----------+--------------------------------+ -| *Default* | ``0`` | -+-----------+--------------------------------+ -| *Setter* | set_space_override_mode(value) | -+-----------+--------------------------------+ -| *Getter* | get_space_override_mode() | -+-----------+--------------------------------+ - -Override mode for gravity and damping calculations within this area. See :ref:`SpaceOverride` for possible values. - -Method Descriptions -------------------- - -.. _class_Area_method_get_collision_layer_bit: - -- :ref:`bool` **get_collision_layer_bit** **(** :ref:`int` bit **)** const - -Returns an individual bit on the layer mask. - ----- - -.. _class_Area_method_get_collision_mask_bit: - -- :ref:`bool` **get_collision_mask_bit** **(** :ref:`int` bit **)** const - -Returns an individual bit on the collision mask. - ----- - -.. _class_Area_method_get_overlapping_areas: - -- :ref:`Array` **get_overlapping_areas** **(** **)** const - -Returns a list of intersecting ``Area``\ s. For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. - ----- - -.. _class_Area_method_get_overlapping_bodies: - -- :ref:`Array` **get_overlapping_bodies** **(** **)** const - -Returns a list of intersecting :ref:`PhysicsBody`\ s. For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. - ----- - -.. _class_Area_method_overlaps_area: - -- :ref:`bool` **overlaps_area** **(** :ref:`Node` area **)** const - -If ``true``, the given area overlaps the Area. - -**Note:** The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead. - ----- - -.. _class_Area_method_overlaps_body: - -- :ref:`bool` **overlaps_body** **(** :ref:`Node` body **)** const - -If ``true``, the given physics body overlaps the Area. - -**Note:** The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead. - -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). - ----- - -.. _class_Area_method_set_collision_layer_bit: - -- void **set_collision_layer_bit** **(** :ref:`int` bit, :ref:`bool` value **)** - -Set/clear individual bits on the layer mask. This simplifies editing this ``Area``'s layers. - ----- - -.. _class_Area_method_set_collision_mask_bit: - -- void **set_collision_mask_bit** **(** :ref:`int` bit, :ref:`bool` value **)** - -Set/clear individual bits on the collision mask. This simplifies editing which ``Area`` layers this ``Area`` scans. - diff --git a/classes/class_area2d.rst b/classes/class_area2d.rst index 2c04f52d137..47248ca9945 100644 --- a/classes/class_area2d.rst +++ b/classes/class_area2d.rst @@ -1,8 +1,12 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Area2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. meta:: + :keywords: trigger + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Area2D.xml. .. _class_Area2D: @@ -11,465 +15,651 @@ Area2D **Inherits:** :ref:`CollisionObject2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -2D area for detection and 2D physics influence. +A region of 2D space that detects other :ref:`CollisionObject2D`\ s entering or exiting it. + +.. rst-class:: classref-introduction-group Description ----------- -2D area that detects :ref:`CollisionObject2D` nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping). +**Area2D** is a region of 2D space defined by one or multiple :ref:`CollisionShape2D` or :ref:`CollisionPolygon2D` child nodes. It detects when other :ref:`CollisionObject2D`\ s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it). + +This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. + +\ **Note:** Areas and bodies created with :ref:`PhysicsServer2D` might not interact as expected with **Area2D**\ s, and might not emit signals or track objects correctly. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/physics/using_area_2d` +- :doc:`Using Area2D <../tutorials/physics/using_area_2d>` + +- `2D Dodge The Creeps Demo `__ + +- `2D Pong Demo `__ + +- `2D Platformer Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`angular_damp` | ``1.0`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`StringName` | :ref:`audio_bus_name` | ``@"Master"`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`audio_bus_override` | ``false`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`collision_layer` | ``1`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`collision_mask` | ``1`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`gravity` | ``98.0`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`gravity_distance_scale` | ``0.0`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`gravity_point` | ``false`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`gravity_vec` | ``Vector2( 0, 1 )`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`linear_damp` | ``0.1`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`monitorable` | ``true`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`monitoring` | ``true`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`priority` | ``0.0`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ -| :ref:`SpaceOverride` | :ref:`space_override` | ``0`` | -+-------------------------------------------------+-----------------------------------------------------------------------------+---------------------+ +.. table:: + :widths: auto + + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`angular_damp` | ``1.0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`SpaceOverride` | :ref:`angular_damp_space_override` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`StringName` | :ref:`audio_bus_name` | ``&"Master"`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`audio_bus_override` | ``false`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`gravity` | ``980.0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`Vector2` | :ref:`gravity_direction` | ``Vector2(0, 1)`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`gravity_point` | ``false`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`Vector2` | :ref:`gravity_point_center` | ``Vector2(0, 1)`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`gravity_point_unit_distance` | ``0.0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`SpaceOverride` | :ref:`gravity_space_override` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`linear_damp` | ``0.1`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`SpaceOverride` | :ref:`linear_damp_space_override` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`monitorable` | ``true`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`monitoring` | ``true`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`int` | :ref:`priority` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_collision_layer_bit` **(** :ref:`int` bit **)** const | -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_collision_mask_bit` **(** :ref:`int` bit **)** const | -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_overlapping_areas` **(** **)** const | -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_overlapping_bodies` **(** **)** const | -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`overlaps_area` **(** :ref:`Node` area **)** const | -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`overlaps_body` **(** :ref:`Node` body **)** const | -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_collision_layer_bit` **(** :ref:`int` bit, :ref:`bool` value **)** | -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_collision_mask_bit` **(** :ref:`int` bit, :ref:`bool` value **)** | -+---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Area2D`\] | :ref:`get_overlapping_areas`\ (\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Node2D`\] | :ref:`get_overlapping_bodies`\ (\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_overlapping_areas`\ (\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_overlapping_bodies`\ (\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`overlaps_area`\ (\ area\: :ref:`Node`\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`overlaps_body`\ (\ body\: :ref:`Node`\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_Area2D_signal_area_entered: -- **area_entered** **(** :ref:`Area2D` area **)** +.. rst-class:: classref-signal + +**area_entered**\ (\ area\: :ref:`Area2D`\ ) :ref:`🔗` -Emitted when another area enters. +Emitted when the received ``area`` enters this area. Requires :ref:`monitoring` to be set to ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_signal_area_exited: -- **area_exited** **(** :ref:`Area2D` area **)** +.. rst-class:: classref-signal + +**area_exited**\ (\ area\: :ref:`Area2D`\ ) :ref:`🔗` -Emitted when another area exits. +Emitted when the received ``area`` exits this area. Requires :ref:`monitoring` to be set to ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_signal_area_shape_entered: -- **area_shape_entered** **(** :ref:`int` area_id, :ref:`Area2D` area, :ref:`int` area_shape, :ref:`int` self_shape **)** +.. rst-class:: classref-signal + +**area_shape_entered**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area2D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`Shape2D` of the received ``area`` enters a shape of this area. Requires :ref:`monitoring` to be set to ``true``. + +\ ``local_shape_index`` and ``area_shape_index`` contain indices of the interacting shapes from this area and the other area, respectively. ``area_rid`` contains the :ref:`RID` of the other area. These values can be used with the :ref:`PhysicsServer2D`. -Emitted when another area enters, reporting which shapes overlapped. ``shape_owner_get_owner(shape_find_owner(shape))`` returns the parent object of the owner of the ``shape``. +\ **Example:** Get the :ref:`CollisionShape2D` node from the shape index: + + +.. tabs:: + + .. code-tab:: gdscript + + var other_shape_owner = area.shape_find_owner(area_shape_index) + var other_shape_node = area.shape_owner_get_owner(other_shape_owner) + + var local_shape_owner = shape_find_owner(local_shape_index) + var local_shape_node = shape_owner_get_owner(local_shape_owner) + + + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_signal_area_shape_exited: -- **area_shape_exited** **(** :ref:`int` area_id, :ref:`Area2D` area, :ref:`int` area_shape, :ref:`int` self_shape **)** +.. rst-class:: classref-signal + +**area_shape_exited**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area2D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` -Emitted when another area exits, reporting which shapes were overlapping. +Emitted when a :ref:`Shape2D` of the received ``area`` exits a shape of this area. Requires :ref:`monitoring` to be set to ``true``. + +See also :ref:`area_shape_entered`. + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_signal_body_entered: -- **body_entered** **(** :ref:`Node` body **)** +.. rst-class:: classref-signal + +**body_entered**\ (\ body\: :ref:`Node2D`\ ) :ref:`🔗` -Emitted when a physics body enters. +Emitted when the received ``body`` enters this area. ``body`` can be a :ref:`PhysicsBody2D` or a :ref:`TileMap`. :ref:`TileMap`\ s are detected if their :ref:`TileSet` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +.. rst-class:: classref-item-separator ---- .. _class_Area2D_signal_body_exited: -- **body_exited** **(** :ref:`Node` body **)** +.. rst-class:: classref-signal -Emitted when a physics body exits. +**body_exited**\ (\ body\: :ref:`Node2D`\ ) :ref:`🔗` -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +Emitted when the received ``body`` exits this area. ``body`` can be a :ref:`PhysicsBody2D` or a :ref:`TileMap`. :ref:`TileMap`\ s are detected if their :ref:`TileSet` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_signal_body_shape_entered: -- **body_shape_entered** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` area_shape **)** +.. rst-class:: classref-signal + +**body_shape_entered**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node2D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`Shape2D` of the received ``body`` enters a shape of this area. ``body`` can be a :ref:`PhysicsBody2D` or a :ref:`TileMap`. :ref:`TileMap`\ s are detected if their :ref:`TileSet` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. + +\ ``local_shape_index`` and ``body_shape_index`` contain indices of the interacting shapes from this area and the interacting body, respectively. ``body_rid`` contains the :ref:`RID` of the body. These values can be used with the :ref:`PhysicsServer2D`. + +\ **Example:** Get the :ref:`CollisionShape2D` node from the shape index: + -Emitted when a physics body enters, reporting which shapes overlapped. +.. tabs:: -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). + .. code-tab:: gdscript + + var body_shape_owner = body.shape_find_owner(body_shape_index) + var body_shape_node = body.shape_owner_get_owner(body_shape_owner) + + var local_shape_owner = shape_find_owner(local_shape_index) + var local_shape_node = shape_owner_get_owner(local_shape_owner) + + + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_signal_body_shape_exited: -- **body_shape_exited** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` area_shape **)** +.. rst-class:: classref-signal + +**body_shape_exited**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node2D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`Shape2D` of the received ``body`` exits a shape of this area. ``body`` can be a :ref:`PhysicsBody2D` or a :ref:`TileMap`. :ref:`TileMap`\ s are detected if their :ref:`TileSet` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. + +See also :ref:`body_shape_entered`. + +.. rst-class:: classref-section-separator -Emitted when a physics body exits, reporting which shapes were overlapping. +---- -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_Area2D_SpaceOverride: +.. rst-class:: classref-enumeration + +enum **SpaceOverride**: :ref:`🔗` + .. _class_Area2D_constant_SPACE_OVERRIDE_DISABLED: +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_DISABLED** = ``0`` + +This area does not affect gravity/damping. + .. _class_Area2D_constant_SPACE_OVERRIDE_COMBINE: +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_COMBINE** = ``1`` + +This area adds its gravity/damping values to whatever has been calculated so far (in :ref:`priority` order). + .. _class_Area2D_constant_SPACE_OVERRIDE_COMBINE_REPLACE: +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_COMBINE_REPLACE** = ``2`` + +This area adds its gravity/damping values to whatever has been calculated so far (in :ref:`priority` order), ignoring any lower priority areas. + .. _class_Area2D_constant_SPACE_OVERRIDE_REPLACE: +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_REPLACE** = ``3`` + +This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas. + .. _class_Area2D_constant_SPACE_OVERRIDE_REPLACE_COMBINE: -enum **SpaceOverride**: +.. rst-class:: classref-enumeration-constant -- **SPACE_OVERRIDE_DISABLED** = **0** --- This area does not affect gravity/damping. +:ref:`SpaceOverride` **SPACE_OVERRIDE_REPLACE_COMBINE** = ``4`` -- **SPACE_OVERRIDE_COMBINE** = **1** --- This area adds its gravity/damping values to whatever has been calculated so far (in :ref:`priority` order). +This area replaces any gravity/damping calculated so far (in :ref:`priority` order), but keeps calculating the rest of the areas. -- **SPACE_OVERRIDE_COMBINE_REPLACE** = **2** --- This area adds its gravity/damping values to whatever has been calculated so far (in :ref:`priority` order), ignoring any lower priority areas. +.. rst-class:: classref-section-separator -- **SPACE_OVERRIDE_REPLACE** = **3** --- This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas. +---- -- **SPACE_OVERRIDE_REPLACE_COMBINE** = **4** --- This area replaces any gravity/damping calculated so far (in :ref:`priority` order), but keeps calculating the rest of the areas. +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_Area2D_property_angular_damp: -- :ref:`float` **angular_damp** +.. rst-class:: classref-property + +:ref:`float` **angular_damp** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_angular_damp**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_angular_damp**\ (\ ) + +The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. + +See :ref:`ProjectSettings.physics/2d/default_angular_damp` for more details about damping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area2D_property_angular_damp_space_override: + +.. rst-class:: classref-property + +:ref:`SpaceOverride` **angular_damp_space_override** = ``0`` :ref:`🔗` -+-----------+-------------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------------+ -| *Setter* | set_angular_damp(value) | -+-----------+-------------------------+ -| *Getter* | get_angular_damp() | -+-----------+-------------------------+ +.. rst-class:: classref-property-setget -The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. Values range from ``0`` (no damping) to ``1`` (full damping). +- |void| **set_angular_damp_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) +- :ref:`SpaceOverride` **get_angular_damp_space_override_mode**\ (\ ) + +Override mode for angular damping calculations within this area. + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_property_audio_bus_name: -- :ref:`StringName` **audio_bus_name** +.. rst-class:: classref-property + +:ref:`StringName` **audio_bus_name** = ``&"Master"`` :ref:`🔗` -+-----------+---------------------------+ -| *Default* | ``@"Master"`` | -+-----------+---------------------------+ -| *Setter* | set_audio_bus_name(value) | -+-----------+---------------------------+ -| *Getter* | get_audio_bus_name() | -+-----------+---------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_audio_bus_name**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_audio_bus_name**\ (\ ) The name of the area's audio bus. +.. rst-class:: classref-item-separator + ---- .. _class_Area2D_property_audio_bus_override: -- :ref:`bool` **audio_bus_override** +.. rst-class:: classref-property -+-----------+-------------------------------+ -| *Default* | ``false`` | -+-----------+-------------------------------+ -| *Setter* | set_audio_bus_override(value) | -+-----------+-------------------------------+ -| *Getter* | is_overriding_audio_bus() | -+-----------+-------------------------------+ +:ref:`bool` **audio_bus_override** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_audio_bus_override**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_overriding_audio_bus**\ (\ ) If ``true``, the area's audio bus overrides the default audio bus. +.. rst-class:: classref-item-separator + ---- -.. _class_Area2D_property_collision_layer: +.. _class_Area2D_property_gravity: + +.. rst-class:: classref-property -- :ref:`int` **collision_layer** +:ref:`float` **gravity** = ``980.0`` :ref:`🔗` -+-----------+----------------------------+ -| *Default* | ``1`` | -+-----------+----------------------------+ -| *Setter* | set_collision_layer(value) | -+-----------+----------------------------+ -| *Getter* | get_collision_layer() | -+-----------+----------------------------+ +.. rst-class:: classref-property-setget -The area's physics layer(s). Collidable objects can exist in any of 32 different layers. A contact is detected if object A is in any of the layers that object B scans, or object B is in any layers that object A scans. See also :ref:`collision_mask`. +- |void| **set_gravity**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_gravity**\ (\ ) + +The area's gravity intensity (in pixels per second squared). This value multiplies the gravity direction. This is useful to alter the force of gravity without altering its direction. + +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_property_collision_mask: +.. _class_Area2D_property_gravity_direction: + +.. rst-class:: classref-property + +:ref:`Vector2` **gravity_direction** = ``Vector2(0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`int` **collision_mask** +- |void| **set_gravity_direction**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_gravity_direction**\ (\ ) -+-----------+---------------------------+ -| *Default* | ``1`` | -+-----------+---------------------------+ -| *Setter* | set_collision_mask(value) | -+-----------+---------------------------+ -| *Getter* | get_collision_mask() | -+-----------+---------------------------+ +The area's gravity vector (not normalized). -The physics layers this area scans to determine collision detection. +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_property_gravity: +.. _class_Area2D_property_gravity_point: + +.. rst-class:: classref-property + +:ref:`bool` **gravity_point** = ``false`` :ref:`🔗` -- :ref:`float` **gravity** +.. rst-class:: classref-property-setget -+-----------+--------------------+ -| *Default* | ``98.0`` | -+-----------+--------------------+ -| *Setter* | set_gravity(value) | -+-----------+--------------------+ -| *Getter* | get_gravity() | -+-----------+--------------------+ +- |void| **set_gravity_is_point**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_gravity_a_point**\ (\ ) -The area's gravity intensity (ranges from -1024 to 1024). This value multiplies the gravity vector. This is useful to alter the force of gravity without altering its direction. +If ``true``, gravity is calculated from a point (set via :ref:`gravity_point_center`). See also :ref:`gravity_space_override`. + +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_property_gravity_distance_scale: +.. _class_Area2D_property_gravity_point_center: + +.. rst-class:: classref-property + +:ref:`Vector2` **gravity_point_center** = ``Vector2(0, 1)`` :ref:`🔗` -- :ref:`float` **gravity_distance_scale** +.. rst-class:: classref-property-setget -+-----------+-----------------------------------+ -| *Default* | ``0.0`` | -+-----------+-----------------------------------+ -| *Setter* | set_gravity_distance_scale(value) | -+-----------+-----------------------------------+ -| *Getter* | get_gravity_distance_scale() | -+-----------+-----------------------------------+ +- |void| **set_gravity_point_center**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_gravity_point_center**\ (\ ) -The falloff factor for point gravity. The greater the value, the faster gravity decreases with distance. +If gravity is a point (see :ref:`gravity_point`), this will be the point of attraction. + +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_property_gravity_point: +.. _class_Area2D_property_gravity_point_unit_distance: + +.. rst-class:: classref-property + +:ref:`float` **gravity_point_unit_distance** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_gravity_point_unit_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_gravity_point_unit_distance**\ (\ ) -- :ref:`bool` **gravity_point** +The distance at which the gravity strength is equal to :ref:`gravity`. For example, on a planet 100 pixels in radius with a surface gravity of 4.0 px/s², set the :ref:`gravity` to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 pixels from the center the gravity will be 1.0 px/s² (twice the distance, 1/4th the gravity), at 50 pixels it will be 16.0 px/s² (half the distance, 4x the gravity), and so on. -+-----------+-----------------------------+ -| *Default* | ``false`` | -+-----------+-----------------------------+ -| *Setter* | set_gravity_is_point(value) | -+-----------+-----------------------------+ -| *Getter* | is_gravity_a_point() | -+-----------+-----------------------------+ +The above is true only when the unit distance is a positive number. When this is set to 0.0, the gravity will be constant regardless of distance. -If ``true``, gravity is calculated from a point (set via :ref:`gravity_vec`). See also :ref:`space_override`. +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_property_gravity_vec: +.. _class_Area2D_property_gravity_space_override: -- :ref:`Vector2` **gravity_vec** +.. rst-class:: classref-property -+-----------+---------------------------+ -| *Default* | ``Vector2( 0, 1 )`` | -+-----------+---------------------------+ -| *Setter* | set_gravity_vector(value) | -+-----------+---------------------------+ -| *Getter* | get_gravity_vector() | -+-----------+---------------------------+ +:ref:`SpaceOverride` **gravity_space_override** = ``0`` :ref:`🔗` -The area's gravity vector (not normalized). If gravity is a point (see :ref:`gravity_point`), this will be the point of attraction. +.. rst-class:: classref-property-setget + +- |void| **set_gravity_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) +- :ref:`SpaceOverride` **get_gravity_space_override_mode**\ (\ ) + +Override mode for gravity calculations within this area. + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_property_linear_damp: -- :ref:`float` **linear_damp** +.. rst-class:: classref-property + +:ref:`float` **linear_damp** = ``0.1`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``0.1`` | -+-----------+------------------------+ -| *Setter* | set_linear_damp(value) | -+-----------+------------------------+ -| *Getter* | get_linear_damp() | -+-----------+------------------------+ +- |void| **set_linear_damp**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_linear_damp**\ (\ ) -The rate at which objects stop moving in this area. Represents the linear velocity lost per second. Values range from ``0`` (no damping) to ``1`` (full damping). +The rate at which objects stop moving in this area. Represents the linear velocity lost per second. + +See :ref:`ProjectSettings.physics/2d/default_linear_damp` for more details about damping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area2D_property_linear_damp_space_override: + +.. rst-class:: classref-property + +:ref:`SpaceOverride` **linear_damp_space_override** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_linear_damp_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) +- :ref:`SpaceOverride` **get_linear_damp_space_override_mode**\ (\ ) + +Override mode for linear damping calculations within this area. + +.. rst-class:: classref-item-separator ---- .. _class_Area2D_property_monitorable: -- :ref:`bool` **monitorable** +.. rst-class:: classref-property + +:ref:`bool` **monitorable** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``true`` | -+-----------+------------------------+ -| *Setter* | set_monitorable(value) | -+-----------+------------------------+ -| *Getter* | is_monitorable() | -+-----------+------------------------+ +- |void| **set_monitorable**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_monitorable**\ (\ ) If ``true``, other monitoring areas can detect this area. +.. rst-class:: classref-item-separator + ---- .. _class_Area2D_property_monitoring: -- :ref:`bool` **monitoring** +.. rst-class:: classref-property + +:ref:`bool` **monitoring** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------+ -| *Default* | ``true`` | -+-----------+-----------------------+ -| *Setter* | set_monitoring(value) | -+-----------+-----------------------+ -| *Getter* | is_monitoring() | -+-----------+-----------------------+ +- |void| **set_monitoring**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_monitoring**\ (\ ) If ``true``, the area detects bodies or areas entering and exiting it. +.. rst-class:: classref-item-separator + ---- .. _class_Area2D_property_priority: -- :ref:`float` **priority** +.. rst-class:: classref-property -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_priority(value) | -+-----------+---------------------+ -| *Getter* | get_priority() | -+-----------+---------------------+ +:ref:`int` **priority** = ``0`` :ref:`🔗` -The area's priority. Higher priority areas are processed first. +.. rst-class:: classref-property-setget ----- +- |void| **set_priority**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_priority**\ (\ ) -.. _class_Area2D_property_space_override: +The area's priority. Higher priority areas are processed first. The :ref:`World2D`'s physics is always processed last, after all areas. -- :ref:`SpaceOverride` **space_override** +.. rst-class:: classref-section-separator -+-----------+--------------------------------+ -| *Default* | ``0`` | -+-----------+--------------------------------+ -| *Setter* | set_space_override_mode(value) | -+-----------+--------------------------------+ -| *Getter* | get_space_override_mode() | -+-----------+--------------------------------+ +---- -Override mode for gravity and damping calculations within this area. See :ref:`SpaceOverride` for possible values. +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_Area2D_method_get_collision_layer_bit: - -- :ref:`bool` **get_collision_layer_bit** **(** :ref:`int` bit **)** const +.. _class_Area2D_method_get_overlapping_areas: -Returns an individual bit on the layer mask. Describes whether other areas will collide with this one on the given layer. +.. rst-class:: classref-method ----- +:ref:`Array`\[:ref:`Area2D`\] **get_overlapping_areas**\ (\ ) |const| :ref:`🔗` -.. _class_Area2D_method_get_collision_mask_bit: +Returns a list of intersecting **Area2D**\ s. The overlapping area's :ref:`CollisionObject2D.collision_layer` must be part of this area's :ref:`CollisionObject2D.collision_mask` in order to be detected. -- :ref:`bool` **get_collision_mask_bit** **(** :ref:`int` bit **)** const +For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. -Returns an individual bit on the collision mask. Describes whether this area will collide with others on the given layer. +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_method_get_overlapping_areas: +.. _class_Area2D_method_get_overlapping_bodies: -- :ref:`Array` **get_overlapping_areas** **(** **)** const +.. rst-class:: classref-method -Returns a list of intersecting ``Area2D``\ s. For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. +:ref:`Array`\[:ref:`Node2D`\] **get_overlapping_bodies**\ (\ ) |const| :ref:`🔗` ----- - -.. _class_Area2D_method_get_overlapping_bodies: +Returns a list of intersecting :ref:`PhysicsBody2D`\ s and :ref:`TileMap`\ s. The overlapping body's :ref:`CollisionObject2D.collision_layer` must be part of this area's :ref:`CollisionObject2D.collision_mask` in order to be detected. -- :ref:`Array` **get_overlapping_bodies** **(** **)** const +For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. -Returns a list of intersecting :ref:`PhysicsBody2D`\ s. For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_method_overlaps_area: +.. _class_Area2D_method_has_overlapping_areas: + +.. rst-class:: classref-method -- :ref:`bool` **overlaps_area** **(** :ref:`Node` area **)** const +:ref:`bool` **has_overlapping_areas**\ (\ ) |const| :ref:`🔗` -If ``true``, the given area overlaps the Area2D. +Returns ``true`` if intersecting any **Area2D**\ s, otherwise returns ``false``. The overlapping area's :ref:`CollisionObject2D.collision_layer` must be part of this area's :ref:`CollisionObject2D.collision_mask` in order to be detected. -**Note:** The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead. +For performance reasons (collisions are all processed at the same time) the list of overlapping areas is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. + +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_method_overlaps_body: +.. _class_Area2D_method_has_overlapping_bodies: -- :ref:`bool` **overlaps_body** **(** :ref:`Node` body **)** const +.. rst-class:: classref-method -If ``true``, the given physics body overlaps the Area2D. +:ref:`bool` **has_overlapping_bodies**\ (\ ) |const| :ref:`🔗` -**Note:** The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead. +Returns ``true`` if intersecting any :ref:`PhysicsBody2D`\ s or :ref:`TileMap`\ s, otherwise returns ``false``. The overlapping body's :ref:`CollisionObject2D.collision_layer` must be part of this area's :ref:`CollisionObject2D.collision_mask` in order to be detected. -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +For performance reasons (collisions are all processed at the same time) the list of overlapping bodies is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. + +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_method_set_collision_layer_bit: +.. _class_Area2D_method_overlaps_area: + +.. rst-class:: classref-method + +:ref:`bool` **overlaps_area**\ (\ area\: :ref:`Node`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given **Area2D** intersects or overlaps this **Area2D**, ``false`` otherwise. -- void **set_collision_layer_bit** **(** :ref:`int` bit, :ref:`bool` value **)** +\ **Note:** The result of this test is not immediate after moving objects. For performance, the list of overlaps is updated once per frame and before the physics step. Consider using signals instead. -Set/clear individual bits on the layer mask. This makes getting an area in/out of only one layer easier. +.. rst-class:: classref-item-separator ---- -.. _class_Area2D_method_set_collision_mask_bit: +.. _class_Area2D_method_overlaps_body: + +.. rst-class:: classref-method + +:ref:`bool` **overlaps_body**\ (\ body\: :ref:`Node`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given physics body intersects or overlaps this **Area2D**, ``false`` otherwise. -- void **set_collision_mask_bit** **(** :ref:`int` bit, :ref:`bool` value **)** +\ **Note:** The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead. -Set/clear individual bits on the collision mask. This makes selecting the areas scanned easier. +The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance. While TileMaps are not physics bodies themselves, they register their tiles with collision shapes as a virtual physics body. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_area3d.rst b/classes/class_area3d.rst new file mode 100644 index 00000000000..93590202c88 --- /dev/null +++ b/classes/class_area3d.rst @@ -0,0 +1,804 @@ +:github_url: hide + +.. meta:: + :keywords: trigger + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Area3D.xml. + +.. _class_Area3D: + +Area3D +====== + +**Inherits:** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +A region of 3D space that detects other :ref:`CollisionObject3D`\ s entering or exiting it. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**Area3D** is a region of 3D space defined by one or multiple :ref:`CollisionShape3D` or :ref:`CollisionPolygon3D` child nodes. It detects when other :ref:`CollisionObject3D`\ s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it). + +This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. + +\ **Note:** Areas and bodies created with :ref:`PhysicsServer3D` might not interact as expected with **Area3D**\ s, and might not emit signals or track objects correctly. + +\ **Warning:** Using a :ref:`ConcavePolygonShape3D` inside a :ref:`CollisionShape3D` child of this node (created e.g. by using the **Create Trimesh Collision Sibling** option in the **Mesh** menu that appears when selecting a :ref:`MeshInstance3D` node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple :ref:`ConvexPolygonShape3D`\ s or primitive shapes like :ref:`BoxShape3D`, or in some cases it may be replaceable by a :ref:`CollisionPolygon3D`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Area2D <../tutorials/physics/using_area_2d>` + +- `3D Platformer Demo `__ + +- `GUI in 3D Viewport Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`angular_damp` | ``0.1`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`SpaceOverride` | :ref:`angular_damp_space_override` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`StringName` | :ref:`audio_bus_name` | ``&"Master"`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`audio_bus_override` | ``false`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`gravity` | ``9.8`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector3` | :ref:`gravity_direction` | ``Vector3(0, -1, 0)`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`gravity_point` | ``false`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector3` | :ref:`gravity_point_center` | ``Vector3(0, -1, 0)`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`gravity_point_unit_distance` | ``0.0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`SpaceOverride` | :ref:`gravity_space_override` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`linear_damp` | ``0.1`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`SpaceOverride` | :ref:`linear_damp_space_override` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`monitorable` | ``true`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`monitoring` | ``true`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`priority` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`reverb_bus_amount` | ``0.0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`reverb_bus_enabled` | ``false`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`StringName` | :ref:`reverb_bus_name` | ``&"Master"`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`reverb_bus_uniformity` | ``0.0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`wind_attenuation_factor` | ``0.0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`wind_force_magnitude` | ``0.0`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + | :ref:`NodePath` | :ref:`wind_source_path` | ``NodePath("")`` | + +-------------------------------------------------+---------------------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Area3D`\] | :ref:`get_overlapping_areas`\ (\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Node3D`\] | :ref:`get_overlapping_bodies`\ (\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_overlapping_areas`\ (\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_overlapping_bodies`\ (\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`overlaps_area`\ (\ area\: :ref:`Node`\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`overlaps_body`\ (\ body\: :ref:`Node`\ ) |const| | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_Area3D_signal_area_entered: + +.. rst-class:: classref-signal + +**area_entered**\ (\ area\: :ref:`Area3D`\ ) :ref:`🔗` + +Emitted when the received ``area`` enters this area. Requires :ref:`monitoring` to be set to ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_signal_area_exited: + +.. rst-class:: classref-signal + +**area_exited**\ (\ area\: :ref:`Area3D`\ ) :ref:`🔗` + +Emitted when the received ``area`` exits this area. Requires :ref:`monitoring` to be set to ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_signal_area_shape_entered: + +.. rst-class:: classref-signal + +**area_shape_entered**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area3D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`Shape3D` of the received ``area`` enters a shape of this area. Requires :ref:`monitoring` to be set to ``true``. + +\ ``local_shape_index`` and ``area_shape_index`` contain indices of the interacting shapes from this area and the other area, respectively. ``area_rid`` contains the :ref:`RID` of the other area. These values can be used with the :ref:`PhysicsServer3D`. + +\ **Example:** Get the :ref:`CollisionShape3D` node from the shape index: + + +.. tabs:: + + .. code-tab:: gdscript + + var other_shape_owner = area.shape_find_owner(area_shape_index) + var other_shape_node = area.shape_owner_get_owner(other_shape_owner) + + var local_shape_owner = shape_find_owner(local_shape_index) + var local_shape_node = shape_owner_get_owner(local_shape_owner) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_signal_area_shape_exited: + +.. rst-class:: classref-signal + +**area_shape_exited**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area3D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`Shape3D` of the received ``area`` exits a shape of this area. Requires :ref:`monitoring` to be set to ``true``. + +See also :ref:`area_shape_entered`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_signal_body_entered: + +.. rst-class:: classref-signal + +**body_entered**\ (\ body\: :ref:`Node3D`\ ) :ref:`🔗` + +Emitted when the received ``body`` enters this area. ``body`` can be a :ref:`PhysicsBody3D` or a :ref:`GridMap`. :ref:`GridMap`\ s are detected if their :ref:`MeshLibrary` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_signal_body_exited: + +.. rst-class:: classref-signal + +**body_exited**\ (\ body\: :ref:`Node3D`\ ) :ref:`🔗` + +Emitted when the received ``body`` exits this area. ``body`` can be a :ref:`PhysicsBody3D` or a :ref:`GridMap`. :ref:`GridMap`\ s are detected if their :ref:`MeshLibrary` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_signal_body_shape_entered: + +.. rst-class:: classref-signal + +**body_shape_entered**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node3D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`Shape3D` of the received ``body`` enters a shape of this area. ``body`` can be a :ref:`PhysicsBody3D` or a :ref:`GridMap`. :ref:`GridMap`\ s are detected if their :ref:`MeshLibrary` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. + +\ ``local_shape_index`` and ``body_shape_index`` contain indices of the interacting shapes from this area and the interacting body, respectively. ``body_rid`` contains the :ref:`RID` of the body. These values can be used with the :ref:`PhysicsServer3D`. + +\ **Example:** Get the :ref:`CollisionShape3D` node from the shape index: + + +.. tabs:: + + .. code-tab:: gdscript + + var body_shape_owner = body.shape_find_owner(body_shape_index) + var body_shape_node = body.shape_owner_get_owner(body_shape_owner) + + var local_shape_owner = shape_find_owner(local_shape_index) + var local_shape_node = shape_owner_get_owner(local_shape_owner) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_signal_body_shape_exited: + +.. rst-class:: classref-signal + +**body_shape_exited**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node3D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`Shape3D` of the received ``body`` exits a shape of this area. ``body`` can be a :ref:`PhysicsBody3D` or a :ref:`GridMap`. :ref:`GridMap`\ s are detected if their :ref:`MeshLibrary` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. + +See also :ref:`body_shape_entered`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_Area3D_SpaceOverride: + +.. rst-class:: classref-enumeration + +enum **SpaceOverride**: :ref:`🔗` + +.. _class_Area3D_constant_SPACE_OVERRIDE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_DISABLED** = ``0`` + +This area does not affect gravity/damping. + +.. _class_Area3D_constant_SPACE_OVERRIDE_COMBINE: + +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_COMBINE** = ``1`` + +This area adds its gravity/damping values to whatever has been calculated so far (in :ref:`priority` order). + +.. _class_Area3D_constant_SPACE_OVERRIDE_COMBINE_REPLACE: + +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_COMBINE_REPLACE** = ``2`` + +This area adds its gravity/damping values to whatever has been calculated so far (in :ref:`priority` order), ignoring any lower priority areas. + +.. _class_Area3D_constant_SPACE_OVERRIDE_REPLACE: + +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_REPLACE** = ``3`` + +This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas. + +.. _class_Area3D_constant_SPACE_OVERRIDE_REPLACE_COMBINE: + +.. rst-class:: classref-enumeration-constant + +:ref:`SpaceOverride` **SPACE_OVERRIDE_REPLACE_COMBINE** = ``4`` + +This area replaces any gravity/damping calculated so far (in :ref:`priority` order), but keeps calculating the rest of the areas. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_Area3D_property_angular_damp: + +.. rst-class:: classref-property + +:ref:`float` **angular_damp** = ``0.1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_angular_damp**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_angular_damp**\ (\ ) + +The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. + +See :ref:`ProjectSettings.physics/3d/default_angular_damp` for more details about damping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_angular_damp_space_override: + +.. rst-class:: classref-property + +:ref:`SpaceOverride` **angular_damp_space_override** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_angular_damp_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) +- :ref:`SpaceOverride` **get_angular_damp_space_override_mode**\ (\ ) + +Override mode for angular damping calculations within this area. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_audio_bus_name: + +.. rst-class:: classref-property + +:ref:`StringName` **audio_bus_name** = ``&"Master"`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_audio_bus_name**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_audio_bus_name**\ (\ ) + +The name of the area's audio bus. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_audio_bus_override: + +.. rst-class:: classref-property + +:ref:`bool` **audio_bus_override** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_audio_bus_override**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_overriding_audio_bus**\ (\ ) + +If ``true``, the area's audio bus overrides the default audio bus. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_gravity: + +.. rst-class:: classref-property + +:ref:`float` **gravity** = ``9.8`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_gravity**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_gravity**\ (\ ) + +The area's gravity intensity (in meters per second squared). This value multiplies the gravity direction. This is useful to alter the force of gravity without altering its direction. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_gravity_direction: + +.. rst-class:: classref-property + +:ref:`Vector3` **gravity_direction** = ``Vector3(0, -1, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_gravity_direction**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_gravity_direction**\ (\ ) + +The area's gravity vector (not normalized). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_gravity_point: + +.. rst-class:: classref-property + +:ref:`bool` **gravity_point** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_gravity_is_point**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_gravity_a_point**\ (\ ) + +If ``true``, gravity is calculated from a point (set via :ref:`gravity_point_center`). See also :ref:`gravity_space_override`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_gravity_point_center: + +.. rst-class:: classref-property + +:ref:`Vector3` **gravity_point_center** = ``Vector3(0, -1, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_gravity_point_center**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_gravity_point_center**\ (\ ) + +If gravity is a point (see :ref:`gravity_point`), this will be the point of attraction. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_gravity_point_unit_distance: + +.. rst-class:: classref-property + +:ref:`float` **gravity_point_unit_distance** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_gravity_point_unit_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_gravity_point_unit_distance**\ (\ ) + +The distance at which the gravity strength is equal to :ref:`gravity`. For example, on a planet 100 meters in radius with a surface gravity of 4.0 m/s², set the :ref:`gravity` to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 meters from the center the gravity will be 1.0 m/s² (twice the distance, 1/4th the gravity), at 50 meters it will be 16.0 m/s² (half the distance, 4x the gravity), and so on. + +The above is true only when the unit distance is a positive number. When this is set to 0.0, the gravity will be constant regardless of distance. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_gravity_space_override: + +.. rst-class:: classref-property + +:ref:`SpaceOverride` **gravity_space_override** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_gravity_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) +- :ref:`SpaceOverride` **get_gravity_space_override_mode**\ (\ ) + +Override mode for gravity calculations within this area. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_linear_damp: + +.. rst-class:: classref-property + +:ref:`float` **linear_damp** = ``0.1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_linear_damp**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_linear_damp**\ (\ ) + +The rate at which objects stop moving in this area. Represents the linear velocity lost per second. + +See :ref:`ProjectSettings.physics/3d/default_linear_damp` for more details about damping. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_linear_damp_space_override: + +.. rst-class:: classref-property + +:ref:`SpaceOverride` **linear_damp_space_override** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_linear_damp_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) +- :ref:`SpaceOverride` **get_linear_damp_space_override_mode**\ (\ ) + +Override mode for linear damping calculations within this area. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_monitorable: + +.. rst-class:: classref-property + +:ref:`bool` **monitorable** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_monitorable**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_monitorable**\ (\ ) + +If ``true``, other monitoring areas can detect this area. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_monitoring: + +.. rst-class:: classref-property + +:ref:`bool` **monitoring** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_monitoring**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_monitoring**\ (\ ) + +If ``true``, the area detects bodies or areas entering and exiting it. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_priority: + +.. rst-class:: classref-property + +:ref:`int` **priority** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_priority**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_priority**\ (\ ) + +The area's priority. Higher priority areas are processed first. The :ref:`World3D`'s physics is always processed last, after all areas. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_reverb_bus_amount: + +.. rst-class:: classref-property + +:ref:`float` **reverb_bus_amount** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_reverb_amount**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_reverb_amount**\ (\ ) + +The degree to which this area applies reverb to its associated audio. Ranges from ``0`` to ``1`` with ``0.1`` precision. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_reverb_bus_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **reverb_bus_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_reverb_bus**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_using_reverb_bus**\ (\ ) + +If ``true``, the area applies reverb to its associated audio. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_reverb_bus_name: + +.. rst-class:: classref-property + +:ref:`StringName` **reverb_bus_name** = ``&"Master"`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_reverb_bus_name**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_reverb_bus_name**\ (\ ) + +The name of the reverb bus to use for this area's associated audio. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_reverb_bus_uniformity: + +.. rst-class:: classref-property + +:ref:`float` **reverb_bus_uniformity** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_reverb_uniformity**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_reverb_uniformity**\ (\ ) + +The degree to which this area's reverb is a uniform effect. Ranges from ``0`` to ``1`` with ``0.1`` precision. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_wind_attenuation_factor: + +.. rst-class:: classref-property + +:ref:`float` **wind_attenuation_factor** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_wind_attenuation_factor**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_wind_attenuation_factor**\ (\ ) + +The exponential rate at which wind force decreases with distance from its origin. + +\ **Note:** This wind force only applies to :ref:`SoftBody3D` nodes. Other physics bodies are currently not affected by wind. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_wind_force_magnitude: + +.. rst-class:: classref-property + +:ref:`float` **wind_force_magnitude** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_wind_force_magnitude**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_wind_force_magnitude**\ (\ ) + +The magnitude of area-specific wind force. + +\ **Note:** This wind force only applies to :ref:`SoftBody3D` nodes. Other physics bodies are currently not affected by wind. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_property_wind_source_path: + +.. rst-class:: classref-property + +:ref:`NodePath` **wind_source_path** = ``NodePath("")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_wind_source_path**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_wind_source_path**\ (\ ) + +The :ref:`Node3D` which is used to specify the direction and origin of an area-specific wind force. The direction is opposite to the z-axis of the :ref:`Node3D`'s local transform, and its origin is the origin of the :ref:`Node3D`'s local transform. + +\ **Note:** This wind force only applies to :ref:`SoftBody3D` nodes. Other physics bodies are currently not affected by wind. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_Area3D_method_get_overlapping_areas: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Area3D`\] **get_overlapping_areas**\ (\ ) |const| :ref:`🔗` + +Returns a list of intersecting **Area3D**\ s. The overlapping area's :ref:`CollisionObject3D.collision_layer` must be part of this area's :ref:`CollisionObject3D.collision_mask` in order to be detected. + +For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_method_get_overlapping_bodies: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Node3D`\] **get_overlapping_bodies**\ (\ ) |const| :ref:`🔗` + +Returns a list of intersecting :ref:`PhysicsBody3D`\ s and :ref:`GridMap`\ s. The overlapping body's :ref:`CollisionObject3D.collision_layer` must be part of this area's :ref:`CollisionObject3D.collision_mask` in order to be detected. + +For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_method_has_overlapping_areas: + +.. rst-class:: classref-method + +:ref:`bool` **has_overlapping_areas**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if intersecting any **Area3D**\ s, otherwise returns ``false``. The overlapping area's :ref:`CollisionObject3D.collision_layer` must be part of this area's :ref:`CollisionObject3D.collision_mask` in order to be detected. + +For performance reasons (collisions are all processed at the same time) the list of overlapping areas is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_method_has_overlapping_bodies: + +.. rst-class:: classref-method + +:ref:`bool` **has_overlapping_bodies**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if intersecting any :ref:`PhysicsBody3D`\ s or :ref:`GridMap`\ s, otherwise returns ``false``. The overlapping body's :ref:`CollisionObject3D.collision_layer` must be part of this area's :ref:`CollisionObject3D.collision_mask` in order to be detected. + +For performance reasons (collisions are all processed at the same time) the list of overlapping bodies is modified once during the physics step, not immediately after objects are moved. Consider using signals instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_method_overlaps_area: + +.. rst-class:: classref-method + +:ref:`bool` **overlaps_area**\ (\ area\: :ref:`Node`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given **Area3D** intersects or overlaps this **Area3D**, ``false`` otherwise. + +\ **Note:** The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Area3D_method_overlaps_body: + +.. rst-class:: classref-method + +:ref:`bool` **overlaps_body**\ (\ body\: :ref:`Node`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given physics body intersects or overlaps this **Area3D**, ``false`` otherwise. + +\ **Note:** The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead. + +The ``body`` argument can either be a :ref:`PhysicsBody3D` or a :ref:`GridMap` instance. While GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_array.rst b/classes/class_array.rst index 8b8e4e23010..de270991850 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -1,454 +1,1571 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Array.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Array.xml. .. _class_Array: Array ===== -Generic array datatype. +A built-in data structure that holds a sequence of elements. + +.. rst-class:: classref-introduction-group Description ----------- -Generic array which can contain several elements of any type, accessible by a numerical index starting at 0. Negative indices can be used to count from the back, like in Python (-1 is the last element, -2 the second to last, etc.). +An array data structure that can contain a sequence of elements of any :ref:`Variant` type by default. Values can optionally be constrained to a specific type by creating a *typed array*. Elements are accessed by a numerical index starting at ``0``. Negative indices are used to count from the back (``-1`` is the last element, ``-2`` is the second to last, etc.). -**Example:** -:: +.. tabs:: - var array = ["One", 2, 3, "Four"] - print(array[0]) # One. - print(array[2]) # 3. - print(array[-1]) # Four. - array[2] = "Three" - print(array[-2]) # Three. + .. code-tab:: gdscript -Arrays can be concatenated using the ``+`` operator: + var array = ["First", 2, 3, "Last"] + print(array[0]) # Prints "First" + print(array[2]) # Prints 3 + print(array[-1]) # Prints "Last" -:: + array[1] = "Second" + print(array[1]) # Prints "Second" + print(array[-3]) # Prints "Second" - var array1 = ["One", 2] - var array2 = [3, "Four"] - print(array1 + array2) # ["One", 2, 3, "Four"] + # This typed array can only contain integers. + # Attempting to add any other type will result in an error. + var typed_array: Array[int] = [1, 2, 3] + + .. code-tab:: csharp + + Godot.Collections.Array array = ["First", 2, 3, "Last"]; + GD.Print(array[0]); // Prints "First" + GD.Print(array[2]); // Prints 3 + GD.Print(array[^1]); // Prints "Last" + + array[1] = "Second"; + GD.Print(array[1]); // Prints "Second" + GD.Print(array[^3]); // Prints "Second" + + // This typed array can only contain integers. + // Attempting to add any other type will result in an error. + Godot.Collections.Array typedArray = [1, 2, 3]; + + + +\ **Note:** Arrays are always passed by **reference**. To get a copy of an array that can be modified independently of the original array, use :ref:`duplicate()`. + +\ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. + +\ **Differences between packed arrays, typed arrays, and untyped arrays:** Packed arrays are generally faster to iterate on and modify compared to a typed array of the same type (e.g. :ref:`PackedInt64Array` versus ``Array[int]``). Also, packed arrays consume less memory. As a downside, packed arrays are less flexible as they don't offer as many convenience methods such as :ref:`map()`. Typed arrays are in turn faster to iterate on and modify than untyped arrays. + +.. note:: + + There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. -Arrays are always passed by reference. +.. rst-class:: classref-reftable-group + +Constructors +------------ + +.. table:: + :widths: auto + + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ base\: :ref:`Array`, type\: :ref:`int`, class_name\: :ref:`StringName`, script\: :ref:`Variant`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedByteArray`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedColorArray`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedFloat32Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedFloat64Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedInt32Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedInt64Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedStringArray`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedVector2Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedVector3Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedVector4Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedColorArray` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedVector3Array` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedVector2Array` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedStringArray` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedFloat64Array` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedFloat32Array` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedInt64Array` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedInt32Array` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedByteArray` from **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`append` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`back` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`bsearch` **(** :ref:`Variant` value, :ref:`bool` before=true **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`bsearch_custom` **(** :ref:`Variant` value, :ref:`Object` obj, :ref:`String` func, :ref:`bool` before=true **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`count` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`duplicate` **(** :ref:`bool` deep=false **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`empty` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`erase` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`find` **(** :ref:`Variant` what, :ref:`int` from=0 **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`find_last` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`front` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`hash` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`insert` **(** :ref:`int` position, :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`invert` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`max` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`min` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`pop_back` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`pop_front` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`push_back` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`push_front` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove` **(** :ref:`int` position **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`resize` **(** :ref:`int` size **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`rfind` **(** :ref:`Variant` what, :ref:`int` from=-1 **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shuffle` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`size` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`slice` **(** :ref:`int` begin, :ref:`int` end, :ref:`int` step=1, :ref:`bool` deep=false **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`sort` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`sort_custom` **(** :ref:`Object` obj, :ref:`String` func **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`all`\ (\ method\: :ref:`Callable`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`any`\ (\ method\: :ref:`Callable`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`append`\ (\ value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`append_array`\ (\ array\: :ref:`Array`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`assign`\ (\ array\: :ref:`Array`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`back`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`bsearch`\ (\ value\: :ref:`Variant`, before\: :ref:`bool` = true\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`bsearch_custom`\ (\ value\: :ref:`Variant`, func\: :ref:`Callable`, before\: :ref:`bool` = true\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear`\ (\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`count`\ (\ value\: :ref:`Variant`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`duplicate`\ (\ deep\: :ref:`bool` = false\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`duplicate_deep`\ (\ deep_subresources_mode\: :ref:`int` = 1\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`erase`\ (\ value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fill`\ (\ value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`filter`\ (\ method\: :ref:`Callable`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`find`\ (\ what\: :ref:`Variant`, from\: :ref:`int` = 0\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`find_custom`\ (\ method\: :ref:`Callable`, from\: :ref:`int` = 0\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`front`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_typed_builtin`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_typed_class_name`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get_typed_script`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has`\ (\ value\: :ref:`Variant`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`hash`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`insert`\ (\ position\: :ref:`int`, value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_empty`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_read_only`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_same_typed`\ (\ array\: :ref:`Array`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_typed`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`make_read_only`\ (\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`map`\ (\ method\: :ref:`Callable`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`max`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`min`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`pick_random`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`pop_at`\ (\ position\: :ref:`int`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`pop_back`\ (\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`pop_front`\ (\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`push_back`\ (\ value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`push_front`\ (\ value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`reduce`\ (\ method\: :ref:`Callable`, accum\: :ref:`Variant` = null\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_at`\ (\ position\: :ref:`int`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`resize`\ (\ size\: :ref:`int`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`reverse`\ (\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rfind`\ (\ what\: :ref:`Variant`, from\: :ref:`int` = -1\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rfind_custom`\ (\ method\: :ref:`Callable`, from\: :ref:`int` = -1\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set`\ (\ index\: :ref:`int`, value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shuffle`\ (\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`size`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`slice`\ (\ begin\: :ref:`int`, end\: :ref:`int` = 2147483647, step\: :ref:`int` = 1, deep\: :ref:`bool` = false\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`sort`\ (\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`sort_custom`\ (\ func\: :ref:`Callable`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Operators +--------- + +.. table:: + :widths: auto + + +-------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator !=`\ (\ right\: :ref:`Array`\ ) | + +-------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`operator +`\ (\ right\: :ref:`Array`\ ) | + +-------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator \<`\ (\ right\: :ref:`Array`\ ) | + +-------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator \<=`\ (\ right\: :ref:`Array`\ ) | + +-------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator ==`\ (\ right\: :ref:`Array`\ ) | + +-------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator >`\ (\ right\: :ref:`Array`\ ) | + +-------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator >=`\ (\ right\: :ref:`Array`\ ) | + +-------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`operator []`\ (\ index\: :ref:`int`\ ) | + +-------------------------------+----------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator -Method Descriptions -------------------- +---- -.. _class_Array_method_Array: +.. rst-class:: classref-descriptions-group -- :ref:`Array` **Array** **(** :ref:`PackedColorArray` from **)** +Constructor Descriptions +------------------------ -Constructs an array from a :ref:`PackedColorArray`. +.. _class_Array_constructor_Array: + +.. rst-class:: classref-constructor + +:ref:`Array` **Array**\ (\ ) :ref:`🔗` + +Constructs an empty **Array**. + +.. rst-class:: classref-item-separator ---- -- :ref:`Array` **Array** **(** :ref:`PackedVector3Array` from **)** +.. rst-class:: classref-constructor -Constructs an array from a :ref:`PackedVector3Array`. +:ref:`Array` **Array**\ (\ base\: :ref:`Array`, type\: :ref:`int`, class_name\: :ref:`StringName`, script\: :ref:`Variant`\ ) + +Creates a typed array from the ``base`` array. A typed array can only contain elements of the given type, or that inherit from the given class, as described by this constructor's parameters: + +- ``type`` is the built-in :ref:`Variant` type, as one the :ref:`Variant.Type` constants. + +- ``class_name`` is the built-in class name (see :ref:`Object.get_class()`). + +- ``script`` is the associated script. It must be a :ref:`Script` instance or ``null``. + +If ``type`` is not :ref:`@GlobalScope.TYPE_OBJECT`, ``class_name`` must be an empty :ref:`StringName` and ``script`` must be ``null``. + +:: + + class_name Sword + extends Node + + class Stats: + pass + + func _ready(): + var a = Array([], TYPE_INT, "", null) # Array[int] + var b = Array([], TYPE_OBJECT, "Node", null) # Array[Node] + var c = Array([], TYPE_OBJECT, "Node", Sword) # Array[Sword] + var d = Array([], TYPE_OBJECT, "RefCounted", Stats) # Array[Stats] + +The ``base`` array's elements are converted when necessary. If this is not possible or ``base`` is already typed, this constructor fails and returns an empty **Array**. + +In GDScript, this constructor is usually not necessary, as it is possible to create a typed array through static typing: + +:: + + var numbers: Array[float] = [] + var children: Array[Node] = [$Node, $Sprite2D, $RigidBody3D] + + var integers: Array[int] = [0.2, 4.5, -2.0] + print(integers) # Prints [0, 4, -2] + +.. rst-class:: classref-item-separator ---- -- :ref:`Array` **Array** **(** :ref:`PackedVector2Array` from **)** +.. rst-class:: classref-constructor -Constructs an array from a :ref:`PackedVector2Array`. +:ref:`Array` **Array**\ (\ from\: :ref:`Array`\ ) + +Returns the same array as ``from``. If you need a copy of the array, use :ref:`duplicate()`. + +.. rst-class:: classref-item-separator ---- -- :ref:`Array` **Array** **(** :ref:`PackedStringArray` from **)** +.. rst-class:: classref-constructor -Constructs an array from a :ref:`PackedStringArray`. +:ref:`Array` **Array**\ (\ from\: :ref:`PackedByteArray`\ ) + +Constructs an array from a :ref:`PackedByteArray`. + +.. rst-class:: classref-item-separator ---- -- :ref:`Array` **Array** **(** :ref:`PackedFloat64Array` from **)** +.. rst-class:: classref-constructor -Constructs an array from a :ref:`PackedFloat64Array`. +:ref:`Array` **Array**\ (\ from\: :ref:`PackedColorArray`\ ) + +Constructs an array from a :ref:`PackedColorArray`. + +.. rst-class:: classref-item-separator ---- -- :ref:`Array` **Array** **(** :ref:`PackedFloat32Array` from **)** +.. rst-class:: classref-constructor + +:ref:`Array` **Array**\ (\ from\: :ref:`PackedFloat32Array`\ ) Constructs an array from a :ref:`PackedFloat32Array`. +.. rst-class:: classref-item-separator + ---- -- :ref:`Array` **Array** **(** :ref:`PackedInt64Array` from **)** +.. rst-class:: classref-constructor -Constructs an array from a :ref:`PackedInt64Array`. +:ref:`Array` **Array**\ (\ from\: :ref:`PackedFloat64Array`\ ) + +Constructs an array from a :ref:`PackedFloat64Array`. + +.. rst-class:: classref-item-separator ---- -- :ref:`Array` **Array** **(** :ref:`PackedInt32Array` from **)** +.. rst-class:: classref-constructor + +:ref:`Array` **Array**\ (\ from\: :ref:`PackedInt32Array`\ ) Constructs an array from a :ref:`PackedInt32Array`. +.. rst-class:: classref-item-separator + ---- -- :ref:`Array` **Array** **(** :ref:`PackedByteArray` from **)** +.. rst-class:: classref-constructor -Constructs an array from a :ref:`PackedByteArray`. +:ref:`Array` **Array**\ (\ from\: :ref:`PackedInt64Array`\ ) + +Constructs an array from a :ref:`PackedInt64Array`. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`Array` **Array**\ (\ from\: :ref:`PackedStringArray`\ ) + +Constructs an array from a :ref:`PackedStringArray`. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`Array` **Array**\ (\ from\: :ref:`PackedVector2Array`\ ) + +Constructs an array from a :ref:`PackedVector2Array`. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`Array` **Array**\ (\ from\: :ref:`PackedVector3Array`\ ) + +Constructs an array from a :ref:`PackedVector3Array`. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`Array` **Array**\ (\ from\: :ref:`PackedVector4Array`\ ) + +Constructs an array from a :ref:`PackedVector4Array`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_Array_method_all: + +.. rst-class:: classref-method + +:ref:`bool` **all**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` + +Calls the given :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *all* elements in the array. If the :ref:`Callable` returns ``false`` for one array element or more, this method returns ``false``. + +The ``method`` should take one :ref:`Variant` parameter (the current array element) and return a :ref:`bool`. + + +.. tabs:: + + .. code-tab:: gdscript + + func greater_than_5(number): + return number > 5 + + func _ready(): + print([6, 10, 6].all(greater_than_5)) # Prints true (3/3 elements evaluate to true). + print([4, 10, 4].all(greater_than_5)) # Prints false (1/3 elements evaluate to true). + print([4, 4, 4].all(greater_than_5)) # Prints false (0/3 elements evaluate to true). + print([].all(greater_than_5)) # Prints true (0/0 elements evaluate to true). + + # Same as the first line above, but using a lambda function. + print([6, 10, 6].all(func(element): return element > 5)) # Prints true + + .. code-tab:: csharp + + private static bool GreaterThan5(int number) + { + return number > 5; + } + + public override void _Ready() + { + // Prints True (3/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(GreaterThan5)); + // Prints False (1/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 10, 4 }.All(GreaterThan5)); + // Prints False (0/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 4, 4 }.All(GreaterThan5)); + // Prints True (0/0 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { }.All(GreaterThan5)); + + // Same as the first line above, but using a lambda function. + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(element => element > 5)); // Prints True + } + + + +See also :ref:`any()`, :ref:`filter()`, :ref:`map()` and :ref:`reduce()`. + +\ **Note:** Unlike relying on the size of an array returned by :ref:`filter()`, this method will return as early as possible to improve performance (especially with large arrays). + +\ **Note:** For an empty array, this method `always `__ returns ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_any: + +.. rst-class:: classref-method + +:ref:`bool` **any**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` + +Calls the given :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *one or more* elements in the array. If the :ref:`Callable` returns ``false`` for all elements in the array, this method returns ``false``. + +The ``method`` should take one :ref:`Variant` parameter (the current array element) and return a :ref:`bool`. + +:: + + func greater_than_5(number): + return number > 5 + + func _ready(): + print([6, 10, 6].any(greater_than_5)) # Prints true (3 elements evaluate to true). + print([4, 10, 4].any(greater_than_5)) # Prints true (1 elements evaluate to true). + print([4, 4, 4].any(greater_than_5)) # Prints false (0 elements evaluate to true). + print([].any(greater_than_5)) # Prints false (0 elements evaluate to true). + + # Same as the first line above, but using a lambda function. + print([6, 10, 6].any(func(number): return number > 5)) # Prints true + +See also :ref:`all()`, :ref:`filter()`, :ref:`map()` and :ref:`reduce()`. + +\ **Note:** Unlike relying on the size of an array returned by :ref:`filter()`, this method will return as early as possible to improve performance (especially with large arrays). + +\ **Note:** For an empty array, this method always returns ``false``. + +.. rst-class:: classref-item-separator ---- .. _class_Array_method_append: -- void **append** **(** :ref:`Variant` value **)** +.. rst-class:: classref-method + +|void| **append**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` + +Appends ``value`` at the end of the array (alias of :ref:`push_back()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_append_array: + +.. rst-class:: classref-method + +|void| **append_array**\ (\ array\: :ref:`Array`\ ) :ref:`🔗` + +Appends another ``array`` at the end of this array. + +:: + + var numbers = [1, 2, 3] + var extra = [4, 5, 6] + numbers.append_array(extra) + print(numbers) # Prints [1, 2, 3, 4, 5, 6] + +.. rst-class:: classref-item-separator -Appends an element at the end of the array (alias of :ref:`push_back`). +---- + +.. _class_Array_method_assign: + +.. rst-class:: classref-method + +|void| **assign**\ (\ array\: :ref:`Array`\ ) :ref:`🔗` + +Assigns elements of another ``array`` into the array. Resizes the array to match ``array``. Performs type conversions if the array is typed. + +.. rst-class:: classref-item-separator ---- .. _class_Array_method_back: -- :ref:`Variant` **back** **(** **)** +.. rst-class:: classref-method + +:ref:`Variant` **back**\ (\ ) |const| :ref:`🔗` + +Returns the last element of the array. If the array is empty, fails and returns ``null``. See also :ref:`front()`. -Returns the last element of the array, or ``null`` if the array is empty. +\ **Note:** Unlike with the ``[]`` operator (``array[-1]``), an error is generated without stopping project execution. + +.. rst-class:: classref-item-separator ---- .. _class_Array_method_bsearch: -- :ref:`int` **bsearch** **(** :ref:`Variant` value, :ref:`bool` before=true **)** +.. rst-class:: classref-method + +:ref:`int` **bsearch**\ (\ value\: :ref:`Variant`, before\: :ref:`bool` = true\ ) |const| :ref:`🔗` + +Returns the index of ``value`` in the sorted array. If it cannot be found, returns where ``value`` should be inserted to keep the array sorted. The algorithm used is `binary search `__. + +If ``before`` is ``true`` (as by default), the returned index comes before all existing elements equal to ``value`` in the array. + +:: + + var numbers = [2, 4, 8, 10] + var idx = numbers.bsearch(7) + + numbers.insert(idx, 7) + print(numbers) # Prints [2, 4, 7, 8, 10] -Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array. + var fruits = ["Apple", "Lemon", "Lemon", "Orange"] + print(fruits.bsearch("Lemon", true)) # Prints 1, points at the first "Lemon". + print(fruits.bsearch("Lemon", false)) # Prints 3, points at "Orange". -**Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** Calling :ref:`bsearch()` on an *unsorted* array will result in unexpected behavior. Use :ref:`sort()` before calling this method. + +.. rst-class:: classref-item-separator ---- .. _class_Array_method_bsearch_custom: -- :ref:`int` **bsearch_custom** **(** :ref:`Variant` value, :ref:`Object` obj, :ref:`String` func, :ref:`bool` before=true **)** +.. rst-class:: classref-method + +:ref:`int` **bsearch_custom**\ (\ value\: :ref:`Variant`, func\: :ref:`Callable`, before\: :ref:`bool` = true\ ) |const| :ref:`🔗` + +Returns the index of ``value`` in the sorted array. If it cannot be found, returns where ``value`` should be inserted to keep the array sorted (using ``func`` for the comparisons). The algorithm used is `binary search `__. + +Similar to :ref:`sort_custom()`, ``func`` is called as many times as necessary, receiving one array element and ``value`` as arguments. The function should return ``true`` if the array element should be *behind* ``value``, otherwise it should return ``false``. + +If ``before`` is ``true`` (as by default), the returned index comes before all existing elements equal to ``value`` in the array. + +:: + + func sort_by_amount(a, b): + if a[1] < b[1]: + return true + return false -Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search and a custom comparison method. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array. The custom method receives two arguments (an element from the array and the value searched for) and must return ``true`` if the first argument is less than the second, and return ``false`` otherwise. + func _ready(): + var my_items = [["Tomato", 2], ["Kiwi", 5], ["Rice", 9]] -**Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. + var apple = ["Apple", 5] + # "Apple" is inserted before "Kiwi". + my_items.insert(my_items.bsearch_custom(apple, sort_by_amount, true), apple) + + var banana = ["Banana", 5] + # "Banana" is inserted after "Kiwi". + my_items.insert(my_items.bsearch_custom(banana, sort_by_amount, false), banana) + + # Prints [["Tomato", 2], ["Apple", 5], ["Kiwi", 5], ["Banana", 5], ["Rice", 9]] + print(my_items) + +\ **Note:** Calling :ref:`bsearch_custom()` on an *unsorted* array will result in unexpected behavior. Use :ref:`sort_custom()` with ``func`` before calling this method. + +.. rst-class:: classref-item-separator ---- .. _class_Array_method_clear: -- void **clear** **(** **)** +.. rst-class:: classref-method -Clears the array. This is equivalent to using :ref:`resize` with a size of ``0``. +|void| **clear**\ (\ ) :ref:`🔗` + +Removes all elements from the array. This is equivalent to using :ref:`resize()` with a size of ``0``. + +.. rst-class:: classref-item-separator ---- .. _class_Array_method_count: -- :ref:`int` **count** **(** :ref:`Variant` value **)** +.. rst-class:: classref-method + +:ref:`int` **count**\ (\ value\: :ref:`Variant`\ ) |const| :ref:`🔗` Returns the number of times an element is in the array. +To count how many elements in an array satisfy a condition, see :ref:`reduce()`. + +.. rst-class:: classref-item-separator + ---- .. _class_Array_method_duplicate: -- :ref:`Array` **duplicate** **(** :ref:`bool` deep=false **)** +.. rst-class:: classref-method + +:ref:`Array` **duplicate**\ (\ deep\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns a new copy of the array. + +By default, a **shallow** copy is returned: all nested **Array**, :ref:`Dictionary`, and :ref:`Resource` elements are shared with the original array. Modifying any of those in one array will also affect them in the other. -Returns a copy of the array. +If ``deep`` is ``true``, a **deep** copy is returned: all nested arrays and dictionaries are also duplicated (recursively). Any :ref:`Resource` is still shared with the original array, though. -If ``deep`` is ``true``, a deep copy is performed: all nested arrays and dictionaries are duplicated and will not be shared with the original array. If ``false``, a shallow copy is made and references to the original nested arrays and dictionaries are kept, so that modifying a sub-array or dictionary in the copy will also impact those referenced in the source array. +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_empty: +.. _class_Array_method_duplicate_deep: -- :ref:`bool` **empty** **(** **)** +.. rst-class:: classref-method -Returns ``true`` if the array is empty. +:ref:`Array` **duplicate_deep**\ (\ deep_subresources_mode\: :ref:`int` = 1\ ) |const| :ref:`🔗` + +Duplicates this array, deeply, like :ref:`duplicate()`\ ``(true)``, with extra control over how subresources are handled. + +\ ``deep_subresources_mode`` must be one of the values from :ref:`DeepDuplicateMode`. By default, only internal resources will be duplicated (recursively). + +.. rst-class:: classref-item-separator ---- .. _class_Array_method_erase: -- void **erase** **(** :ref:`Variant` value **)** +.. rst-class:: classref-method -Removes the first occurrence of a value from the array. +|void| **erase**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` ----- +Finds and removes the first occurrence of ``value`` from the array. If ``value`` does not exist in the array, nothing happens. To remove an element by index, use :ref:`remove_at()` instead. -.. _class_Array_method_find: +\ **Note:** This method shifts every element's index after the removed ``value`` back, which may have a noticeable performance cost, especially on larger arrays. -- :ref:`int` **find** **(** :ref:`Variant` what, :ref:`int` from=0 **)** +\ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. -Searches the array for a value and returns its index or -1 if not found. Optionally, the initial search index can be passed. +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_find_last: +.. _class_Array_method_fill: -- :ref:`int` **find_last** **(** :ref:`Variant` value **)** +.. rst-class:: classref-method -Searches the array in reverse order for a value and returns its index or -1 if not found. +|void| **fill**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` ----- +Assigns the given ``value`` to all elements in the array. -.. _class_Array_method_front: +This method can often be combined with :ref:`resize()` to create an array with a given size and initialized elements: + + +.. tabs:: + + .. code-tab:: gdscript + + var array = [] + array.resize(5) + array.fill(2) + print(array) # Prints [2, 2, 2, 2, 2] + + .. code-tab:: csharp -- :ref:`Variant` **front** **(** **)** + Godot.Collections.Array array = []; + array.Resize(5); + array.Fill(2); + GD.Print(array); // Prints [2, 2, 2, 2, 2] -Returns the first element of the array, or ``null`` if the array is empty. + + +\ **Note:** If ``value`` is a :ref:`Variant` passed by reference (:ref:`Object`-derived, **Array**, :ref:`Dictionary`, etc.), the array will be filled with references to the same ``value``, which are not duplicates. + +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_has: +.. _class_Array_method_filter: -- :ref:`bool` **has** **(** :ref:`Variant` value **)** +.. rst-class:: classref-method -Returns ``true`` if the array contains the given value. +:ref:`Array` **filter**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` + +Calls the given :ref:`Callable` on each element in the array and returns a new, filtered **Array**. + +The ``method`` receives one of the array elements as an argument, and should return ``true`` to add the element to the filtered array, or ``false`` to exclude it. :: - ["inside", 7].has("inside") == true - ["inside", 7].has("outside") == false - ["inside", 7].has(7) == true - ["inside", 7].has("7") == false + func is_even(number): + return number % 2 == 0 ----- + func _ready(): + print([1, 4, 5, 8].filter(is_even)) # Prints [4, 8] -.. _class_Array_method_hash: + # Same as above, but using a lambda function. + print([1, 4, 5, 8].filter(func(number): return number % 2 == 0)) -- :ref:`int` **hash** **(** **)** +See also :ref:`any()`, :ref:`all()`, :ref:`map()` and :ref:`reduce()`. -Returns a hashed integer value representing the array contents. +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_insert: +.. _class_Array_method_find: -- void **insert** **(** :ref:`int` position, :ref:`Variant` value **)** +.. rst-class:: classref-method -Inserts a new element at a given position in the array. The position must be valid, or at the end of the array (``pos == size()``). +:ref:`int` **find**\ (\ what\: :ref:`Variant`, from\: :ref:`int` = 0\ ) |const| :ref:`🔗` ----- +Returns the index of the **first** occurrence of ``what`` in this array, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the end of the array. -.. _class_Array_method_invert: +\ **Note:** If you just want to know whether the array contains ``what``, use :ref:`has()` (``Contains`` in C#). In GDScript, you may also use the ``in`` operator. -- void **invert** **(** **)** +\ **Note:** For performance reasons, the search is affected by ``what``'s :ref:`Variant.Type`. For example, ``7`` (:ref:`int`) and ``7.0`` (:ref:`float`) are not considered equal for this method. -Reverses the order of the elements in the array. +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_max: +.. _class_Array_method_find_custom: -- :ref:`Variant` **max** **(** **)** +.. rst-class:: classref-method -Returns the maximum value contained in the array if all elements are of comparable types. If the elements can't be compared, ``null`` is returned. +:ref:`int` **find_custom**\ (\ method\: :ref:`Callable`, from\: :ref:`int` = 0\ ) |const| :ref:`🔗` ----- +Returns the index of the **first** element in the array that causes ``method`` to return ``true``, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the end of the array. -.. _class_Array_method_min: +\ ``method`` is a callable that takes an element of the array, and returns a :ref:`bool`. -- :ref:`Variant` **min** **(** **)** +\ **Note:** If you just want to know whether the array contains *anything* that satisfies ``method``, use :ref:`any()`. -Returns the minimum value contained in the array if all elements are of comparable types. If the elements can't be compared, ``null`` is returned. ----- +.. tabs:: -.. _class_Array_method_pop_back: + .. code-tab:: gdscript -- :ref:`Variant` **pop_back** **(** **)** + func is_even(number): + return number % 2 == 0 -Removes and returns the last element of the array. Returns ``null`` if the array is empty. + func _ready(): + print([1, 3, 4, 7].find_custom(is_even.bind())) # Prints 2 + + + +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_pop_front: +.. _class_Array_method_front: + +.. rst-class:: classref-method + +:ref:`Variant` **front**\ (\ ) |const| :ref:`🔗` + +Returns the first element of the array. If the array is empty, fails and returns ``null``. See also :ref:`back()`. -- :ref:`Variant` **pop_front** **(** **)** +\ **Note:** Unlike with the ``[]`` operator (``array[0]``), an error is generated without stopping project execution. -Removes and returns the first element of the array. Returns ``null`` if the array is empty. +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_push_back: +.. _class_Array_method_get: + +.. rst-class:: classref-method + +:ref:`Variant` **get**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the element at the given ``index`` in the array. If ``index`` out-of-bounds or negative, this method fails and returns ``null``. -- void **push_back** **(** :ref:`Variant` value **)** +This method is similar (but not identical) to the ``[]`` operator. Most notably, when this method fails, it doesn't pause project execution if run from the editor. -Appends an element at the end of the array. +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_push_front: +.. _class_Array_method_get_typed_builtin: + +.. rst-class:: classref-method -- void **push_front** **(** :ref:`Variant` value **)** +:ref:`int` **get_typed_builtin**\ (\ ) |const| :ref:`🔗` -Adds an element at the beginning of the array. +Returns the built-in :ref:`Variant` type of the typed array as a :ref:`Variant.Type` constant. If the array is not typed, returns :ref:`@GlobalScope.TYPE_NIL`. See also :ref:`is_typed()`. + +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_remove: +.. _class_Array_method_get_typed_class_name: + +.. rst-class:: classref-method -- void **remove** **(** :ref:`int` position **)** +:ref:`StringName` **get_typed_class_name**\ (\ ) |const| :ref:`🔗` -Removes an element from the array by index. +Returns the **built-in** class name of the typed array, if the built-in :ref:`Variant` type :ref:`@GlobalScope.TYPE_OBJECT`. Otherwise, returns an empty :ref:`StringName`. See also :ref:`is_typed()` and :ref:`Object.get_class()`. + +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_resize: +.. _class_Array_method_get_typed_script: + +.. rst-class:: classref-method + +:ref:`Variant` **get_typed_script**\ (\ ) |const| :ref:`🔗` -- void **resize** **(** :ref:`int` size **)** +Returns the :ref:`Script` instance associated with this typed array, or ``null`` if it does not exist. See also :ref:`is_typed()`. -Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are ``null``. +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_rfind: +.. _class_Array_method_has: -- :ref:`int` **rfind** **(** :ref:`Variant` what, :ref:`int` from=-1 **)** +.. rst-class:: classref-method -Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +:ref:`bool` **has**\ (\ value\: :ref:`Variant`\ ) |const| :ref:`🔗` ----- +Returns ``true`` if the array contains the given ``value``. -.. _class_Array_method_shuffle: -- void **shuffle** **(** **)** +.. tabs:: -Shuffles the array such that the items will have a random order. This method uses the global random number generator common to methods such as :ref:`@GDScript.randi`. Call :ref:`@GDScript.randomize` to ensure that a new seed will be used each time if you want non-reproducible shuffling. + .. code-tab:: gdscript ----- + print(["inside", 7].has("inside")) # Prints true + print(["inside", 7].has("outside")) # Prints false + print(["inside", 7].has(7)) # Prints true + print(["inside", 7].has("7")) # Prints false -.. _class_Array_method_size: + .. code-tab:: csharp -- :ref:`int` **size** **(** **)** + Godot.Collections.Array arr = ["inside", 7]; + // By C# convention, this method is renamed to `Contains`. + GD.Print(arr.Contains("inside")); // Prints True + GD.Print(arr.Contains("outside")); // Prints False + GD.Print(arr.Contains(7)); // Prints True + GD.Print(arr.Contains("7")); // Prints False -Returns the number of elements in the array. ----- -.. _class_Array_method_slice: +In GDScript, this is equivalent to the ``in`` operator: -- :ref:`Array` **slice** **(** :ref:`int` begin, :ref:`int` end, :ref:`int` step=1, :ref:`bool` deep=false **)** +:: + + if 4 in [2, 4, 6, 8]: + print("4 is here!") # Will be printed. -Duplicates the subset described in the function and returns it in an array, deeply copying the array if ``deep`` is ``true``. Lower and upper index are inclusive, with the ``step`` describing the change between indices while slicing. +\ **Note:** For performance reasons, the search is affected by the ``value``'s :ref:`Variant.Type`. For example, ``7`` (:ref:`int`) and ``7.0`` (:ref:`float`) are not considered equal for this method. + +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_sort: +.. _class_Array_method_hash: -- void **sort** **(** **)** +.. rst-class:: classref-method -Sorts the array. +:ref:`int` **hash**\ (\ ) |const| :ref:`🔗` -**Note:** Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example: +Returns a hashed 32-bit integer value representing the array and its contents. -:: +\ **Note:** Arrays with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the countrary, arrays with different hash values are guaranteed to be different. - var strings = ["string1", "string2", "string10", "string11"] - strings.sort() - print(strings) # Prints [string1, string10, string11, string2] +.. rst-class:: classref-item-separator ---- -.. _class_Array_method_sort_custom: +.. _class_Array_method_insert: -- void **sort_custom** **(** :ref:`Object` obj, :ref:`String` func **)** +.. rst-class:: classref-method -Sorts the array using a custom method. The arguments are an object that holds the method and the name of such method. The custom method receives two arguments (a pair of elements from the array) and must return either ``true`` or ``false``. +:ref:`int` **insert**\ (\ position\: :ref:`int`, value\: :ref:`Variant`\ ) :ref:`🔗` -**Note:** you cannot randomize the return value as the heapsort algorithm expects a deterministic result. Doing so will result in unexpected behavior. +Inserts a new element (``value``) at a given index (``position``) in the array. ``position`` should be between ``0`` and the array's :ref:`size()`. If negative, ``position`` is considered relative to the end of the array. -:: +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` constants if this method fails. + +\ **Note:** Every element's index after ``position`` needs to be shifted forward, which may have a noticeable performance cost, especially on larger arrays. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_is_empty: + +.. rst-class:: classref-method + +:ref:`bool` **is_empty**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the array is empty (``[]``). See also :ref:`size()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_is_read_only: + +.. rst-class:: classref-method + +:ref:`bool` **is_read_only**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the array is read-only. See :ref:`make_read_only()`. + +In GDScript, arrays are automatically read-only if declared with the ``const`` keyword. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_is_same_typed: + +.. rst-class:: classref-method + +:ref:`bool` **is_same_typed**\ (\ array\: :ref:`Array`\ ) |const| :ref:`🔗` + +Returns ``true`` if this array is typed the same as the given ``array``. See also :ref:`is_typed()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_is_typed: + +.. rst-class:: classref-method + +:ref:`bool` **is_typed**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the array is typed. Typed arrays can only contain elements of a specific type, as defined by the typed array constructor. The methods of a typed array are still expected to return a generic :ref:`Variant`. + +In GDScript, it is possible to define a typed array with static typing: + +:: + + var numbers: Array[float] = [0.2, 4.2, -2.0] + print(numbers.is_typed()) # Prints true + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_make_read_only: + +.. rst-class:: classref-method + +|void| **make_read_only**\ (\ ) :ref:`🔗` + +Makes the array read-only. The array's elements cannot be overridden with different values, and their order cannot change. Does not apply to nested elements, such as dictionaries. + +In GDScript, arrays are automatically read-only if declared with the ``const`` keyword. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_map: + +.. rst-class:: classref-method + +:ref:`Array` **map**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` + +Calls the given :ref:`Callable` for each element in the array and returns a new array filled with values returned by the ``method``. + +The ``method`` should take one :ref:`Variant` parameter (the current array element) and can return any :ref:`Variant`. + +:: + + func double(number): + return number * 2 + + func _ready(): + print([1, 2, 3].map(double)) # Prints [2, 4, 6] + + # Same as above, but using a lambda function. + print([1, 2, 3].map(func(element): return element * 2)) + +See also :ref:`filter()`, :ref:`reduce()`, :ref:`any()` and :ref:`all()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_max: + +.. rst-class:: classref-method + +:ref:`Variant` **max**\ (\ ) |const| :ref:`🔗` + +Returns the maximum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also :ref:`min()`. + +To find the maximum value using a custom comparator, you can use :ref:`reduce()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_min: + +.. rst-class:: classref-method + +:ref:`Variant` **min**\ (\ ) |const| :ref:`🔗` + +Returns the minimum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also :ref:`max()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_pick_random: + +.. rst-class:: classref-method + +:ref:`Variant` **pick_random**\ (\ ) |const| :ref:`🔗` + +Returns a random element from the array. Generates an error and returns ``null`` if the array is empty. + + +.. tabs:: + + .. code-tab:: gdscript + + # May print 1, 2, 3.25, or "Hi". + print([1, 2, 3.25, "Hi"].pick_random()) + + .. code-tab:: csharp + + Godot.Collections.Array array = [1, 2, 3.25f, "Hi"]; + GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi". + + + +\ **Note:** Like many similar functions in the engine (such as :ref:`@GlobalScope.randi()` or :ref:`shuffle()`), this method uses a common, global random seed. To get a predictable outcome from this method, see :ref:`@GlobalScope.seed()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_pop_at: + +.. rst-class:: classref-method + +:ref:`Variant` **pop_at**\ (\ position\: :ref:`int`\ ) :ref:`🔗` + +Removes and returns the element of the array at index ``position``. If negative, ``position`` is considered relative to the end of the array. Returns ``null`` if the array is empty. If ``position`` is out of bounds, an error message is also generated. + +\ **Note:** This method shifts every element's index after ``position`` back, which may have a noticeable performance cost, especially on larger arrays. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_pop_back: + +.. rst-class:: classref-method + +:ref:`Variant` **pop_back**\ (\ ) :ref:`🔗` + +Removes and returns the last element of the array. Returns ``null`` if the array is empty, without generating an error. See also :ref:`pop_front()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_pop_front: + +.. rst-class:: classref-method + +:ref:`Variant` **pop_front**\ (\ ) :ref:`🔗` + +Removes and returns the first element of the array. Returns ``null`` if the array is empty, without generating an error. See also :ref:`pop_back()`. + +\ **Note:** This method shifts every other element's index back, which may have a noticeable performance cost, especially on larger arrays. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_push_back: + +.. rst-class:: classref-method + +|void| **push_back**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` + +Appends an element at the end of the array. See also :ref:`push_front()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_push_front: + +.. rst-class:: classref-method + +|void| **push_front**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` + +Adds an element at the beginning of the array. See also :ref:`push_back()`. + +\ **Note:** This method shifts every other element's index forward, which may have a noticeable performance cost, especially on larger arrays. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_reduce: + +.. rst-class:: classref-method + +:ref:`Variant` **reduce**\ (\ method\: :ref:`Callable`, accum\: :ref:`Variant` = null\ ) |const| :ref:`🔗` + +Calls the given :ref:`Callable` for each element in array, accumulates the result in ``accum``, then returns it. + +The ``method`` takes two arguments: the current value of ``accum`` and the current array element. If ``accum`` is ``null`` (as by default), the iteration will start from the second element, with the first one used as initial value of ``accum``. + +:: + + func sum(accum, number): + return accum + number + + func _ready(): + print([1, 2, 3].reduce(sum, 0)) # Prints 6 + print([1, 2, 3].reduce(sum, 10)) # Prints 16 + + # Same as above, but using a lambda function. + print([1, 2, 3].reduce(func(accum, number): return accum + number, 10)) + +If :ref:`max()` is not desirable, this method may also be used to implement a custom comparator: + +:: + + func _ready(): + var arr = [Vector2i(5, 0), Vector2i(3, 4), Vector2i(1, 2)] + + var longest_vec = arr.reduce(func(max, vec): return vec if is_length_greater(vec, max) else max) + print(longest_vec) # Prints (3, 4) + + func is_length_greater(a, b): + return a.length() > b.length() + +This method can also be used to count how many elements in an array satisfy a certain condition, similar to :ref:`count()`: + +:: + + func is_even(number): + return number % 2 == 0 + + func _ready(): + var arr = [1, 2, 3, 4, 5] + # If the current element is even, increment count, otherwise leave count the same. + var even_count = arr.reduce(func(count, next): return count + 1 if is_even(next) else count, 0) + print(even_count) # Prints 2 + +See also :ref:`map()`, :ref:`filter()`, :ref:`any()`, and :ref:`all()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_remove_at: + +.. rst-class:: classref-method + +|void| **remove_at**\ (\ position\: :ref:`int`\ ) :ref:`🔗` + +Removes the element from the array at the given index (``position``). If the index is out of bounds, this method fails. If the index is negative, ``position`` is considered relative to the end of the array. + +If you need to return the removed element, use :ref:`pop_at()`. To remove an element by value, use :ref:`erase()` instead. + +\ **Note:** This method shifts every element's index after ``position`` back, which may have a noticeable performance cost, especially on larger arrays. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_resize: + +.. rst-class:: classref-method + +:ref:`int` **resize**\ (\ size\: :ref:`int`\ ) :ref:`🔗` + +Sets the array's number of elements to ``size``. If ``size`` is smaller than the array's current size, the elements at the end are removed. If ``size`` is greater, new default elements (usually ``null``) are added, depending on the array's type. + +Returns :ref:`@GlobalScope.OK` on success, or one of the following :ref:`Error` constants if this method fails: :ref:`@GlobalScope.ERR_LOCKED` if the array is read-only, :ref:`@GlobalScope.ERR_INVALID_PARAMETER` if the size is negative, or :ref:`@GlobalScope.ERR_OUT_OF_MEMORY` if allocations fail. Use :ref:`size()` to find the actual size of the array after resize. + +\ **Note:** Calling this method once and assigning the new values is faster than calling :ref:`append()` for every new element. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_reverse: + +.. rst-class:: classref-method + +|void| **reverse**\ (\ ) :ref:`🔗` + +Reverses the order of all elements in the array. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_rfind: + +.. rst-class:: classref-method + +:ref:`int` **rfind**\ (\ what\: :ref:`Variant`, from\: :ref:`int` = -1\ ) |const| :ref:`🔗` + +Returns the index of the **last** occurrence of ``what`` in this array, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the beginning of the array. This method is the reverse of :ref:`find()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_rfind_custom: + +.. rst-class:: classref-method + +:ref:`int` **rfind_custom**\ (\ method\: :ref:`Callable`, from\: :ref:`int` = -1\ ) |const| :ref:`🔗` + +Returns the index of the **last** element of the array that causes ``method`` to return ``true``, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the beginning of the array. This method is the reverse of :ref:`find_custom()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_set: + +.. rst-class:: classref-method + +|void| **set**\ (\ index\: :ref:`int`, value\: :ref:`Variant`\ ) :ref:`🔗` + +Sets the value of the element at the given ``index`` to the given ``value``. This will not change the size of the array, it only changes the value at an index already in the array. This is the same as using the ``[]`` operator (``array[index] = value``). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_shuffle: + +.. rst-class:: classref-method + +|void| **shuffle**\ (\ ) :ref:`🔗` + +Shuffles all elements of the array in a random order. + +\ **Note:** Like many similar functions in the engine (such as :ref:`@GlobalScope.randi()` or :ref:`pick_random()`), this method uses a common, global random seed. To get a predictable outcome from this method, see :ref:`@GlobalScope.seed()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_size: + +.. rst-class:: classref-method + +:ref:`int` **size**\ (\ ) |const| :ref:`🔗` + +Returns the number of elements in the array. Empty arrays (``[]``) always return ``0``. See also :ref:`is_empty()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_slice: + +.. rst-class:: classref-method + +:ref:`Array` **slice**\ (\ begin\: :ref:`int`, end\: :ref:`int` = 2147483647, step\: :ref:`int` = 1, deep\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns a new **Array** containing this array's elements, from index ``begin`` (inclusive) to ``end`` (exclusive), every ``step`` elements. + +If either ``begin`` or ``end`` are negative, their value is relative to the end of the array. + +If ``step`` is negative, this method iterates through the array in reverse, returning a slice ordered backwards. For this to work, ``begin`` must be greater than ``end``. + +If ``deep`` is ``true``, all nested **Array** and :ref:`Dictionary` elements in the slice are duplicated from the original, recursively. See also :ref:`duplicate()`. + +:: + + var letters = ["A", "B", "C", "D", "E", "F"] + + print(letters.slice(0, 2)) # Prints ["A", "B"] + print(letters.slice(2, -2)) # Prints ["C", "D"] + print(letters.slice(-2, 6)) # Prints ["E", "F"] + + print(letters.slice(0, 6, 2)) # Prints ["A", "C", "E"] + print(letters.slice(4, 1, -1)) # Prints ["E", "D", "C"] + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_sort: + +.. rst-class:: classref-method + +|void| **sort**\ (\ ) :ref:`🔗` + +Sorts the array in ascending order. The final order is dependent on the "less than" (``<``) comparison between elements. + + +.. tabs:: + + .. code-tab:: gdscript + + var numbers = [10, 5, 2.5, 8] + numbers.sort() + print(numbers) # Prints [2.5, 5, 8, 10] + + .. code-tab:: csharp + + Godot.Collections.Array numbers = [10, 5, 2.5, 8]; + numbers.Sort(); + GD.Print(numbers); // Prints [2.5, 5, 8, 10] + + + +\ **Note:** The sorting algorithm used is not `stable `__. This means that equivalent elements (such as ``2`` and ``2.0``) may have their order changed when calling :ref:`sort()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_sort_custom: + +.. rst-class:: classref-method + +|void| **sort_custom**\ (\ func\: :ref:`Callable`\ ) :ref:`🔗` + +Sorts the array using a custom :ref:`Callable`. + +\ ``func`` is called as many times as necessary, receiving two array elements as arguments. The function should return ``true`` if the first element should be moved *before* the second one, otherwise it should return ``false``. + +:: + + func sort_ascending(a, b): + if a[1] < b[1]: + return true + return false + + func _ready(): + var my_items = [["Tomato", 5], ["Apple", 9], ["Rice", 4]] + my_items.sort_custom(sort_ascending) + print(my_items) # Prints [["Rice", 4], ["Tomato", 5], ["Apple", 9]] + + # Sort descending, using a lambda function. + my_items.sort_custom(func(a, b): return a[1] > b[1]) + print(my_items) # Prints [["Apple", 9], ["Tomato", 5], ["Rice", 4]] + +It may also be necessary to use this method to sort strings by natural order, with :ref:`String.naturalnocasecmp_to()`, as in the following example: + +:: + + var files = ["newfile1", "newfile2", "newfile10", "newfile11"] + files.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0) + print(files) # Prints ["newfile1", "newfile2", "newfile10", "newfile11"] + +\ **Note:** In C#, this method is not supported. + +\ **Note:** The sorting algorithm used is not `stable `__. This means that values considered equal may have their order changed when calling this method. + +\ **Note:** You should not randomize the return value of ``func``, as the heapsort algorithm expects a consistent result. Randomizing the return value will result in unexpected behavior. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Operator Descriptions +--------------------- + +.. _class_Array_operator_neq_Array: + +.. rst-class:: classref-operator + +:ref:`bool` **operator !=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Returns ``true`` if the array's size or its elements are different than ``right``'s. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_operator_sum_Array: + +.. rst-class:: classref-operator + +:ref:`Array` **operator +**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Appends the ``right`` array to the left operand, creating a new **Array**. This is also known as an array concatenation. + + +.. tabs:: + + .. code-tab:: gdscript + + var array1 = ["One", 2] + var array2 = [3, "Four"] + print(array1 + array2) # Prints ["One", 2, 3, "Four"] + + .. code-tab:: csharp + + // Note that concatenation is not possible with C#'s native Array type. + Godot.Collections.Array array1 = ["One", 2]; + Godot.Collections.Array array2 = [3, "Four"]; + GD.Print(array1 + array2); // Prints ["One", 2, 3, "Four"] + + + +\ **Note:** For existing arrays, :ref:`append_array()` is much more efficient than concatenation and assignment with the ``+=`` operator. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_operator_lt_Array: + +.. rst-class:: classref-operator + +:ref:`bool` **operator <**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than ``right``'s, ``false`` if this element is greater. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is less than ``right``'s, otherwise returns ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_operator_lte_Array: + +.. rst-class:: classref-operator + +:ref:`bool` **operator <=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than ``right``'s, ``false`` if this element is greater. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is less or equal to ``right``'s, otherwise returns ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_operator_eq_Array: + +.. rst-class:: classref-operator + +:ref:`bool` **operator ==**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Compares the left operand **Array** against the ``right`` **Array**. Returns ``true`` if the sizes and contents of the arrays are equal, ``false`` otherwise. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_operator_gt_Array: + +.. rst-class:: classref-operator + +:ref:`bool` **operator >**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than ``right``'s, ``false`` if this element is less. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is greater than ``right``'s, otherwise returns ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_operator_gte_Array: + +.. rst-class:: classref-operator + +:ref:`bool` **operator >=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than ``right``'s, ``false`` if this element is less. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is greater or equal to ``right``'s, otherwise returns ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_operator_idx_int: + +.. rst-class:: classref-operator + +:ref:`Variant` **operator []**\ (\ index\: :ref:`int`\ ) :ref:`🔗` - class MyCustomSorter: - static func sort_ascending(a, b): - if a[0] < b[0]: - return true - return false - - var my_items = [[5, "Potato"], [9, "Rice"], [4, "Tomato"]] - my_items.sort_custom(MyCustomSorter, "sort_ascending") - print(my_items) # Prints [[4, Tomato], [5, Potato], [9, Rice]]. +Returns the :ref:`Variant` element at the specified ``index``. Arrays start at index 0. If ``index`` is greater or equal to ``0``, the element is fetched starting from the beginning of the array. If ``index`` is a negative value, the element is fetched starting from the end. Accessing an array out-of-bounds will cause a run-time error, pausing the project execution if run from the editor. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_arraymesh.rst b/classes/class_arraymesh.rst index ba732abb20b..afbadf7087c 100644 --- a/classes/class_arraymesh.rst +++ b/classes/class_arraymesh.rst @@ -1,365 +1,477 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ArrayMesh.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ArrayMesh.xml. .. _class_ArrayMesh: ArrayMesh ========= -**Inherits:** :ref:`Mesh` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Mesh` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` :ref:`Mesh` type that provides utility for constructing a surface from arrays. +.. rst-class:: classref-introduction-group + Description ----------- -The ``ArrayMesh`` is used to construct a :ref:`Mesh` by specifying the attributes as arrays. +The **ArrayMesh** is used to construct a :ref:`Mesh` by specifying the attributes as arrays. The most basic example is the creation of a single triangle: -:: + +.. tabs:: + + .. code-tab:: gdscript var vertices = PackedVector3Array() vertices.push_back(Vector3(0, 1, 0)) vertices.push_back(Vector3(1, 0, 0)) vertices.push_back(Vector3(0, 0, 1)) + # Initialize the ArrayMesh. var arr_mesh = ArrayMesh.new() var arrays = [] - arrays.resize(ArrayMesh.ARRAY_MAX) - arrays[ArrayMesh.ARRAY_VERTEX] = vertices + arrays.resize(Mesh.ARRAY_MAX) + arrays[Mesh.ARRAY_VERTEX] = vertices + # Create the Mesh. arr_mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, arrays) - var m = MeshInstance.new() + var m = MeshInstance3D.new() m.mesh = arr_mesh -The :ref:`MeshInstance` is ready to be added to the :ref:`SceneTree` to be shown. + .. code-tab:: csharp -Tutorials ---------- + Vector3[] vertices = + [ + new Vector3(0, 1, 0), + new Vector3(1, 0, 0), + new Vector3(0, 0, 1), + ]; -- :doc:`../tutorials/3d/procedural_geometry/arraymesh` + // Initialize the ArrayMesh. + var arrMesh = new ArrayMesh(); + Godot.Collections.Array arrays = []; + arrays.Resize((int)Mesh.ArrayType.Max); + arrays[(int)Mesh.ArrayType.Vertex] = vertices; -Properties ----------- + // Create the Mesh. + arrMesh.AddSurfaceFromArrays(Mesh.PrimitiveType.Triangles, arrays); + var m = new MeshInstance3D(); + m.Mesh = arrMesh; -+-------------------------------------------------+--------------------------------------------------------------------+------------------------------+ -| :ref:`BlendShapeMode` | :ref:`blend_shape_mode` | ``1`` | -+-------------------------------------------------+--------------------------------------------------------------------+------------------------------+ -| :ref:`AABB` | :ref:`custom_aabb` | ``AABB( 0, 0, 0, 0, 0, 0 )`` | -+-------------------------------------------------+--------------------------------------------------------------------+------------------------------+ -Methods -------- -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_blend_shape` **(** :ref:`StringName` name **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_surface_from_arrays` **(** :ref:`PrimitiveType` primitive, :ref:`Array` arrays, :ref:`Array` blend_shapes=[ ], :ref:`Dictionary` lods={ }, :ref:`int` compress_flags=31744 **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_blend_shapes` **(** **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_surfaces` **(** **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_blend_shape_count` **(** **)** const | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_blend_shape_name` **(** :ref:`int` index **)** const | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`lightmap_unwrap` **(** :ref:`Transform` transform, :ref:`float` texel_size **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`regen_normalmaps` **(** **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`surface_find_by_name` **(** :ref:`String` name **)** const | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`surface_get_array_index_len` **(** :ref:`int` surf_idx **)** const | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`surface_get_array_len` **(** :ref:`int` surf_idx **)** const | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`surface_get_format` **(** :ref:`int` surf_idx **)** const | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`surface_get_name` **(** :ref:`int` surf_idx **)** const | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PrimitiveType` | :ref:`surface_get_primitive_type` **(** :ref:`int` surf_idx **)** const | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`surface_set_name` **(** :ref:`int` surf_idx, :ref:`String` name **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`surface_update_region` **(** :ref:`int` surf_idx, :ref:`int` offset, :ref:`PackedByteArray` data **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +The :ref:`MeshInstance3D` is ready to be added to the :ref:`SceneTree` to be shown. + +See also :ref:`ImmediateMesh`, :ref:`MeshDataTool` and :ref:`SurfaceTool` for procedural geometry generation. -Enumerations ------------- +\ **Note:** Godot uses clockwise `winding order `__ for front faces of triangle primitive modes. -.. _enum_ArrayMesh_ArrayType: +.. rst-class:: classref-introduction-group -.. _class_ArrayMesh_constant_ARRAY_VERTEX: +Tutorials +--------- -.. _class_ArrayMesh_constant_ARRAY_NORMAL: +- :doc:`Procedural geometry using the ArrayMesh <../tutorials/3d/procedural_geometry/arraymesh>` -.. _class_ArrayMesh_constant_ARRAY_TANGENT: +.. rst-class:: classref-reftable-group -.. _class_ArrayMesh_constant_ARRAY_COLOR: +Properties +---------- -.. _class_ArrayMesh_constant_ARRAY_TEX_UV: +.. table:: + :widths: auto -.. _class_ArrayMesh_constant_ARRAY_TEX_UV2: + +-------------------------------------------------+--------------------------------------------------------------------+----------------------------+ + | :ref:`BlendShapeMode` | :ref:`blend_shape_mode` | ``1`` | + +-------------------------------------------------+--------------------------------------------------------------------+----------------------------+ + | :ref:`AABB` | :ref:`custom_aabb` | ``AABB(0, 0, 0, 0, 0, 0)`` | + +-------------------------------------------------+--------------------------------------------------------------------+----------------------------+ + | :ref:`ArrayMesh` | :ref:`shadow_mesh` | | + +-------------------------------------------------+--------------------------------------------------------------------+----------------------------+ -.. _class_ArrayMesh_constant_ARRAY_BONES: +.. rst-class:: classref-reftable-group -.. _class_ArrayMesh_constant_ARRAY_WEIGHTS: +Methods +------- -.. _class_ArrayMesh_constant_ARRAY_INDEX: +.. table:: + :widths: auto + + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_blend_shape`\ (\ name\: :ref:`StringName`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_surface_from_arrays`\ (\ primitive\: :ref:`PrimitiveType`, arrays\: :ref:`Array`, blend_shapes\: :ref:`Array`\[:ref:`Array`\] = [], lods\: :ref:`Dictionary` = {}, flags\: |bitfield|\[:ref:`ArrayFormat`\] = 0\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_blend_shapes`\ (\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_surfaces`\ (\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_blend_shape_count`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_blend_shape_name`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`lightmap_unwrap`\ (\ transform\: :ref:`Transform3D`, texel_size\: :ref:`float`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`regen_normal_maps`\ (\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_blend_shape_name`\ (\ index\: :ref:`int`, name\: :ref:`StringName`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`surface_find_by_name`\ (\ name\: :ref:`String`\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`surface_get_array_index_len`\ (\ surf_idx\: :ref:`int`\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`surface_get_array_len`\ (\ surf_idx\: :ref:`int`\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |bitfield|\[:ref:`ArrayFormat`\] | :ref:`surface_get_format`\ (\ surf_idx\: :ref:`int`\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`surface_get_name`\ (\ surf_idx\: :ref:`int`\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PrimitiveType` | :ref:`surface_get_primitive_type`\ (\ surf_idx\: :ref:`int`\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`surface_remove`\ (\ surf_idx\: :ref:`int`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`surface_set_name`\ (\ surf_idx\: :ref:`int`, name\: :ref:`String`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`surface_update_attribute_region`\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`surface_update_skin_region`\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`surface_update_vertex_region`\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator -.. _class_ArrayMesh_constant_ARRAY_MAX: +---- -enum **ArrayType**: +.. rst-class:: classref-descriptions-group -- **ARRAY_VERTEX** = **0** --- :ref:`PackedVector3Array`, :ref:`PackedVector2Array`, or :ref:`Array` of vertex positions. +Property Descriptions +--------------------- -- **ARRAY_NORMAL** = **1** --- :ref:`PackedVector3Array` of vertex normals. +.. _class_ArrayMesh_property_blend_shape_mode: -- **ARRAY_TANGENT** = **2** --- :ref:`PackedFloat32Array` of vertex tangents. Each element in groups of 4 floats, first 3 floats determine the tangent, and the last the binormal direction as -1 or 1. +.. rst-class:: classref-property -- **ARRAY_COLOR** = **3** --- :ref:`PackedColorArray` of vertex colors. +:ref:`BlendShapeMode` **blend_shape_mode** = ``1`` :ref:`🔗` -- **ARRAY_TEX_UV** = **4** --- :ref:`PackedVector2Array` for UV coordinates. +.. rst-class:: classref-property-setget -- **ARRAY_TEX_UV2** = **5** --- :ref:`PackedVector2Array` for second UV coordinates. +- |void| **set_blend_shape_mode**\ (\ value\: :ref:`BlendShapeMode`\ ) +- :ref:`BlendShapeMode` **get_blend_shape_mode**\ (\ ) -- **ARRAY_BONES** = **6** --- :ref:`PackedFloat32Array` or :ref:`PackedInt32Array` of bone indices. Each element in groups of 4 floats. +The blend shape mode. -- **ARRAY_WEIGHTS** = **7** --- :ref:`PackedFloat32Array` of bone weights. Each element in groups of 4 floats. +.. rst-class:: classref-item-separator -- **ARRAY_INDEX** = **8** --- :ref:`PackedInt32Array` of integers used as indices referencing vertices, colors, normals, tangents, and textures. All of those arrays must have the same number of elements as the vertex array. No index can be beyond the vertex array size. When this index array is present, it puts the function into "index mode," where the index selects the \*i\*'th vertex, normal, tangent, color, UV, etc. This means if you want to have different normals or colors along an edge, you have to duplicate the vertices. +---- -For triangles, the index array is interpreted as triples, referring to the vertices of each triangle. For lines, the index array is in pairs indicating the start and end of each line. +.. _class_ArrayMesh_property_custom_aabb: -- **ARRAY_MAX** = **9** --- Represents the size of the :ref:`ArrayType` enum. +.. rst-class:: classref-property ----- +:ref:`AABB` **custom_aabb** = ``AABB(0, 0, 0, 0, 0, 0)`` :ref:`🔗` -.. _enum_ArrayMesh_ArrayFormat: +.. rst-class:: classref-property-setget -.. _class_ArrayMesh_constant_ARRAY_FORMAT_VERTEX: +- |void| **set_custom_aabb**\ (\ value\: :ref:`AABB`\ ) +- :ref:`AABB` **get_custom_aabb**\ (\ ) -.. _class_ArrayMesh_constant_ARRAY_FORMAT_NORMAL: +Overrides the :ref:`AABB` with one defined by user for use with frustum culling. Especially useful to avoid unexpected culling when using a shader to offset vertices. -.. _class_ArrayMesh_constant_ARRAY_FORMAT_TANGENT: +.. rst-class:: classref-item-separator -.. _class_ArrayMesh_constant_ARRAY_FORMAT_COLOR: +---- -.. _class_ArrayMesh_constant_ARRAY_FORMAT_TEX_UV: +.. _class_ArrayMesh_property_shadow_mesh: -.. _class_ArrayMesh_constant_ARRAY_FORMAT_TEX_UV2: +.. rst-class:: classref-property -.. _class_ArrayMesh_constant_ARRAY_FORMAT_BONES: +:ref:`ArrayMesh` **shadow_mesh** :ref:`🔗` -.. _class_ArrayMesh_constant_ARRAY_FORMAT_WEIGHTS: +.. rst-class:: classref-property-setget -.. _class_ArrayMesh_constant_ARRAY_FORMAT_INDEX: +- |void| **set_shadow_mesh**\ (\ value\: :ref:`ArrayMesh`\ ) +- :ref:`ArrayMesh` **get_shadow_mesh**\ (\ ) -enum **ArrayFormat**: +An optional mesh which can be used for rendering shadows and the depth prepass. Can be used to increase performance by supplying a mesh with fused vertices and only vertex position data (without normals, UVs, colors, etc.). -- **ARRAY_FORMAT_VERTEX** = **1** --- Array format will include vertices (mandatory). +\ **Note:** This mesh must have exactly the same vertex positions as the source mesh (including the source mesh's LODs, if present). If vertex positions differ, then the mesh will not draw correctly. -- **ARRAY_FORMAT_NORMAL** = **2** --- Array format will include normals. +.. rst-class:: classref-section-separator -- **ARRAY_FORMAT_TANGENT** = **4** --- Array format will include tangents. +---- -- **ARRAY_FORMAT_COLOR** = **8** --- Array format will include a color array. +.. rst-class:: classref-descriptions-group -- **ARRAY_FORMAT_TEX_UV** = **16** --- Array format will include UVs. +Method Descriptions +------------------- -- **ARRAY_FORMAT_TEX_UV2** = **32** --- Array format will include another set of UVs. +.. _class_ArrayMesh_method_add_blend_shape: -- **ARRAY_FORMAT_BONES** = **64** --- Array format will include bone indices. +.. rst-class:: classref-method -- **ARRAY_FORMAT_WEIGHTS** = **128** --- Array format will include bone weights. +|void| **add_blend_shape**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` -- **ARRAY_FORMAT_INDEX** = **256** --- Index array will be used. +Adds name for a blend shape that will be added with :ref:`add_surface_from_arrays()`. Must be called before surface is added. -Constants ---------- +.. rst-class:: classref-item-separator -.. _class_ArrayMesh_constant_NO_INDEX_ARRAY: +---- -.. _class_ArrayMesh_constant_ARRAY_WEIGHTS_SIZE: +.. _class_ArrayMesh_method_add_surface_from_arrays: -- **NO_INDEX_ARRAY** = **-1** --- Default value used for index_array_len when no indices are present. +.. rst-class:: classref-method -- **ARRAY_WEIGHTS_SIZE** = **4** --- Amount of weights/bone indices per vertex (always 4). +|void| **add_surface_from_arrays**\ (\ primitive\: :ref:`PrimitiveType`, arrays\: :ref:`Array`, blend_shapes\: :ref:`Array`\[:ref:`Array`\] = [], lods\: :ref:`Dictionary` = {}, flags\: |bitfield|\[:ref:`ArrayFormat`\] = 0\ ) :ref:`🔗` -Property Descriptions ---------------------- +Creates a new surface. :ref:`Mesh.get_surface_count()` will become the ``surf_idx`` for this new surface. -.. _class_ArrayMesh_property_blend_shape_mode: +Surfaces are created to be rendered using a ``primitive``, which may be any of the values defined in :ref:`PrimitiveType`. -- :ref:`BlendShapeMode` **blend_shape_mode** +The ``arrays`` argument is an array of arrays. Each of the :ref:`Mesh.ARRAY_MAX` elements contains an array with some of the mesh data for this surface as described by the corresponding member of :ref:`ArrayType` or ``null`` if it is not used by the surface. For example, ``arrays[0]`` is the array of vertices. That first vertex sub-array is always required; the others are optional. Adding an index array puts this surface into "index mode" where the vertex and other arrays become the sources of data and the index array defines the vertex order. All sub-arrays must have the same length as the vertex array (or be an exact multiple of the vertex array's length, when multiple elements of a sub-array correspond to a single vertex) or be empty, except for :ref:`Mesh.ARRAY_INDEX` if it is used. -+-----------+-----------------------------+ -| *Default* | ``1`` | -+-----------+-----------------------------+ -| *Setter* | set_blend_shape_mode(value) | -+-----------+-----------------------------+ -| *Getter* | get_blend_shape_mode() | -+-----------+-----------------------------+ +The ``blend_shapes`` argument is an array of vertex data for each blend shape. Each element is an array of the same structure as ``arrays``, but :ref:`Mesh.ARRAY_VERTEX`, :ref:`Mesh.ARRAY_NORMAL`, and :ref:`Mesh.ARRAY_TANGENT` are set if and only if they are set in ``arrays`` and all other entries are ``null``. -Sets the blend shape mode to one of :ref:`BlendShapeMode`. +The ``lods`` argument is a dictionary with :ref:`float` keys and :ref:`PackedInt32Array` values. Each entry in the dictionary represents an LOD level of the surface, where the value is the :ref:`Mesh.ARRAY_INDEX` array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used. ----- +The ``flags`` argument is the bitwise OR of, as required: One value of :ref:`ArrayCustomFormat` left shifted by ``ARRAY_FORMAT_CUSTOMn_SHIFT`` for each custom channel in use, :ref:`Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE`, :ref:`Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS`, or :ref:`Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY`. -.. _class_ArrayMesh_property_custom_aabb: +\ **Note:** When using indices, it is recommended to only use points, lines, or triangles. -- :ref:`AABB` **custom_aabb** +.. rst-class:: classref-item-separator -+-----------+------------------------------+ -| *Default* | ``AABB( 0, 0, 0, 0, 0, 0 )`` | -+-----------+------------------------------+ -| *Setter* | set_custom_aabb(value) | -+-----------+------------------------------+ -| *Getter* | get_custom_aabb() | -+-----------+------------------------------+ +---- -Overrides the :ref:`AABB` with one defined by user for use with frustum culling. Especially useful to avoid unexpected culling when using a shader to offset vertices. +.. _class_ArrayMesh_method_clear_blend_shapes: -Method Descriptions -------------------- +.. rst-class:: classref-method -.. _class_ArrayMesh_method_add_blend_shape: +|void| **clear_blend_shapes**\ (\ ) :ref:`🔗` -- void **add_blend_shape** **(** :ref:`StringName` name **)** +Removes all blend shapes from this **ArrayMesh**. -Adds name for a blend shape that will be added with :ref:`add_surface_from_arrays`. Must be called before surface is added. +.. rst-class:: classref-item-separator ---- -.. _class_ArrayMesh_method_add_surface_from_arrays: +.. _class_ArrayMesh_method_clear_surfaces: -- void **add_surface_from_arrays** **(** :ref:`PrimitiveType` primitive, :ref:`Array` arrays, :ref:`Array` blend_shapes=[ ], :ref:`Dictionary` lods={ }, :ref:`int` compress_flags=31744 **)** +.. rst-class:: classref-method -Creates a new surface. +|void| **clear_surfaces**\ (\ ) :ref:`🔗` -Surfaces are created to be rendered using a ``primitive``, which may be any of the types defined in :ref:`PrimitiveType`. (As a note, when using indices, it is recommended to only use points, lines or triangles.) :ref:`Mesh.get_surface_count` will become the ``surf_idx`` for this new surface. +Removes all surfaces from this **ArrayMesh**. -The ``arrays`` argument is an array of arrays. See :ref:`ArrayType` for the values used in this array. For example, ``arrays[0]`` is the array of vertices. That first vertex sub-array is always required; the others are optional. Adding an index array puts this function into "index mode" where the vertex and other arrays become the sources of data and the index array defines the vertex order. All sub-arrays must have the same length as the vertex array or be empty, except for :ref:`ARRAY_INDEX` if it is used. +.. rst-class:: classref-item-separator -Adding an index array puts this function into "index mode" where the vertex and other arrays become the sources of data, and the index array defines the order of the vertices. +---- -Godot uses clockwise winding order for front faces of triangle primitive modes. +.. _class_ArrayMesh_method_get_blend_shape_count: ----- +.. rst-class:: classref-method -.. _class_ArrayMesh_method_clear_blend_shapes: +:ref:`int` **get_blend_shape_count**\ (\ ) |const| :ref:`🔗` -- void **clear_blend_shapes** **(** **)** +Returns the number of blend shapes that the **ArrayMesh** holds. -Removes all blend shapes from this ``ArrayMesh``. +.. rst-class:: classref-item-separator ---- -.. _class_ArrayMesh_method_clear_surfaces: +.. _class_ArrayMesh_method_get_blend_shape_name: -- void **clear_surfaces** **(** **)** +.. rst-class:: classref-method -Removes all surfaces from this ``ArrayMesh``. +:ref:`StringName` **get_blend_shape_name**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` ----- +Returns the name of the blend shape at this index. -.. _class_ArrayMesh_method_get_blend_shape_count: +.. rst-class:: classref-item-separator -- :ref:`int` **get_blend_shape_count** **(** **)** const +---- -Returns the number of blend shapes that the ``ArrayMesh`` holds. +.. _class_ArrayMesh_method_lightmap_unwrap: ----- +.. rst-class:: classref-method -.. _class_ArrayMesh_method_get_blend_shape_name: +:ref:`Error` **lightmap_unwrap**\ (\ transform\: :ref:`Transform3D`, texel_size\: :ref:`float`\ ) :ref:`🔗` -- :ref:`StringName` **get_blend_shape_name** **(** :ref:`int` index **)** const +Performs a UV unwrap on the **ArrayMesh** to prepare the mesh for lightmapping. -Returns the name of the blend shape at this index. +.. rst-class:: classref-item-separator ---- -.. _class_ArrayMesh_method_lightmap_unwrap: +.. _class_ArrayMesh_method_regen_normal_maps: -- :ref:`Error` **lightmap_unwrap** **(** :ref:`Transform` transform, :ref:`float` texel_size **)** +.. rst-class:: classref-method -Will perform a UV unwrap on the ``ArrayMesh`` to prepare the mesh for lightmapping. +|void| **regen_normal_maps**\ (\ ) :ref:`🔗` + +Regenerates tangents for each of the **ArrayMesh**'s surfaces. + +.. rst-class:: classref-item-separator ---- -.. _class_ArrayMesh_method_regen_normalmaps: +.. _class_ArrayMesh_method_set_blend_shape_name: + +.. rst-class:: classref-method -- void **regen_normalmaps** **(** **)** +|void| **set_blend_shape_name**\ (\ index\: :ref:`int`, name\: :ref:`StringName`\ ) :ref:`🔗` -Will regenerate normal maps for the ``ArrayMesh``. +Sets the name of the blend shape at this index. + +.. rst-class:: classref-item-separator ---- .. _class_ArrayMesh_method_surface_find_by_name: -- :ref:`int` **surface_find_by_name** **(** :ref:`String` name **)** const +.. rst-class:: classref-method + +:ref:`int` **surface_find_by_name**\ (\ name\: :ref:`String`\ ) |const| :ref:`🔗` -Returns the index of the first surface with this name held within this ``ArrayMesh``. If none are found, -1 is returned. +Returns the index of the first surface with this name held within this **ArrayMesh**. If none are found, -1 is returned. + +.. rst-class:: classref-item-separator ---- .. _class_ArrayMesh_method_surface_get_array_index_len: -- :ref:`int` **surface_get_array_index_len** **(** :ref:`int` surf_idx **)** const +.. rst-class:: classref-method + +:ref:`int` **surface_get_array_index_len**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the length in indices of the index array in the requested surface (see :ref:`add_surface_from_arrays`). +Returns the length in indices of the index array in the requested surface (see :ref:`add_surface_from_arrays()`). + +.. rst-class:: classref-item-separator ---- .. _class_ArrayMesh_method_surface_get_array_len: -- :ref:`int` **surface_get_array_len** **(** :ref:`int` surf_idx **)** const +.. rst-class:: classref-method + +:ref:`int` **surface_get_array_len**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the length in vertices of the vertex array in the requested surface (see :ref:`add_surface_from_arrays()`). -Returns the length in vertices of the vertex array in the requested surface (see :ref:`add_surface_from_arrays`). +.. rst-class:: classref-item-separator ---- .. _class_ArrayMesh_method_surface_get_format: -- :ref:`int` **surface_get_format** **(** :ref:`int` surf_idx **)** const +.. rst-class:: classref-method -Returns the format mask of the requested surface (see :ref:`add_surface_from_arrays`). +|bitfield|\[:ref:`ArrayFormat`\] **surface_get_format**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the format mask of the requested surface (see :ref:`add_surface_from_arrays()`). + +.. rst-class:: classref-item-separator ---- .. _class_ArrayMesh_method_surface_get_name: -- :ref:`String` **surface_get_name** **(** :ref:`int` surf_idx **)** const +.. rst-class:: classref-method + +:ref:`String` **surface_get_name**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` Gets the name assigned to this surface. +.. rst-class:: classref-item-separator + ---- .. _class_ArrayMesh_method_surface_get_primitive_type: -- :ref:`PrimitiveType` **surface_get_primitive_type** **(** :ref:`int` surf_idx **)** const +.. rst-class:: classref-method + +:ref:`PrimitiveType` **surface_get_primitive_type**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the primitive type of the requested surface (see :ref:`add_surface_from_arrays()`). -Returns the primitive type of the requested surface (see :ref:`add_surface_from_arrays`). +.. rst-class:: classref-item-separator + +---- + +.. _class_ArrayMesh_method_surface_remove: + +.. rst-class:: classref-method + +|void| **surface_remove**\ (\ surf_idx\: :ref:`int`\ ) :ref:`🔗` + +Removes the surface at the given index from the Mesh, shifting surfaces with higher index down by one. + +.. rst-class:: classref-item-separator ---- .. _class_ArrayMesh_method_surface_set_name: -- void **surface_set_name** **(** :ref:`int` surf_idx, :ref:`String` name **)** +.. rst-class:: classref-method + +|void| **surface_set_name**\ (\ surf_idx\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` Sets a name for a given surface. +.. rst-class:: classref-item-separator + +---- + +.. _class_ArrayMesh_method_surface_update_attribute_region: + +.. rst-class:: classref-method + +|void| **surface_update_attribute_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator + ---- -.. _class_ArrayMesh_method_surface_update_region: +.. _class_ArrayMesh_method_surface_update_skin_region: + +.. rst-class:: classref-method + +|void| **surface_update_skin_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator + +---- + +.. _class_ArrayMesh_method_surface_update_vertex_region: + +.. rst-class:: classref-method -- void **surface_update_region** **(** :ref:`int` surf_idx, :ref:`int` offset, :ref:`PackedByteArray` data **)** +|void| **surface_update_vertex_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) :ref:`🔗` -Updates a specified region of mesh arrays on the GPU. +.. container:: contribute -**Warning:** Only use if you know what you are doing. You can easily cause crashes by calling this function with improper arguments. + There is currently no description for this method. Please help us by `contributing one `__! +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_arrayoccluder3d.rst b/classes/class_arrayoccluder3d.rst new file mode 100644 index 00000000000..24daff7388c --- /dev/null +++ b/classes/class_arrayoccluder3d.rst @@ -0,0 +1,131 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ArrayOccluder3D.xml. + +.. _class_ArrayOccluder3D: + +ArrayOccluder3D +=============== + +**Inherits:** :ref:`Occluder3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +3D polygon shape for use with occlusion culling in :ref:`OccluderInstance3D`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**ArrayOccluder3D** stores an arbitrary 3D polygon shape that can be used by the engine's occlusion culling system. This is analogous to :ref:`ArrayMesh`, but for occluders. + +See :ref:`OccluderInstance3D`'s documentation for instructions on setting up occlusion culling. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Occlusion culling <../tutorials/3d/occlusion_culling>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------------------------------+----------------------------------------------------------+--------------------------+ + | :ref:`PackedInt32Array` | :ref:`indices` | ``PackedInt32Array()`` | + +-----------------------------------------------------+----------------------------------------------------------+--------------------------+ + | :ref:`PackedVector3Array` | :ref:`vertices` | ``PackedVector3Array()`` | + +-----------------------------------------------------+----------------------------------------------------------+--------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_arrays`\ (\ vertices\: :ref:`PackedVector3Array`, indices\: :ref:`PackedInt32Array`\ ) | + +--------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_ArrayOccluder3D_property_indices: + +.. rst-class:: classref-property + +:ref:`PackedInt32Array` **indices** = ``PackedInt32Array()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_indices**\ (\ value\: :ref:`PackedInt32Array`\ ) +- :ref:`PackedInt32Array` **get_indices**\ (\ ) + +The occluder's index position. Indices determine which points from the :ref:`vertices` array should be drawn, and in which order. + +\ **Note:** The occluder is always updated after setting this value. If creating occluders procedurally, consider using :ref:`set_arrays()` instead to avoid updating the occluder twice when it's created. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedInt32Array` for more details. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ArrayOccluder3D_property_vertices: + +.. rst-class:: classref-property + +:ref:`PackedVector3Array` **vertices** = ``PackedVector3Array()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_vertices**\ (\ value\: :ref:`PackedVector3Array`\ ) +- :ref:`PackedVector3Array` **get_vertices**\ (\ ) + +The occluder's vertex positions in local 3D coordinates. + +\ **Note:** The occluder is always updated after setting this value. If creating occluders procedurally, consider using :ref:`set_arrays()` instead to avoid updating the occluder twice when it's created. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedVector3Array` for more details. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_ArrayOccluder3D_method_set_arrays: + +.. rst-class:: classref-method + +|void| **set_arrays**\ (\ vertices\: :ref:`PackedVector3Array`, indices\: :ref:`PackedInt32Array`\ ) :ref:`🔗` + +Sets :ref:`indices` and :ref:`vertices`, while updating the final occluder only once after both values are set. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_arvranchor.rst b/classes/class_arvranchor.rst deleted file mode 100644 index c956e708fa7..00000000000 --- a/classes/class_arvranchor.rst +++ /dev/null @@ -1,113 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ARVRAnchor.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ARVRAnchor: - -ARVRAnchor -========== - -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -An anchor point in AR space. - -Description ------------ - -The ``ARVRAnchor`` point is a spatial node that maps a real world location identified by the AR platform to a position within the game world. For example, as long as plane detection in ARKit is on, ARKit will identify and update the position of planes (tables, floors, etc) and create anchors for them. - -This node is mapped to one of the anchors through its unique ID. When you receive a signal that a new anchor is available, you should add this node to your scene for that anchor. You can predefine nodes and set the ID; the nodes will simply remain on 0,0,0 until a plane is recognized. - -Keep in mind that, as long as plane detection is enabled, the size, placing and orientation of an anchor will be updated as the detection logic learns more about the real world out there especially if only part of the surface is in view. - -Properties ----------- - -+-----------------------+-------------------------------------------------------+-------+ -| :ref:`int` | :ref:`anchor_id` | ``1`` | -+-----------------------+-------------------------------------------------------+-------+ - -Methods -------- - -+-------------------------------+-----------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_anchor_name` **(** **)** const | -+-------------------------------+-----------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_is_active` **(** **)** const | -+-------------------------------+-----------------------------------------------------------------------------------+ -| :ref:`Mesh` | :ref:`get_mesh` **(** **)** const | -+-------------------------------+-----------------------------------------------------------------------------------+ -| :ref:`Plane` | :ref:`get_plane` **(** **)** const | -+-------------------------------+-----------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_size` **(** **)** const | -+-------------------------------+-----------------------------------------------------------------------------------+ - -Signals -------- - -.. _class_ARVRAnchor_signal_mesh_updated: - -- **mesh_updated** **(** :ref:`Mesh` mesh **)** - -Emitted when the mesh associated with the anchor changes or when one becomes available. This is especially important for topology that is constantly being ``mesh_updated``. - -Property Descriptions ---------------------- - -.. _class_ARVRAnchor_property_anchor_id: - -- :ref:`int` **anchor_id** - -+-----------+----------------------+ -| *Default* | ``1`` | -+-----------+----------------------+ -| *Setter* | set_anchor_id(value) | -+-----------+----------------------+ -| *Getter* | get_anchor_id() | -+-----------+----------------------+ - -The anchor's ID. You can set this before the anchor itself exists. The first anchor gets an ID of ``1``, the second an ID of ``2``, etc. When anchors get removed, the engine can then assign the corresponding ID to new anchors. The most common situation where anchors "disappear" is when the AR server identifies that two anchors represent different parts of the same plane and merges them. - -Method Descriptions -------------------- - -.. _class_ARVRAnchor_method_get_anchor_name: - -- :ref:`String` **get_anchor_name** **(** **)** const - -Returns the name given to this anchor. - ----- - -.. _class_ARVRAnchor_method_get_is_active: - -- :ref:`bool` **get_is_active** **(** **)** const - -Returns ``true`` if the anchor is being tracked and ``false`` if no anchor with this ID is currently known. - ----- - -.. _class_ARVRAnchor_method_get_mesh: - -- :ref:`Mesh` **get_mesh** **(** **)** const - -If provided by the :ref:`ARVRInterface`, this returns a mesh object for the anchor. For an anchor, this can be a shape related to the object being tracked or it can be a mesh that provides topology related to the anchor and can be used to create shadows/reflections on surfaces or for generating collision shapes. - ----- - -.. _class_ARVRAnchor_method_get_plane: - -- :ref:`Plane` **get_plane** **(** **)** const - -Returns a plane aligned with our anchor; handy for intersection testing. - ----- - -.. _class_ARVRAnchor_method_get_size: - -- :ref:`Vector3` **get_size** **(** **)** const - -Returns the estimated size of the plane that was detected. Say when the anchor relates to a table in the real world, this is the estimated size of the surface of that table. - diff --git a/classes/class_arvrcamera.rst b/classes/class_arvrcamera.rst deleted file mode 100644 index af9cef27b1e..00000000000 --- a/classes/class_arvrcamera.rst +++ /dev/null @@ -1,27 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ARVRCamera.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ARVRCamera: - -ARVRCamera -========== - -**Inherits:** :ref:`Camera` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -A camera node with a few overrules for AR/VR applied, such as location tracking. - -Description ------------ - -This is a helper spatial node for our camera; note that, if stereoscopic rendering is applicable (VR-HMD), most of the camera properties are ignored, as the HMD information overrides them. The only properties that can be trusted are the near and far planes. - -The position and orientation of this node is automatically updated by the ARVR Server to represent the location of the HMD if such tracking is available and can thus be used by game logic. Note that, in contrast to the ARVR Controller, the render thread has access to the most up-to-date tracking data of the HMD and the location of the ARVRCamera can lag a few milliseconds behind what is used for rendering as a result. - -Tutorials ---------- - -- :doc:`../tutorials/vr/index` - diff --git a/classes/class_arvrcontroller.rst b/classes/class_arvrcontroller.rst deleted file mode 100644 index 355539acae4..00000000000 --- a/classes/class_arvrcontroller.rst +++ /dev/null @@ -1,180 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ARVRController.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ARVRController: - -ARVRController -============== - -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -A spatial node representing a spatially-tracked controller. - -Description ------------ - -This is a helper spatial node that is linked to the tracking of controllers. It also offers several handy passthroughs to the state of buttons and such on the controllers. - -Controllers are linked by their ID. You can create controller nodes before the controllers are available. If your game always uses two controllers (one for each hand), you can predefine the controllers with ID 1 and 2; they will become active as soon as the controllers are identified. If you expect additional controllers to be used, you should react to the signals and add ARVRController nodes to your scene. - -The position of the controller node is automatically updated by the :ref:`ARVRServer`. This makes this node ideal to add child nodes to visualize the controller. - -Tutorials ---------- - -- :doc:`../tutorials/vr/index` - -Properties ----------- - -+---------------------------+-------------------------------------------------------------------+---------+ -| :ref:`int` | :ref:`controller_id` | ``1`` | -+---------------------------+-------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`rumble` | ``0.0`` | -+---------------------------+-------------------------------------------------------------------+---------+ - -Methods -------- - -+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_controller_name` **(** **)** const | -+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| :ref:`TrackerHand` | :ref:`get_hand` **(** **)** const | -+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_is_active` **(** **)** const | -+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_joystick_axis` **(** :ref:`int` axis **)** const | -+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_joystick_id` **(** **)** const | -+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Mesh` | :ref:`get_mesh` **(** **)** const | -+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_button_pressed` **(** :ref:`int` button **)** const | -+------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ - -Signals -------- - -.. _class_ARVRController_signal_button_pressed: - -- **button_pressed** **(** :ref:`int` button **)** - -Emitted when a button on this controller is pressed. - ----- - -.. _class_ARVRController_signal_button_release: - -- **button_release** **(** :ref:`int` button **)** - -Emitted when a button on this controller is released. - ----- - -.. _class_ARVRController_signal_mesh_updated: - -- **mesh_updated** **(** :ref:`Mesh` mesh **)** - -Emitted when the mesh associated with the controller changes or when one becomes available. Generally speaking this will be a static mesh after becoming available. - -Property Descriptions ---------------------- - -.. _class_ARVRController_property_controller_id: - -- :ref:`int` **controller_id** - -+-----------+--------------------------+ -| *Default* | ``1`` | -+-----------+--------------------------+ -| *Setter* | set_controller_id(value) | -+-----------+--------------------------+ -| *Getter* | get_controller_id() | -+-----------+--------------------------+ - -The controller's ID. - -A controller ID of 0 is unbound and will always result in an inactive node. Controller ID 1 is reserved for the first controller that identifies itself as the left-hand controller and ID 2 is reserved for the first controller that identifies itself as the right-hand controller. - -For any other controller that the :ref:`ARVRServer` detects, we continue with controller ID 3. - -When a controller is turned off, its slot is freed. This ensures controllers will keep the same ID even when controllers with lower IDs are turned off. - ----- - -.. _class_ARVRController_property_rumble: - -- :ref:`float` **rumble** - -+-----------+-------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------+ -| *Setter* | set_rumble(value) | -+-----------+-------------------+ -| *Getter* | get_rumble() | -+-----------+-------------------+ - -The degree to which the controller vibrates. Ranges from ``0.0`` to ``1.0`` with precision ``.01``. If changed, updates :ref:`ARVRPositionalTracker.rumble` accordingly. - -This is a useful property to animate if you want the controller to vibrate for a limited duration. - -Method Descriptions -------------------- - -.. _class_ARVRController_method_get_controller_name: - -- :ref:`String` **get_controller_name** **(** **)** const - -If active, returns the name of the associated controller if provided by the AR/VR SDK used. - ----- - -.. _class_ARVRController_method_get_hand: - -- :ref:`TrackerHand` **get_hand** **(** **)** const - -Returns the hand holding this controller, if known. See :ref:`TrackerHand`. - ----- - -.. _class_ARVRController_method_get_is_active: - -- :ref:`bool` **get_is_active** **(** **)** const - -Returns ``true`` if the bound controller is active. ARVR systems attempt to track active controllers. - ----- - -.. _class_ARVRController_method_get_joystick_axis: - -- :ref:`float` **get_joystick_axis** **(** :ref:`int` axis **)** const - -Returns the value of the given axis for things like triggers, touchpads, etc. that are embedded into the controller. - ----- - -.. _class_ARVRController_method_get_joystick_id: - -- :ref:`int` **get_joystick_id** **(** **)** const - -Returns the ID of the joystick object bound to this. Every controller tracked by the :ref:`ARVRServer` that has buttons and axis will also be registered as a joystick within Godot. This means that all the normal joystick tracking and input mapping will work for buttons and axis found on the AR/VR controllers. This ID is purely offered as information so you can link up the controller with its joystick entry. - ----- - -.. _class_ARVRController_method_get_mesh: - -- :ref:`Mesh` **get_mesh** **(** **)** const - -If provided by the :ref:`ARVRInterface`, this returns a mesh associated with the controller. This can be used to visualize the controller. - ----- - -.. _class_ARVRController_method_is_button_pressed: - -- :ref:`bool` **is_button_pressed** **(** :ref:`int` button **)** const - -Returns ``true`` if the button at index ``button`` is pressed. See :ref:`JoystickList`, in particular the ``JOY_VR_*`` constants. - diff --git a/classes/class_arvrinterface.rst b/classes/class_arvrinterface.rst deleted file mode 100644 index ef54dc151c9..00000000000 --- a/classes/class_arvrinterface.rst +++ /dev/null @@ -1,254 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ARVRInterface.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ARVRInterface: - -ARVRInterface -============= - -**Inherits:** :ref:`Reference` **<** :ref:`Object` - -**Inherited By:** :ref:`ARVRInterfaceGDNative`, :ref:`MobileVRInterface` - -Base class for an AR/VR interface implementation. - -Description ------------ - -This class needs to be implemented to make an AR or VR platform available to Godot and these should be implemented as C++ modules or GDNative modules (note that for GDNative the subclass ARVRScriptInterface should be used). Part of the interface is exposed to GDScript so you can detect, enable and configure an AR or VR platform. - -Interfaces should be written in such a way that simply enabling them will give us a working setup. You can query the available interfaces through :ref:`ARVRServer`. - -Tutorials ---------- - -- :doc:`../tutorials/vr/index` - -Properties ----------- - -+-------------------------+----------------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`ar_is_anchor_detection_enabled` | ``false`` | -+-------------------------+----------------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`interface_is_initialized` | ``false`` | -+-------------------------+----------------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`interface_is_primary` | ``false`` | -+-------------------------+----------------------------------------------------------------------------------------------------+-----------+ - -Methods -------- - -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_camera_feed_id` **(** **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_capabilities` **(** **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_name` **(** **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_render_targetsize` **(** **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :ref:`Tracking_status` | :ref:`get_tracking_status` **(** **)** const | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`initialize` **(** **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_stereo` **(** **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| void | :ref:`uninitialize` **(** **)** | -+------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - -Enumerations ------------- - -.. _enum_ARVRInterface_Capabilities: - -.. _class_ARVRInterface_constant_ARVR_NONE: - -.. _class_ARVRInterface_constant_ARVR_MONO: - -.. _class_ARVRInterface_constant_ARVR_STEREO: - -.. _class_ARVRInterface_constant_ARVR_AR: - -.. _class_ARVRInterface_constant_ARVR_EXTERNAL: - -enum **Capabilities**: - -- **ARVR_NONE** = **0** --- No ARVR capabilities. - -- **ARVR_MONO** = **1** --- This interface can work with normal rendering output (non-HMD based AR). - -- **ARVR_STEREO** = **2** --- This interface supports stereoscopic rendering. - -- **ARVR_AR** = **4** --- This interface supports AR (video background and real world tracking). - -- **ARVR_EXTERNAL** = **8** --- This interface outputs to an external device. If the main viewport is used, the on screen output is an unmodified buffer of either the left or right eye (stretched if the viewport size is not changed to the same aspect ratio of :ref:`get_render_targetsize`). Using a separate viewport node frees up the main viewport for other purposes. - ----- - -.. _enum_ARVRInterface_Eyes: - -.. _class_ARVRInterface_constant_EYE_MONO: - -.. _class_ARVRInterface_constant_EYE_LEFT: - -.. _class_ARVRInterface_constant_EYE_RIGHT: - -enum **Eyes**: - -- **EYE_MONO** = **0** --- Mono output, this is mostly used internally when retrieving positioning information for our camera node or when stereo scopic rendering is not supported. - -- **EYE_LEFT** = **1** --- Left eye output, this is mostly used internally when rendering the image for the left eye and obtaining positioning and projection information. - -- **EYE_RIGHT** = **2** --- Right eye output, this is mostly used internally when rendering the image for the right eye and obtaining positioning and projection information. - ----- - -.. _enum_ARVRInterface_Tracking_status: - -.. _class_ARVRInterface_constant_ARVR_NORMAL_TRACKING: - -.. _class_ARVRInterface_constant_ARVR_EXCESSIVE_MOTION: - -.. _class_ARVRInterface_constant_ARVR_INSUFFICIENT_FEATURES: - -.. _class_ARVRInterface_constant_ARVR_UNKNOWN_TRACKING: - -.. _class_ARVRInterface_constant_ARVR_NOT_TRACKING: - -enum **Tracking_status**: - -- **ARVR_NORMAL_TRACKING** = **0** --- Tracking is behaving as expected. - -- **ARVR_EXCESSIVE_MOTION** = **1** --- Tracking is hindered by excessive motion (the player is moving faster than tracking can keep up). - -- **ARVR_INSUFFICIENT_FEATURES** = **2** --- Tracking is hindered by insufficient features, it's too dark (for camera-based tracking), player is blocked, etc. - -- **ARVR_UNKNOWN_TRACKING** = **3** --- We don't know the status of the tracking or this interface does not provide feedback. - -- **ARVR_NOT_TRACKING** = **4** --- Tracking is not functional (camera not plugged in or obscured, lighthouses turned off, etc.). - -Property Descriptions ---------------------- - -.. _class_ARVRInterface_property_ar_is_anchor_detection_enabled: - -- :ref:`bool` **ar_is_anchor_detection_enabled** - -+-----------+----------------------------------------+ -| *Default* | ``false`` | -+-----------+----------------------------------------+ -| *Setter* | set_anchor_detection_is_enabled(value) | -+-----------+----------------------------------------+ -| *Getter* | get_anchor_detection_is_enabled() | -+-----------+----------------------------------------+ - -On an AR interface, ``true`` if anchor detection is enabled. - ----- - -.. _class_ARVRInterface_property_interface_is_initialized: - -- :ref:`bool` **interface_is_initialized** - -+-----------+---------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------+ -| *Setter* | set_is_initialized(value) | -+-----------+---------------------------+ -| *Getter* | is_initialized() | -+-----------+---------------------------+ - -``true`` if this interface been initialized. - ----- - -.. _class_ARVRInterface_property_interface_is_primary: - -- :ref:`bool` **interface_is_primary** - -+-----------+-----------------------+ -| *Default* | ``false`` | -+-----------+-----------------------+ -| *Setter* | set_is_primary(value) | -+-----------+-----------------------+ -| *Getter* | is_primary() | -+-----------+-----------------------+ - -``true`` if this is the primary interface. - -Method Descriptions -------------------- - -.. _class_ARVRInterface_method_get_camera_feed_id: - -- :ref:`int` **get_camera_feed_id** **(** **)** - -If this is an AR interface that requires displaying a camera feed as the background, this method returns the feed ID in the :ref:`CameraServer` for this interface. - ----- - -.. _class_ARVRInterface_method_get_capabilities: - -- :ref:`int` **get_capabilities** **(** **)** const - -Returns a combination of :ref:`Capabilities` flags providing information about the capabilities of this interface. - ----- - -.. _class_ARVRInterface_method_get_name: - -- :ref:`StringName` **get_name** **(** **)** const - -Returns the name of this interface (OpenVR, OpenHMD, ARKit, etc). - ----- - -.. _class_ARVRInterface_method_get_render_targetsize: - -- :ref:`Vector2` **get_render_targetsize** **(** **)** - -Returns the resolution at which we should render our intermediate results before things like lens distortion are applied by the VR platform. - ----- - -.. _class_ARVRInterface_method_get_tracking_status: - -- :ref:`Tracking_status` **get_tracking_status** **(** **)** const - -If supported, returns the status of our tracking. This will allow you to provide feedback to the user whether there are issues with positional tracking. - ----- - -.. _class_ARVRInterface_method_initialize: - -- :ref:`bool` **initialize** **(** **)** - -Call this to initialize this interface. The first interface that is initialized is identified as the primary interface and it will be used for rendering output. - -After initializing the interface you want to use you then need to enable the AR/VR mode of a viewport and rendering should commence. - -**Note:** You must enable the AR/VR mode on the main viewport for any device that uses the main output of Godot, such as for mobile VR. - -If you do this for a platform that handles its own output (such as OpenVR) Godot will show just one eye without distortion on screen. Alternatively, you can add a separate viewport node to your scene and enable AR/VR on that viewport. It will be used to output to the HMD, leaving you free to do anything you like in the main window, such as using a separate camera as a spectator camera or rendering something completely different. - -While currently not used, you can activate additional interfaces. You may wish to do this if you want to track controllers from other platforms. However, at this point in time only one interface can render to an HMD. - ----- - -.. _class_ARVRInterface_method_is_stereo: - -- :ref:`bool` **is_stereo** **(** **)** - -Returns ``true`` if the current output of this interface is in stereo. - ----- - -.. _class_ARVRInterface_method_uninitialize: - -- void **uninitialize** **(** **)** - -Turns the interface off. - diff --git a/classes/class_arvrinterfacegdnative.rst b/classes/class_arvrinterfacegdnative.rst deleted file mode 100644 index 9a58256b20a..00000000000 --- a/classes/class_arvrinterfacegdnative.rst +++ /dev/null @@ -1,20 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ARVRInterfaceGDNative.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ARVRInterfaceGDNative: - -ARVRInterfaceGDNative -===================== - -**Inherits:** :ref:`ARVRInterface` **<** :ref:`Reference` **<** :ref:`Object` - -GDNative wrapper for an ARVR interface. - -Description ------------ - -This is a wrapper class for GDNative implementations of the ARVR interface. To use a GDNative ARVR interface, simply instantiate this object and set your GDNative library containing the ARVR interface implementation. - diff --git a/classes/class_arvrorigin.rst b/classes/class_arvrorigin.rst deleted file mode 100644 index ff6dc23d1ea..00000000000 --- a/classes/class_arvrorigin.rst +++ /dev/null @@ -1,57 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ARVROrigin.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ARVROrigin: - -ARVROrigin -========== - -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -The origin point in AR/VR. - -Description ------------ - -This is a special node within the AR/VR system that maps the physical location of the center of our tracking space to the virtual location within our game world. - -There should be only one of these nodes in your scene and you must have one. All the ARVRCamera, ARVRController and ARVRAnchor nodes should be direct children of this node for spatial tracking to work correctly. - -It is the position of this node that you update when your character needs to move through your game world while we're not moving in the real world. Movement in the real world is always in relation to this origin point. - -For example, if your character is driving a car, the ARVROrigin node should be a child node of this car. Or, if you're implementing a teleport system to move your character, you should change the position of this node. - -Tutorials ---------- - -- :doc:`../tutorials/vr/index` - -Properties ----------- - -+---------------------------+-----------------------------------------------------------+---------+ -| :ref:`float` | :ref:`world_scale` | ``1.0`` | -+---------------------------+-----------------------------------------------------------+---------+ - -Property Descriptions ---------------------- - -.. _class_ARVROrigin_property_world_scale: - -- :ref:`float` **world_scale** - -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_world_scale(value) | -+-----------+------------------------+ -| *Getter* | get_world_scale() | -+-----------+------------------------+ - -Allows you to adjust the scale to your game's units. Most AR/VR platforms assume a scale of 1 game world unit = 1 real world meter. - -**Note:** This method is a passthrough to the :ref:`ARVRServer` itself. - diff --git a/classes/class_arvrpositionaltracker.rst b/classes/class_arvrpositionaltracker.rst deleted file mode 100644 index 62f1e5a759f..00000000000 --- a/classes/class_arvrpositionaltracker.rst +++ /dev/null @@ -1,188 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ARVRPositionalTracker.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ARVRPositionalTracker: - -ARVRPositionalTracker -===================== - -**Inherits:** :ref:`Object` - -A tracked object. - -Description ------------ - -An instance of this object represents a device that is tracked, such as a controller or anchor point. HMDs aren't represented here as they are handled internally. - -As controllers are turned on and the AR/VR interface detects them, instances of this object are automatically added to this list of active tracking objects accessible through the :ref:`ARVRServer`. - -The :ref:`ARVRController` and :ref:`ARVRAnchor` both consume objects of this type and should be used in your project. The positional trackers are just under-the-hood objects that make this all work. These are mostly exposed so that GDNative-based interfaces can interact with them. - -Tutorials ---------- - -- :doc:`../tutorials/vr/index` - -Properties ----------- - -+---------------------------+------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`rumble` | ``0.0`` | -+---------------------------+------------------------------------------------------------+---------+ - -Methods -------- - -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`TrackerHand` | :ref:`get_hand` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_joy_id` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Mesh` | :ref:`get_mesh` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_name` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`get_orientation` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_position` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_tracker_id` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_tracks_orientation` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_tracks_position` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform` | :ref:`get_transform` **(** :ref:`bool` adjust_by_reference_frame **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`TrackerType` | :ref:`get_type` **(** **)** const | -+------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ - -Enumerations ------------- - -.. _enum_ARVRPositionalTracker_TrackerHand: - -.. _class_ARVRPositionalTracker_constant_TRACKER_HAND_UNKNOWN: - -.. _class_ARVRPositionalTracker_constant_TRACKER_LEFT_HAND: - -.. _class_ARVRPositionalTracker_constant_TRACKER_RIGHT_HAND: - -enum **TrackerHand**: - -- **TRACKER_HAND_UNKNOWN** = **0** --- The hand this tracker is held in is unknown or not applicable. - -- **TRACKER_LEFT_HAND** = **1** --- This tracker is the left hand controller. - -- **TRACKER_RIGHT_HAND** = **2** --- This tracker is the right hand controller. - -Property Descriptions ---------------------- - -.. _class_ARVRPositionalTracker_property_rumble: - -- :ref:`float` **rumble** - -+-----------+-------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------+ -| *Setter* | set_rumble(value) | -+-----------+-------------------+ -| *Getter* | get_rumble() | -+-----------+-------------------+ - -The degree to which the tracker rumbles. Ranges from ``0.0`` to ``1.0`` with precision ``.01``. - -Method Descriptions -------------------- - -.. _class_ARVRPositionalTracker_method_get_hand: - -- :ref:`TrackerHand` **get_hand** **(** **)** const - -Returns the hand holding this tracker, if known. See :ref:`TrackerHand` constants. - ----- - -.. _class_ARVRPositionalTracker_method_get_joy_id: - -- :ref:`int` **get_joy_id** **(** **)** const - -If this is a controller that is being tracked, the controller will also be represented by a joystick entry with this ID. - ----- - -.. _class_ARVRPositionalTracker_method_get_mesh: - -- :ref:`Mesh` **get_mesh** **(** **)** const - -Returns the mesh related to a controller or anchor point if one is available. - ----- - -.. _class_ARVRPositionalTracker_method_get_name: - -- :ref:`StringName` **get_name** **(** **)** const - -Returns the controller or anchor point's name if available. - ----- - -.. _class_ARVRPositionalTracker_method_get_orientation: - -- :ref:`Basis` **get_orientation** **(** **)** const - -Returns the controller's orientation matrix. - ----- - -.. _class_ARVRPositionalTracker_method_get_position: - -- :ref:`Vector3` **get_position** **(** **)** const - -Returns the world-space controller position. - ----- - -.. _class_ARVRPositionalTracker_method_get_tracker_id: - -- :ref:`int` **get_tracker_id** **(** **)** const - -Returns the internal tracker ID. This uniquely identifies the tracker per tracker type and matches the ID you need to specify for nodes such as the :ref:`ARVRController` and :ref:`ARVRAnchor` nodes. - ----- - -.. _class_ARVRPositionalTracker_method_get_tracks_orientation: - -- :ref:`bool` **get_tracks_orientation** **(** **)** const - -Returns ``true`` if this device tracks orientation. - ----- - -.. _class_ARVRPositionalTracker_method_get_tracks_position: - -- :ref:`bool` **get_tracks_position** **(** **)** const - -Returns ``true`` if this device tracks position. - ----- - -.. _class_ARVRPositionalTracker_method_get_transform: - -- :ref:`Transform` **get_transform** **(** :ref:`bool` adjust_by_reference_frame **)** const - -Returns the transform combining this device's orientation and position. - ----- - -.. _class_ARVRPositionalTracker_method_get_type: - -- :ref:`TrackerType` **get_type** **(** **)** const - -Returns the tracker's type. - diff --git a/classes/class_arvrserver.rst b/classes/class_arvrserver.rst deleted file mode 100644 index a3ff58badb8..00000000000 --- a/classes/class_arvrserver.rst +++ /dev/null @@ -1,283 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ARVRServer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ARVRServer: - -ARVRServer -========== - -**Inherits:** :ref:`Object` - -Server for AR and VR features. - -Description ------------ - -The AR/VR server is the heart of our Advanced and Virtual Reality solution and handles all the processing. - -Tutorials ---------- - -- :doc:`../tutorials/vr/index` - -Properties ----------- - -+-------------------------------------------+-----------------------------------------------------------------------+---------+ -| :ref:`ARVRInterface` | :ref:`primary_interface` | | -+-------------------------------------------+-----------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`world_scale` | ``1.0`` | -+-------------------------------------------+-----------------------------------------------------------------------+---------+ - -Methods -------- - -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`center_on_hmd` **(** :ref:`RotationMode` rotation_mode, :ref:`bool` keep_height **)** | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`ARVRInterface` | :ref:`find_interface` **(** :ref:`String` name **)** const | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform` | :ref:`get_hmd_transform` **(** **)** | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`ARVRInterface` | :ref:`get_interface` **(** :ref:`int` idx **)** const | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_interface_count` **(** **)** const | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_interfaces` **(** **)** const | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_last_commit_usec` **(** **)** | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_last_frame_usec` **(** **)** | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_last_process_usec` **(** **)** | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform` | :ref:`get_reference_frame` **(** **)** const | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`ARVRPositionalTracker` | :ref:`get_tracker` **(** :ref:`int` idx **)** const | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_tracker_count` **(** **)** const | -+-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Signals -------- - -.. _class_ARVRServer_signal_interface_added: - -- **interface_added** **(** :ref:`StringName` interface_name **)** - -Emitted when a new interface has been added. - ----- - -.. _class_ARVRServer_signal_interface_removed: - -- **interface_removed** **(** :ref:`StringName` interface_name **)** - -Emitted when an interface is removed. - ----- - -.. _class_ARVRServer_signal_tracker_added: - -- **tracker_added** **(** :ref:`StringName` tracker_name, :ref:`int` type, :ref:`int` id **)** - -Emitted when a new tracker has been added. If you don't use a fixed number of controllers or if you're using :ref:`ARVRAnchor`\ s for an AR solution, it is important to react to this signal to add the appropriate :ref:`ARVRController` or :ref:`ARVRAnchor` nodes related to this new tracker. - ----- - -.. _class_ARVRServer_signal_tracker_removed: - -- **tracker_removed** **(** :ref:`StringName` tracker_name, :ref:`int` type, :ref:`int` id **)** - -Emitted when a tracker is removed. You should remove any :ref:`ARVRController` or :ref:`ARVRAnchor` points if applicable. This is not mandatory, the nodes simply become inactive and will be made active again when a new tracker becomes available (i.e. a new controller is switched on that takes the place of the previous one). - -Enumerations ------------- - -.. _enum_ARVRServer_TrackerType: - -.. _class_ARVRServer_constant_TRACKER_CONTROLLER: - -.. _class_ARVRServer_constant_TRACKER_BASESTATION: - -.. _class_ARVRServer_constant_TRACKER_ANCHOR: - -.. _class_ARVRServer_constant_TRACKER_ANY_KNOWN: - -.. _class_ARVRServer_constant_TRACKER_UNKNOWN: - -.. _class_ARVRServer_constant_TRACKER_ANY: - -enum **TrackerType**: - -- **TRACKER_CONTROLLER** = **1** --- The tracker tracks the location of a controller. - -- **TRACKER_BASESTATION** = **2** --- The tracker tracks the location of a base station. - -- **TRACKER_ANCHOR** = **4** --- The tracker tracks the location and size of an AR anchor. - -- **TRACKER_ANY_KNOWN** = **127** --- Used internally to filter trackers of any known type. - -- **TRACKER_UNKNOWN** = **128** --- Used internally if we haven't set the tracker type yet. - -- **TRACKER_ANY** = **255** --- Used internally to select all trackers. - ----- - -.. _enum_ARVRServer_RotationMode: - -.. _class_ARVRServer_constant_RESET_FULL_ROTATION: - -.. _class_ARVRServer_constant_RESET_BUT_KEEP_TILT: - -.. _class_ARVRServer_constant_DONT_RESET_ROTATION: - -enum **RotationMode**: - -- **RESET_FULL_ROTATION** = **0** --- Fully reset the orientation of the HMD. Regardless of what direction the user is looking to in the real world. The user will look dead ahead in the virtual world. - -- **RESET_BUT_KEEP_TILT** = **1** --- Resets the orientation but keeps the tilt of the device. So if we're looking down, we keep looking down but heading will be reset. - -- **DONT_RESET_ROTATION** = **2** --- Does not reset the orientation of the HMD, only the position of the player gets centered. - -Property Descriptions ---------------------- - -.. _class_ARVRServer_property_primary_interface: - -- :ref:`ARVRInterface` **primary_interface** - -+----------+------------------------------+ -| *Setter* | set_primary_interface(value) | -+----------+------------------------------+ -| *Getter* | get_primary_interface() | -+----------+------------------------------+ - -The primary :ref:`ARVRInterface` currently bound to the ``ARVRServer``. - ----- - -.. _class_ARVRServer_property_world_scale: - -- :ref:`float` **world_scale** - -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_world_scale(value) | -+-----------+------------------------+ -| *Getter* | get_world_scale() | -+-----------+------------------------+ - -Allows you to adjust the scale to your game's units. Most AR/VR platforms assume a scale of 1 game world unit = 1 real world meter. - -Method Descriptions -------------------- - -.. _class_ARVRServer_method_center_on_hmd: - -- void **center_on_hmd** **(** :ref:`RotationMode` rotation_mode, :ref:`bool` keep_height **)** - -This is an important function to understand correctly. AR and VR platforms all handle positioning slightly differently. - -For platforms that do not offer spatial tracking, our origin point (0,0,0) is the location of our HMD, but you have little control over the direction the player is facing in the real world. - -For platforms that do offer spatial tracking, our origin point depends very much on the system. For OpenVR, our origin point is usually the center of the tracking space, on the ground. For other platforms, it's often the location of the tracking camera. - -This method allows you to center your tracker on the location of the HMD. It will take the current location of the HMD and use that to adjust all your tracking data; in essence, realigning the real world to your player's current position in the game world. - -For this method to produce usable results, tracking information must be available. This often takes a few frames after starting your game. - -You should call this method after a few seconds have passed. For instance, when the user requests a realignment of the display holding a designated button on a controller for a short period of time, or when implementing a teleport mechanism. - ----- - -.. _class_ARVRServer_method_find_interface: - -- :ref:`ARVRInterface` **find_interface** **(** :ref:`String` name **)** const - -Finds an interface by its name. For instance, if your project uses capabilities of an AR/VR platform, you can find the interface for that platform by name and initialize it. - ----- - -.. _class_ARVRServer_method_get_hmd_transform: - -- :ref:`Transform` **get_hmd_transform** **(** **)** - -Returns the primary interface's transformation. - ----- - -.. _class_ARVRServer_method_get_interface: - -- :ref:`ARVRInterface` **get_interface** **(** :ref:`int` idx **)** const - -Returns the interface registered at a given index in our list of interfaces. - ----- - -.. _class_ARVRServer_method_get_interface_count: - -- :ref:`int` **get_interface_count** **(** **)** const - -Returns the number of interfaces currently registered with the AR/VR server. If your project supports multiple AR/VR platforms, you can look through the available interface, and either present the user with a selection or simply try to initialize each interface and use the first one that returns ``true``. - ----- - -.. _class_ARVRServer_method_get_interfaces: - -- :ref:`Array` **get_interfaces** **(** **)** const - -Returns a list of available interfaces the ID and name of each interface. - ----- - -.. _class_ARVRServer_method_get_last_commit_usec: - -- :ref:`int` **get_last_commit_usec** **(** **)** - -Returns the absolute timestamp (in μs) of the last ``ARVRServer`` commit of the AR/VR eyes to :ref:`VisualServer`. The value comes from an internal call to :ref:`OS.get_ticks_usec`. - ----- - -.. _class_ARVRServer_method_get_last_frame_usec: - -- :ref:`int` **get_last_frame_usec** **(** **)** - -Returns the duration (in μs) of the last frame. This is computed as the difference between :ref:`get_last_commit_usec` and :ref:`get_last_process_usec` when committing. - ----- - -.. _class_ARVRServer_method_get_last_process_usec: - -- :ref:`int` **get_last_process_usec** **(** **)** - -Returns the absolute timestamp (in μs) of the last ``ARVRServer`` process callback. The value comes from an internal call to :ref:`OS.get_ticks_usec`. - ----- - -.. _class_ARVRServer_method_get_reference_frame: - -- :ref:`Transform` **get_reference_frame** **(** **)** const - -Returns the reference frame transform. Mostly used internally and exposed for GDNative build interfaces. - ----- - -.. _class_ARVRServer_method_get_tracker: - -- :ref:`ARVRPositionalTracker` **get_tracker** **(** :ref:`int` idx **)** const - -Returns the positional tracker at the given ID. - ----- - -.. _class_ARVRServer_method_get_tracker_count: - -- :ref:`int` **get_tracker_count** **(** **)** const - -Returns the number of trackers currently registered. - diff --git a/classes/class_aspectratiocontainer.rst b/classes/class_aspectratiocontainer.rst new file mode 100644 index 00000000000..d606f09adfd --- /dev/null +++ b/classes/class_aspectratiocontainer.rst @@ -0,0 +1,213 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AspectRatioContainer.xml. + +.. _class_AspectRatioContainer: + +AspectRatioContainer +==================== + +**Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` + +A container that preserves the proportions of its child controls. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A container type that arranges its child controls in a way that preserves their proportions automatically when the container is resized. Useful when a container has a dynamic size and the child nodes must adjust their sizes accordingly without losing their aspect ratios. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ + | :ref:`AlignmentMode` | :ref:`alignment_horizontal` | ``1`` | + +---------------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ + | :ref:`AlignmentMode` | :ref:`alignment_vertical` | ``1`` | + +---------------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`ratio` | ``1.0`` | + +---------------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ + | :ref:`StretchMode` | :ref:`stretch_mode` | ``2`` | + +---------------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AspectRatioContainer_StretchMode: + +.. rst-class:: classref-enumeration + +enum **StretchMode**: :ref:`🔗` + +.. _class_AspectRatioContainer_constant_STRETCH_WIDTH_CONTROLS_HEIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`StretchMode` **STRETCH_WIDTH_CONTROLS_HEIGHT** = ``0`` + +The height of child controls is automatically adjusted based on the width of the container. + +.. _class_AspectRatioContainer_constant_STRETCH_HEIGHT_CONTROLS_WIDTH: + +.. rst-class:: classref-enumeration-constant + +:ref:`StretchMode` **STRETCH_HEIGHT_CONTROLS_WIDTH** = ``1`` + +The width of child controls is automatically adjusted based on the height of the container. + +.. _class_AspectRatioContainer_constant_STRETCH_FIT: + +.. rst-class:: classref-enumeration-constant + +:ref:`StretchMode` **STRETCH_FIT** = ``2`` + +The bounding rectangle of child controls is automatically adjusted to fit inside the container while keeping the aspect ratio. + +.. _class_AspectRatioContainer_constant_STRETCH_COVER: + +.. rst-class:: classref-enumeration-constant + +:ref:`StretchMode` **STRETCH_COVER** = ``3`` + +The width and height of child controls is automatically adjusted to make their bounding rectangle cover the entire area of the container while keeping the aspect ratio. + +When the bounding rectangle of child controls exceed the container's size and :ref:`Control.clip_contents` is enabled, this allows to show only the container's area restricted by its own bounding rectangle. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AspectRatioContainer_AlignmentMode: + +.. rst-class:: classref-enumeration + +enum **AlignmentMode**: :ref:`🔗` + +.. _class_AspectRatioContainer_constant_ALIGNMENT_BEGIN: + +.. rst-class:: classref-enumeration-constant + +:ref:`AlignmentMode` **ALIGNMENT_BEGIN** = ``0`` + +Aligns child controls with the beginning (left or top) of the container. + +.. _class_AspectRatioContainer_constant_ALIGNMENT_CENTER: + +.. rst-class:: classref-enumeration-constant + +:ref:`AlignmentMode` **ALIGNMENT_CENTER** = ``1`` + +Aligns child controls with the center of the container. + +.. _class_AspectRatioContainer_constant_ALIGNMENT_END: + +.. rst-class:: classref-enumeration-constant + +:ref:`AlignmentMode` **ALIGNMENT_END** = ``2`` + +Aligns child controls with the end (right or bottom) of the container. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AspectRatioContainer_property_alignment_horizontal: + +.. rst-class:: classref-property + +:ref:`AlignmentMode` **alignment_horizontal** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_alignment_horizontal**\ (\ value\: :ref:`AlignmentMode`\ ) +- :ref:`AlignmentMode` **get_alignment_horizontal**\ (\ ) + +Specifies the horizontal relative position of child controls. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AspectRatioContainer_property_alignment_vertical: + +.. rst-class:: classref-property + +:ref:`AlignmentMode` **alignment_vertical** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_alignment_vertical**\ (\ value\: :ref:`AlignmentMode`\ ) +- :ref:`AlignmentMode` **get_alignment_vertical**\ (\ ) + +Specifies the vertical relative position of child controls. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AspectRatioContainer_property_ratio: + +.. rst-class:: classref-property + +:ref:`float` **ratio** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_ratio**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_ratio**\ (\ ) + +The aspect ratio to enforce on child controls. This is the width divided by the height. The ratio depends on the :ref:`stretch_mode`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AspectRatioContainer_property_stretch_mode: + +.. rst-class:: classref-property + +:ref:`StretchMode` **stretch_mode** = ``2`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stretch_mode**\ (\ value\: :ref:`StretchMode`\ ) +- :ref:`StretchMode` **get_stretch_mode**\ (\ ) + +The stretch mode used to align child controls. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_astar.rst b/classes/class_astar.rst deleted file mode 100644 index f7bd4c33318..00000000000 --- a/classes/class_astar.rst +++ /dev/null @@ -1,351 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AStar.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_AStar: - -AStar -===== - -**Inherits:** :ref:`Reference` **<** :ref:`Object` - -An implementation of A\* to find shortest paths among connected points in space. - -Description ------------ - -A\* (A star) is a computer algorithm that is widely used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments). It enjoys widespread use due to its performance and accuracy. Godot's A\* implementation uses points in three-dimensional space and Euclidean distances by default. - -You must add points manually with :ref:`add_point` and create segments manually with :ref:`connect_points`. Then you can test if there is a path between two points with the :ref:`are_points_connected` function, get a path containing indices by :ref:`get_id_path`, or one containing actual coordinates with :ref:`get_point_path`. - -It is also possible to use non-Euclidean distances. To do so, create a class that extends ``AStar`` and override methods :ref:`_compute_cost` and :ref:`_estimate_cost`. Both take two indices and return a length, as is shown in the following example. - -:: - - class MyAStar: - extends AStar - - func _compute_cost(u, v): - return abs(u - v) - - func _estimate_cost(u, v): - return min(0, abs(u - v) - 1) - -:ref:`_estimate_cost` should return a lower bound of the distance, i.e. ``_estimate_cost(u, v) <= _compute_cost(u, v)``. This serves as a hint to the algorithm because the custom ``_compute_cost`` might be computation-heavy. If this is not the case, make :ref:`_estimate_cost` return the same value as :ref:`_compute_cost` to provide the algorithm with the most accurate information. - -Methods -------- - -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`_compute_cost` **(** :ref:`int` from_id, :ref:`int` to_id **)** virtual | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`_estimate_cost` **(** :ref:`int` from_id, :ref:`int` to_id **)** virtual | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_point` **(** :ref:`int` id, :ref:`Vector3` position, :ref:`float` weight_scale=1.0 **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`are_points_connected` **(** :ref:`int` id, :ref:`int` to_id, :ref:`bool` bidirectional=true **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear` **(** **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`connect_points` **(** :ref:`int` id, :ref:`int` to_id, :ref:`bool` bidirectional=true **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`disconnect_points` **(** :ref:`int` id, :ref:`int` to_id, :ref:`bool` bidirectional=true **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_available_point_id` **(** **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_closest_point` **(** :ref:`Vector3` to_position, :ref:`bool` include_disabled=false **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_closest_position_in_segment` **(** :ref:`Vector3` to_position **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedInt32Array` | :ref:`get_id_path` **(** :ref:`int` from_id, :ref:`int` to_id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_point_capacity` **(** **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedInt32Array` | :ref:`get_point_connections` **(** :ref:`int` id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_point_count` **(** **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedVector3Array` | :ref:`get_point_path` **(** :ref:`int` from_id, :ref:`int` to_id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_point_position` **(** :ref:`int` id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_point_weight_scale` **(** :ref:`int` id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_points` **(** **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_point` **(** :ref:`int` id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_point_disabled` **(** :ref:`int` id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_point` **(** :ref:`int` id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`reserve_space` **(** :ref:`int` num_nodes **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_point_disabled` **(** :ref:`int` id, :ref:`bool` disabled=true **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_point_position` **(** :ref:`int` id, :ref:`Vector3` position **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_point_weight_scale` **(** :ref:`int` id, :ref:`float` weight_scale **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Method Descriptions -------------------- - -.. _class_AStar_method__compute_cost: - -- :ref:`float` **_compute_cost** **(** :ref:`int` from_id, :ref:`int` to_id **)** virtual - -Called when computing the cost between two connected points. - -Note that this function is hidden in the default ``AStar`` class. - ----- - -.. _class_AStar_method__estimate_cost: - -- :ref:`float` **_estimate_cost** **(** :ref:`int` from_id, :ref:`int` to_id **)** virtual - -Called when estimating the cost between a point and the path's ending point. - -Note that this function is hidden in the default ``AStar`` class. - ----- - -.. _class_AStar_method_add_point: - -- void **add_point** **(** :ref:`int` id, :ref:`Vector3` position, :ref:`float` weight_scale=1.0 **)** - -Adds a new point at the given position with the given identifier. The algorithm prefers points with lower ``weight_scale`` to form a path. The ``id`` must be 0 or larger, and the ``weight_scale`` must be 1 or larger. - -:: - - var astar = AStar.new() - astar.add_point(1, Vector3(1, 0, 0), 4) # Adds the point (1, 0, 0) with weight_scale 4 and id 1 - -If there already exists a point for the given ``id``, its position and weight scale are updated to the given values. - ----- - -.. _class_AStar_method_are_points_connected: - -- :ref:`bool` **are_points_connected** **(** :ref:`int` id, :ref:`int` to_id, :ref:`bool` bidirectional=true **)** const - -Returns whether the two given points are directly connected by a segment. If ``bidirectional`` is ``false``, returns whether movement from ``id`` to ``to_id`` is possible through this segment. - ----- - -.. _class_AStar_method_clear: - -- void **clear** **(** **)** - -Clears all the points and segments. - ----- - -.. _class_AStar_method_connect_points: - -- void **connect_points** **(** :ref:`int` id, :ref:`int` to_id, :ref:`bool` bidirectional=true **)** - -Creates a segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is allowed, not the reverse direction. - -:: - - var astar = AStar.new() - astar.add_point(1, Vector3(1, 1, 0)) - astar.add_point(2, Vector3(0, 5, 0)) - astar.connect_points(1, 2, false) - ----- - -.. _class_AStar_method_disconnect_points: - -- void **disconnect_points** **(** :ref:`int` id, :ref:`int` to_id, :ref:`bool` bidirectional=true **)** - -Deletes the segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is prevented, and a unidirectional segment possibly remains. - ----- - -.. _class_AStar_method_get_available_point_id: - -- :ref:`int` **get_available_point_id** **(** **)** const - -Returns the next available point ID with no point associated to it. - ----- - -.. _class_AStar_method_get_closest_point: - -- :ref:`int` **get_closest_point** **(** :ref:`Vector3` to_position, :ref:`bool` include_disabled=false **)** const - -Returns the ID of the closest point to ``to_position``, optionally taking disabled points into account. Returns -1 if there are no points in the points pool. - ----- - -.. _class_AStar_method_get_closest_position_in_segment: - -- :ref:`Vector3` **get_closest_position_in_segment** **(** :ref:`Vector3` to_position **)** const - -Returns the closest position to ``to_position`` that resides inside a segment between two connected points. - -:: - - var astar = AStar.new() - astar.add_point(1, Vector3(0, 0, 0)) - astar.add_point(2, Vector3(0, 5, 0)) - astar.connect_points(1, 2) - var res = astar.get_closest_position_in_segment(Vector3(3, 3, 0)) # Returns (0, 3, 0) - -The result is in the segment that goes from ``y = 0`` to ``y = 5``. It's the closest position in the segment to the given point. - ----- - -.. _class_AStar_method_get_id_path: - -- :ref:`PackedInt32Array` **get_id_path** **(** :ref:`int` from_id, :ref:`int` to_id **)** - -Returns an array with the IDs of the points that form the path found by AStar between the given points. The array is ordered from the starting point to the ending point of the path. - -:: - - var astar = AStar.new() - astar.add_point(1, Vector3(0, 0, 0)) - astar.add_point(2, Vector3(0, 1, 0), 1) # Default weight is 1 - astar.add_point(3, Vector3(1, 1, 0)) - astar.add_point(4, Vector3(2, 0, 0)) - - astar.connect_points(1, 2, false) - astar.connect_points(2, 3, false) - astar.connect_points(4, 3, false) - astar.connect_points(1, 4, false) - - var res = astar.get_id_path(1, 3) # Returns [1, 2, 3] - -If you change the 2nd point's weight to 3, then the result will be ``[1, 4, 3]`` instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2. - ----- - -.. _class_AStar_method_get_point_capacity: - -- :ref:`int` **get_point_capacity** **(** **)** const - -Returns the capacity of the structure backing the points, useful in conjunction with ``reserve_space``. - ----- - -.. _class_AStar_method_get_point_connections: - -- :ref:`PackedInt32Array` **get_point_connections** **(** :ref:`int` id **)** - -Returns an array with the IDs of the points that form the connection with the given point. - -:: - - var astar = AStar.new() - astar.add_point(1, Vector3(0, 0, 0)) - astar.add_point(2, Vector3(0, 1, 0)) - astar.add_point(3, Vector3(1, 1, 0)) - astar.add_point(4, Vector3(2, 0, 0)) - - astar.connect_points(1, 2, true) - astar.connect_points(1, 3, true) - - var neighbors = astar.get_point_connections(1) # Returns [2, 3] - ----- - -.. _class_AStar_method_get_point_count: - -- :ref:`int` **get_point_count** **(** **)** const - -Returns the number of points currently in the points pool. - ----- - -.. _class_AStar_method_get_point_path: - -- :ref:`PackedVector3Array` **get_point_path** **(** :ref:`int` from_id, :ref:`int` to_id **)** - -Returns an array with the points that are in the path found by AStar between the given points. The array is ordered from the starting point to the ending point of the path. - ----- - -.. _class_AStar_method_get_point_position: - -- :ref:`Vector3` **get_point_position** **(** :ref:`int` id **)** const - -Returns the position of the point associated with the given ``id``. - ----- - -.. _class_AStar_method_get_point_weight_scale: - -- :ref:`float` **get_point_weight_scale** **(** :ref:`int` id **)** const - -Returns the weight scale of the point associated with the given ``id``. - ----- - -.. _class_AStar_method_get_points: - -- :ref:`Array` **get_points** **(** **)** - -Returns an array of all points. - ----- - -.. _class_AStar_method_has_point: - -- :ref:`bool` **has_point** **(** :ref:`int` id **)** const - -Returns whether a point associated with the given ``id`` exists. - ----- - -.. _class_AStar_method_is_point_disabled: - -- :ref:`bool` **is_point_disabled** **(** :ref:`int` id **)** const - -Returns whether a point is disabled or not for pathfinding. By default, all points are enabled. - ----- - -.. _class_AStar_method_remove_point: - -- void **remove_point** **(** :ref:`int` id **)** - -Removes the point associated with the given ``id`` from the points pool. - ----- - -.. _class_AStar_method_reserve_space: - -- void **reserve_space** **(** :ref:`int` num_nodes **)** - -Reserves space internally for ``num_nodes`` points, useful if you're adding a known large number of points at once, for a grid for instance. New capacity must be greater or equals to old capacity. - ----- - -.. _class_AStar_method_set_point_disabled: - -- void **set_point_disabled** **(** :ref:`int` id, :ref:`bool` disabled=true **)** - -Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle. - ----- - -.. _class_AStar_method_set_point_position: - -- void **set_point_position** **(** :ref:`int` id, :ref:`Vector3` position **)** - -Sets the ``position`` for the point with the given ``id``. - ----- - -.. _class_AStar_method_set_point_weight_scale: - -- void **set_point_weight_scale** **(** :ref:`int` id, :ref:`float` weight_scale **)** - -Sets the ``weight_scale`` for the point with the given ``id``. - diff --git a/classes/class_astar2d.rst b/classes/class_astar2d.rst index 7f5d0aa0e5b..ecbe19af6cb 100644 --- a/classes/class_astar2d.rst +++ b/classes/class_astar2d.rst @@ -1,178 +1,318 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AStar2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AStar2D.xml. .. _class_AStar2D: AStar2D ======= -**Inherits:** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` -AStar class representation that uses 2D vectors as edges. +An implementation of A\* for finding the shortest path between two vertices on a connected graph in 2D space. + +.. rst-class:: classref-introduction-group Description ----------- -This is a wrapper for the :ref:`AStar` class which uses 2D vectors instead of 3D vectors. +An implementation of the A\* algorithm, used to find the shortest path between two vertices on a connected graph in 2D space. + +See :ref:`AStar3D` for a more thorough explanation on how to use this class. **AStar2D** is a wrapper for :ref:`AStar3D` that enforces 2D coordinates. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Grid-based Navigation with AStarGrid2D Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+--------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`neighbor_filter_enabled` | ``false`` | + +-------------------------+--------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`_compute_cost` **(** :ref:`int` from_id, :ref:`int` to_id **)** virtual | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`_estimate_cost` **(** :ref:`int` from_id, :ref:`int` to_id **)** virtual | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_point` **(** :ref:`int` id, :ref:`Vector2` position, :ref:`float` weight_scale=1.0 **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`are_points_connected` **(** :ref:`int` id, :ref:`int` to_id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear` **(** **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`connect_points` **(** :ref:`int` id, :ref:`int` to_id, :ref:`bool` bidirectional=true **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`disconnect_points` **(** :ref:`int` id, :ref:`int` to_id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_available_point_id` **(** **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_closest_point` **(** :ref:`Vector2` to_position, :ref:`bool` include_disabled=false **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_closest_position_in_segment` **(** :ref:`Vector2` to_position **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedInt32Array` | :ref:`get_id_path` **(** :ref:`int` from_id, :ref:`int` to_id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_point_capacity` **(** **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedInt32Array` | :ref:`get_point_connections` **(** :ref:`int` id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_point_count` **(** **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedVector2Array` | :ref:`get_point_path` **(** :ref:`int` from_id, :ref:`int` to_id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_point_position` **(** :ref:`int` id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_point_weight_scale` **(** :ref:`int` id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_points` **(** **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_point` **(** :ref:`int` id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_point_disabled` **(** :ref:`int` id **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_point` **(** :ref:`int` id **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`reserve_space` **(** :ref:`int` num_nodes **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_point_disabled` **(** :ref:`int` id, :ref:`bool` disabled=true **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_point_position` **(** :ref:`int` id, :ref:`Vector2` position **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_point_weight_scale` **(** :ref:`int` id, :ref:`float` weight_scale **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_filter_neighbor`\ (\ from_id\: :ref:`int`, neighbor_id\: :ref:`int`\ ) |virtual| |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_point`\ (\ id\: :ref:`int`, position\: :ref:`Vector2`, weight_scale\: :ref:`float` = 1.0\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`are_points_connected`\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear`\ (\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`connect_points`\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`disconnect_points`\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_available_point_id`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_closest_point`\ (\ to_position\: :ref:`Vector2`, include_disabled\: :ref:`bool` = false\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_closest_position_in_segment`\ (\ to_position\: :ref:`Vector2`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt64Array` | :ref:`get_id_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_point_capacity`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt64Array` | :ref:`get_point_connections`\ (\ id\: :ref:`int`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_point_count`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt64Array` | :ref:`get_point_ids`\ (\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_point_position`\ (\ id\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_point_weight_scale`\ (\ id\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_point`\ (\ id\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_point_disabled`\ (\ id\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_point`\ (\ id\: :ref:`int`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`reserve_space`\ (\ num_nodes\: :ref:`int`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_disabled`\ (\ id\: :ref:`int`, disabled\: :ref:`bool` = true\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_position`\ (\ id\: :ref:`int`, position\: :ref:`Vector2`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_weight_scale`\ (\ id\: :ref:`int`, weight_scale\: :ref:`float`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AStar2D_property_neighbor_filter_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **neighbor_filter_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_neighbor_filter_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_neighbor_filter_enabled**\ (\ ) + +If ``true`` enables the filtering of neighbors via :ref:`_filter_neighbor()`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_AStar2D_method__compute_cost: +.. _class_AStar2D_private_method__compute_cost: -- :ref:`float` **_compute_cost** **(** :ref:`int` from_id, :ref:`int` to_id **)** virtual +.. rst-class:: classref-method + +:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` Called when computing the cost between two connected points. -Note that this function is hidden in the default ``AStar2D`` class. +Note that this function is hidden in the default **AStar2D** class. + +.. rst-class:: classref-item-separator ---- -.. _class_AStar2D_method__estimate_cost: +.. _class_AStar2D_private_method__estimate_cost: -- :ref:`float` **_estimate_cost** **(** :ref:`int` from_id, :ref:`int` to_id **)** virtual +.. rst-class:: classref-method + +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` Called when estimating the cost between a point and the path's ending point. -Note that this function is hidden in the default ``AStar2D`` class. +Note that this function is hidden in the default **AStar2D** class. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar2D_private_method__filter_neighbor: + +.. rst-class:: classref-method + +:ref:`bool` **_filter_neighbor**\ (\ from_id\: :ref:`int`, neighbor_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` + +Called when neighboring enters processing and if :ref:`neighbor_filter_enabled` is ``true``. If ``true`` is returned the point will not be processed. + +Note that this function is hidden in the default **AStar2D** class. + +.. rst-class:: classref-item-separator ---- .. _class_AStar2D_method_add_point: -- void **add_point** **(** :ref:`int` id, :ref:`Vector2` position, :ref:`float` weight_scale=1.0 **)** +.. rst-class:: classref-method + +|void| **add_point**\ (\ id\: :ref:`int`, position\: :ref:`Vector2`, weight_scale\: :ref:`float` = 1.0\ ) :ref:`🔗` + +Adds a new point at the given position with the given identifier. The ``id`` must be 0 or larger, and the ``weight_scale`` must be 0.0 or greater. + +The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. Thus, all else being equal, the algorithm prefers points with lower ``weight_scale``\ s to form a path. -Adds a new point at the given position with the given identifier. The algorithm prefers points with lower ``weight_scale`` to form a path. The ``id`` must be 0 or larger, and the ``weight_scale`` must be 1 or larger. -:: +.. tabs:: + + .. code-tab:: gdscript var astar = AStar2D.new() astar.add_point(1, Vector2(1, 0), 4) # Adds the point (1, 0) with weight_scale 4 and id 1 + .. code-tab:: csharp + + var astar = new AStar2D(); + astar.AddPoint(1, new Vector2(1, 0), 4); // Adds the point (1, 0) with weight_scale 4 and id 1 + + + If there already exists a point for the given ``id``, its position and weight scale are updated to the given values. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_are_points_connected: -- :ref:`bool` **are_points_connected** **(** :ref:`int` id, :ref:`int` to_id **)** const +.. rst-class:: classref-method + +:ref:`bool` **are_points_connected**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) |const| :ref:`🔗` + +Returns whether there is a connection/segment between the given points. If ``bidirectional`` is ``false``, returns whether movement from ``id`` to ``to_id`` is possible through this segment. -Returns whether there is a connection/segment between the given points. +.. rst-class:: classref-item-separator ---- .. _class_AStar2D_method_clear: -- void **clear** **(** **)** +.. rst-class:: classref-method + +|void| **clear**\ (\ ) :ref:`🔗` Clears all the points and segments. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_connect_points: -- void **connect_points** **(** :ref:`int` id, :ref:`int` to_id, :ref:`bool` bidirectional=true **)** +.. rst-class:: classref-method + +|void| **connect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) :ref:`🔗` Creates a segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is allowed, not the reverse direction. -:: + +.. tabs:: + + .. code-tab:: gdscript var astar = AStar2D.new() astar.add_point(1, Vector2(1, 1)) astar.add_point(2, Vector2(0, 5)) astar.connect_points(1, 2, false) + .. code-tab:: csharp + + var astar = new AStar2D(); + astar.AddPoint(1, new Vector2(1, 1)); + astar.AddPoint(2, new Vector2(0, 5)); + astar.ConnectPoints(1, 2, false); + + + +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_disconnect_points: -- void **disconnect_points** **(** :ref:`int` id, :ref:`int` to_id **)** +.. rst-class:: classref-method + +|void| **disconnect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) :ref:`🔗` + +Deletes the segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is prevented, and a unidirectional segment possibly remains. -Deletes the segment between the given points. +.. rst-class:: classref-item-separator ---- .. _class_AStar2D_method_get_available_point_id: -- :ref:`int` **get_available_point_id** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_available_point_id**\ (\ ) |const| :ref:`🔗` Returns the next available point ID with no point associated to it. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_get_closest_point: -- :ref:`int` **get_closest_point** **(** :ref:`Vector2` to_position, :ref:`bool` include_disabled=false **)** const +.. rst-class:: classref-method + +:ref:`int` **get_closest_point**\ (\ to_position\: :ref:`Vector2`, include_disabled\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns the ID of the closest point to ``to_position``, optionally taking disabled points into account. Returns ``-1`` if there are no points in the points pool. -Returns the ID of the closest point to ``to_position``, optionally taking disabled points into account. Returns -1 if there are no points in the points pool. +\ **Note:** If several points are the closest to ``to_position``, the one with the smallest ID will be returned, ensuring a deterministic result. + +.. rst-class:: classref-item-separator ---- .. _class_AStar2D_method_get_closest_position_in_segment: -- :ref:`Vector2` **get_closest_position_in_segment** **(** :ref:`Vector2` to_position **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **get_closest_position_in_segment**\ (\ to_position\: :ref:`Vector2`\ ) |const| :ref:`🔗` Returns the closest position to ``to_position`` that resides inside a segment between two connected points. -:: + +.. tabs:: + + .. code-tab:: gdscript var astar = AStar2D.new() astar.add_point(1, Vector2(0, 0)) @@ -180,155 +320,281 @@ Returns the closest position to ``to_position`` that resides inside a segment be astar.connect_points(1, 2) var res = astar.get_closest_position_in_segment(Vector2(3, 3)) # Returns (0, 3) + .. code-tab:: csharp + + var astar = new AStar2D(); + astar.AddPoint(1, new Vector2(0, 0)); + astar.AddPoint(2, new Vector2(0, 5)); + astar.ConnectPoints(1, 2); + Vector2 res = astar.GetClosestPositionInSegment(new Vector2(3, 3)); // Returns (0, 3) + + + The result is in the segment that goes from ``y = 0`` to ``y = 5``. It's the closest position in the segment to the given point. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_get_id_path: -- :ref:`PackedInt32Array` **get_id_path** **(** :ref:`int` from_id, :ref:`int` to_id **)** +.. rst-class:: classref-method + +:ref:`PackedInt64Array` **get_id_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. -:: +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + + +.. tabs:: + + .. code-tab:: gdscript var astar = AStar2D.new() astar.add_point(1, Vector2(0, 0)) astar.add_point(2, Vector2(0, 1), 1) # Default weight is 1 astar.add_point(3, Vector2(1, 1)) astar.add_point(4, Vector2(2, 0)) - + astar.connect_points(1, 2, false) astar.connect_points(2, 3, false) astar.connect_points(4, 3, false) astar.connect_points(1, 4, false) - + var res = astar.get_id_path(1, 3) # Returns [1, 2, 3] + .. code-tab:: csharp + + var astar = new AStar2D(); + astar.AddPoint(1, new Vector2(0, 0)); + astar.AddPoint(2, new Vector2(0, 1), 1); // Default weight is 1 + astar.AddPoint(3, new Vector2(1, 1)); + astar.AddPoint(4, new Vector2(2, 0)); + + astar.ConnectPoints(1, 2, false); + astar.ConnectPoints(2, 3, false); + astar.ConnectPoints(4, 3, false); + astar.ConnectPoints(1, 4, false); + long[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] + + + If you change the 2nd point's weight to 3, then the result will be ``[1, 4, 3]`` instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_get_point_capacity: -- :ref:`int` **get_point_capacity** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_point_capacity**\ (\ ) |const| :ref:`🔗` -Returns the capacity of the structure backing the points, useful in conjunction with ``reserve_space``. +Returns the capacity of the structure backing the points, useful in conjunction with :ref:`reserve_space()`. + +.. rst-class:: classref-item-separator ---- .. _class_AStar2D_method_get_point_connections: -- :ref:`PackedInt32Array` **get_point_connections** **(** :ref:`int` id **)** +.. rst-class:: classref-method + +:ref:`PackedInt64Array` **get_point_connections**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Returns an array with the IDs of the points that form the connection with the given point. -:: + +.. tabs:: + + .. code-tab:: gdscript var astar = AStar2D.new() astar.add_point(1, Vector2(0, 0)) astar.add_point(2, Vector2(0, 1)) astar.add_point(3, Vector2(1, 1)) astar.add_point(4, Vector2(2, 0)) - + astar.connect_points(1, 2, true) astar.connect_points(1, 3, true) - + var neighbors = astar.get_point_connections(1) # Returns [2, 3] + .. code-tab:: csharp + + var astar = new AStar2D(); + astar.AddPoint(1, new Vector2(0, 0)); + astar.AddPoint(2, new Vector2(0, 1)); + astar.AddPoint(3, new Vector2(1, 1)); + astar.AddPoint(4, new Vector2(2, 0)); + + astar.ConnectPoints(1, 2, true); + astar.ConnectPoints(1, 3, true); + + long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] + + + +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_get_point_count: -- :ref:`int` **get_point_count** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_point_count**\ (\ ) |const| :ref:`🔗` Returns the number of points currently in the points pool. +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar2D_method_get_point_ids: + +.. rst-class:: classref-method + +:ref:`PackedInt64Array` **get_point_ids**\ (\ ) :ref:`🔗` + +Returns an array of all point IDs. + +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_get_point_path: -- :ref:`PackedVector2Array` **get_point_path** **(** :ref:`int` from_id, :ref:`int` to_id **)** +.. rst-class:: classref-method + +:ref:`PackedVector2Array` **get_point_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` Returns an array with the points that are in the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe; it can only be used from a single :ref:`Thread` at a given time. Consider using :ref:`Mutex` to ensure exclusive access to one thread to avoid race conditions. + +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_get_point_position: -- :ref:`Vector2` **get_point_position** **(** :ref:`int` id **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **get_point_position**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the position of the point associated with the given ``id``. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_get_point_weight_scale: -- :ref:`float` **get_point_weight_scale** **(** :ref:`int` id **)** const +.. rst-class:: classref-method -Returns the weight scale of the point associated with the given ``id``. +:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` ----- - -.. _class_AStar2D_method_get_points: - -- :ref:`Array` **get_points** **(** **)** +Returns the weight scale of the point associated with the given ``id``. -Returns an array of all points. +.. rst-class:: classref-item-separator ---- .. _class_AStar2D_method_has_point: -- :ref:`bool` **has_point** **(** :ref:`int` id **)** const +.. rst-class:: classref-method + +:ref:`bool` **has_point**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether a point associated with the given ``id`` exists. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_is_point_disabled: -- :ref:`bool` **is_point_disabled** **(** :ref:`int` id **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_point_disabled**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether a point is disabled or not for pathfinding. By default, all points are enabled. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_remove_point: -- void **remove_point** **(** :ref:`int` id **)** +.. rst-class:: classref-method + +|void| **remove_point**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Removes the point associated with the given ``id`` from the points pool. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_reserve_space: -- void **reserve_space** **(** :ref:`int` num_nodes **)** +.. rst-class:: classref-method + +|void| **reserve_space**\ (\ num_nodes\: :ref:`int`\ ) :ref:`🔗` -Reserves space internally for ``num_nodes`` points, useful if you're adding a known large number of points at once, for a grid for instance. New capacity must be greater or equals to old capacity. +Reserves space internally for ``num_nodes`` points. Useful if you're adding a known large number of points at once, such as points on a grid. + +.. rst-class:: classref-item-separator ---- .. _class_AStar2D_method_set_point_disabled: -- void **set_point_disabled** **(** :ref:`int` id, :ref:`bool` disabled=true **)** +.. rst-class:: classref-method + +|void| **set_point_disabled**\ (\ id\: :ref:`int`, disabled\: :ref:`bool` = true\ ) :ref:`🔗` Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_set_point_position: -- void **set_point_position** **(** :ref:`int` id, :ref:`Vector2` position **)** +.. rst-class:: classref-method + +|void| **set_point_position**\ (\ id\: :ref:`int`, position\: :ref:`Vector2`\ ) :ref:`🔗` Sets the ``position`` for the point with the given ``id``. +.. rst-class:: classref-item-separator + ---- .. _class_AStar2D_method_set_point_weight_scale: -- void **set_point_weight_scale** **(** :ref:`int` id, :ref:`float` weight_scale **)** +.. rst-class:: classref-method + +|void| **set_point_weight_scale**\ (\ id\: :ref:`int`, weight_scale\: :ref:`float`\ ) :ref:`🔗` -Sets the ``weight_scale`` for the point with the given ``id``. +Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_astar3d.rst b/classes/class_astar3d.rst new file mode 100644 index 00000000000..e2d486e0ada --- /dev/null +++ b/classes/class_astar3d.rst @@ -0,0 +1,642 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AStar3D.xml. + +.. _class_AStar3D: + +AStar3D +======= + +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` + +An implementation of A\* for finding the shortest path between two vertices on a connected graph in 3D space. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A\* (A star) is a computer algorithm used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments). It enjoys widespread use due to its performance and accuracy. Godot's A\* implementation uses points in 3D space and Euclidean distances by default. + +You must add points manually with :ref:`add_point()` and create segments manually with :ref:`connect_points()`. Once done, you can test if there is a path between two points with the :ref:`are_points_connected()` function, get a path containing indices by :ref:`get_id_path()`, or one containing actual coordinates with :ref:`get_point_path()`. + +It is also possible to use non-Euclidean distances. To do so, create a script that extends **AStar3D** and override the methods :ref:`_compute_cost()` and :ref:`_estimate_cost()`. Both should take two point IDs and return the distance between the corresponding points. + +\ **Example:** Use Manhattan distance instead of Euclidean distance: + + +.. tabs:: + + .. code-tab:: gdscript + + class_name MyAStar3D + extends AStar3D + + func _compute_cost(u, v): + var u_pos = get_point_position(u) + var v_pos = get_point_position(v) + return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z) + + func _estimate_cost(u, v): + var u_pos = get_point_position(u) + var v_pos = get_point_position(v) + return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z) + + .. code-tab:: csharp + + using Godot; + + [GlobalClass] + public partial class MyAStar3D : AStar3D + { + public override float _ComputeCost(long fromId, long toId) + { + Vector3 fromPoint = GetPointPosition(fromId); + Vector3 toPoint = GetPointPosition(toId); + + return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z); + } + + public override float _EstimateCost(long fromId, long toId) + { + Vector3 fromPoint = GetPointPosition(fromId); + Vector3 toPoint = GetPointPosition(toId); + return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z); + } + } + + + +\ :ref:`_estimate_cost()` should return a lower bound of the distance, i.e. ``_estimate_cost(u, v) <= _compute_cost(u, v)``. This serves as a hint to the algorithm because the custom :ref:`_compute_cost()` might be computation-heavy. If this is not the case, make :ref:`_estimate_cost()` return the same value as :ref:`_compute_cost()` to provide the algorithm with the most accurate information. + +If the default :ref:`_estimate_cost()` and :ref:`_compute_cost()` methods are used, or if the supplied :ref:`_estimate_cost()` method returns a lower bound of the cost, then the paths returned by A\* will be the lowest-cost paths. Here, the cost of a path equals the sum of the :ref:`_compute_cost()` results of all segments in the path multiplied by the ``weight_scale``\ s of the endpoints of the respective segments. If the default methods are used and the ``weight_scale``\ s of all points are set to ``1.0``, then this equals the sum of Euclidean distances of all segments in the path. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+--------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`neighbor_filter_enabled` | ``false`` | + +-------------------------+--------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_filter_neighbor`\ (\ from_id\: :ref:`int`, neighbor_id\: :ref:`int`\ ) |virtual| |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_point`\ (\ id\: :ref:`int`, position\: :ref:`Vector3`, weight_scale\: :ref:`float` = 1.0\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`are_points_connected`\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear`\ (\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`connect_points`\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`disconnect_points`\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_available_point_id`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_closest_point`\ (\ to_position\: :ref:`Vector3`, include_disabled\: :ref:`bool` = false\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_closest_position_in_segment`\ (\ to_position\: :ref:`Vector3`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt64Array` | :ref:`get_id_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_point_capacity`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt64Array` | :ref:`get_point_connections`\ (\ id\: :ref:`int`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_point_count`\ (\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt64Array` | :ref:`get_point_ids`\ (\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector3Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_point_position`\ (\ id\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_point_weight_scale`\ (\ id\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_point`\ (\ id\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_point_disabled`\ (\ id\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_point`\ (\ id\: :ref:`int`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`reserve_space`\ (\ num_nodes\: :ref:`int`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_disabled`\ (\ id\: :ref:`int`, disabled\: :ref:`bool` = true\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_position`\ (\ id\: :ref:`int`, position\: :ref:`Vector3`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_weight_scale`\ (\ id\: :ref:`int`, weight_scale\: :ref:`float`\ ) | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AStar3D_property_neighbor_filter_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **neighbor_filter_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_neighbor_filter_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_neighbor_filter_enabled**\ (\ ) + +If ``true`` enables the filtering of neighbors via :ref:`_filter_neighbor()`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AStar3D_private_method__compute_cost: + +.. rst-class:: classref-method + +:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` + +Called when computing the cost between two connected points. + +Note that this function is hidden in the default **AStar3D** class. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_private_method__estimate_cost: + +.. rst-class:: classref-method + +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` + +Called when estimating the cost between a point and the path's ending point. + +Note that this function is hidden in the default **AStar3D** class. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_private_method__filter_neighbor: + +.. rst-class:: classref-method + +:ref:`bool` **_filter_neighbor**\ (\ from_id\: :ref:`int`, neighbor_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` + +Called when neighboring point enters processing and if :ref:`neighbor_filter_enabled` is ``true``. If ``true`` is returned the point will not be processed. + +Note that this function is hidden in the default **AStar3D** class. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_add_point: + +.. rst-class:: classref-method + +|void| **add_point**\ (\ id\: :ref:`int`, position\: :ref:`Vector3`, weight_scale\: :ref:`float` = 1.0\ ) :ref:`🔗` + +Adds a new point at the given position with the given identifier. The ``id`` must be 0 or larger, and the ``weight_scale`` must be 0.0 or greater. + +The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. Thus, all else being equal, the algorithm prefers points with lower ``weight_scale``\ s to form a path. + + +.. tabs:: + + .. code-tab:: gdscript + + var astar = AStar3D.new() + astar.add_point(1, Vector3(1, 0, 0), 4) # Adds the point (1, 0, 0) with weight_scale 4 and id 1 + + .. code-tab:: csharp + + var astar = new AStar3D(); + astar.AddPoint(1, new Vector3(1, 0, 0), 4); // Adds the point (1, 0, 0) with weight_scale 4 and id 1 + + + +If there already exists a point for the given ``id``, its position and weight scale are updated to the given values. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_are_points_connected: + +.. rst-class:: classref-method + +:ref:`bool` **are_points_connected**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) |const| :ref:`🔗` + +Returns whether the two given points are directly connected by a segment. If ``bidirectional`` is ``false``, returns whether movement from ``id`` to ``to_id`` is possible through this segment. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_clear: + +.. rst-class:: classref-method + +|void| **clear**\ (\ ) :ref:`🔗` + +Clears all the points and segments. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_connect_points: + +.. rst-class:: classref-method + +|void| **connect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) :ref:`🔗` + +Creates a segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is allowed, not the reverse direction. + + +.. tabs:: + + .. code-tab:: gdscript + + var astar = AStar3D.new() + astar.add_point(1, Vector3(1, 1, 0)) + astar.add_point(2, Vector3(0, 5, 0)) + astar.connect_points(1, 2, false) + + .. code-tab:: csharp + + var astar = new AStar3D(); + astar.AddPoint(1, new Vector3(1, 1, 0)); + astar.AddPoint(2, new Vector3(0, 5, 0)); + astar.ConnectPoints(1, 2, false); + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_disconnect_points: + +.. rst-class:: classref-method + +|void| **disconnect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) :ref:`🔗` + +Deletes the segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is prevented, and a unidirectional segment possibly remains. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_available_point_id: + +.. rst-class:: classref-method + +:ref:`int` **get_available_point_id**\ (\ ) |const| :ref:`🔗` + +Returns the next available point ID with no point associated to it. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_closest_point: + +.. rst-class:: classref-method + +:ref:`int` **get_closest_point**\ (\ to_position\: :ref:`Vector3`, include_disabled\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns the ID of the closest point to ``to_position``, optionally taking disabled points into account. Returns ``-1`` if there are no points in the points pool. + +\ **Note:** If several points are the closest to ``to_position``, the one with the smallest ID will be returned, ensuring a deterministic result. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_closest_position_in_segment: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_closest_position_in_segment**\ (\ to_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns the closest position to ``to_position`` that resides inside a segment between two connected points. + + +.. tabs:: + + .. code-tab:: gdscript + + var astar = AStar3D.new() + astar.add_point(1, Vector3(0, 0, 0)) + astar.add_point(2, Vector3(0, 5, 0)) + astar.connect_points(1, 2) + var res = astar.get_closest_position_in_segment(Vector3(3, 3, 0)) # Returns (0, 3, 0) + + .. code-tab:: csharp + + var astar = new AStar3D(); + astar.AddPoint(1, new Vector3(0, 0, 0)); + astar.AddPoint(2, new Vector3(0, 5, 0)); + astar.ConnectPoints(1, 2); + Vector3 res = astar.GetClosestPositionInSegment(new Vector3(3, 3, 0)); // Returns (0, 3, 0) + + + +The result is in the segment that goes from ``y = 0`` to ``y = 5``. It's the closest position in the segment to the given point. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_id_path: + +.. rst-class:: classref-method + +:ref:`PackedInt64Array` **get_id_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` + +Returns an array with the IDs of the points that form the path found by AStar3D between the given points. The array is ordered from the starting point to the ending point of the path. + +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + + +.. tabs:: + + .. code-tab:: gdscript + + var astar = AStar3D.new() + astar.add_point(1, Vector3(0, 0, 0)) + astar.add_point(2, Vector3(0, 1, 0), 1) # Default weight is 1 + astar.add_point(3, Vector3(1, 1, 0)) + astar.add_point(4, Vector3(2, 0, 0)) + + astar.connect_points(1, 2, false) + astar.connect_points(2, 3, false) + astar.connect_points(4, 3, false) + astar.connect_points(1, 4, false) + + var res = astar.get_id_path(1, 3) # Returns [1, 2, 3] + + .. code-tab:: csharp + + var astar = new AStar3D(); + astar.AddPoint(1, new Vector3(0, 0, 0)); + astar.AddPoint(2, new Vector3(0, 1, 0), 1); // Default weight is 1 + astar.AddPoint(3, new Vector3(1, 1, 0)); + astar.AddPoint(4, new Vector3(2, 0, 0)); + astar.ConnectPoints(1, 2, false); + astar.ConnectPoints(2, 3, false); + astar.ConnectPoints(4, 3, false); + astar.ConnectPoints(1, 4, false); + long[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] + + + +If you change the 2nd point's weight to 3, then the result will be ``[1, 4, 3]`` instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_point_capacity: + +.. rst-class:: classref-method + +:ref:`int` **get_point_capacity**\ (\ ) |const| :ref:`🔗` + +Returns the capacity of the structure backing the points, useful in conjunction with :ref:`reserve_space()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_point_connections: + +.. rst-class:: classref-method + +:ref:`PackedInt64Array` **get_point_connections**\ (\ id\: :ref:`int`\ ) :ref:`🔗` + +Returns an array with the IDs of the points that form the connection with the given point. + + +.. tabs:: + + .. code-tab:: gdscript + + var astar = AStar3D.new() + astar.add_point(1, Vector3(0, 0, 0)) + astar.add_point(2, Vector3(0, 1, 0)) + astar.add_point(3, Vector3(1, 1, 0)) + astar.add_point(4, Vector3(2, 0, 0)) + + astar.connect_points(1, 2, true) + astar.connect_points(1, 3, true) + + var neighbors = astar.get_point_connections(1) # Returns [2, 3] + + .. code-tab:: csharp + + var astar = new AStar3D(); + astar.AddPoint(1, new Vector3(0, 0, 0)); + astar.AddPoint(2, new Vector3(0, 1, 0)); + astar.AddPoint(3, new Vector3(1, 1, 0)); + astar.AddPoint(4, new Vector3(2, 0, 0)); + astar.ConnectPoints(1, 2, true); + astar.ConnectPoints(1, 3, true); + + long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_point_count: + +.. rst-class:: classref-method + +:ref:`int` **get_point_count**\ (\ ) |const| :ref:`🔗` + +Returns the number of points currently in the points pool. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_point_ids: + +.. rst-class:: classref-method + +:ref:`PackedInt64Array` **get_point_ids**\ (\ ) :ref:`🔗` + +Returns an array of all point IDs. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_point_path: + +.. rst-class:: classref-method + +:ref:`PackedVector3Array` **get_point_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` + +Returns an array with the points that are in the path found by AStar3D between the given points. The array is ordered from the starting point to the ending point of the path. + +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe; it can only be used from a single :ref:`Thread` at a given time. Consider using :ref:`Mutex` to ensure exclusive access to one thread to avoid race conditions. + +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_point_position: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_point_position**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the position of the point associated with the given ``id``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_get_point_weight_scale: + +.. rst-class:: classref-method + +:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the weight scale of the point associated with the given ``id``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_has_point: + +.. rst-class:: classref-method + +:ref:`bool` **has_point**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether a point associated with the given ``id`` exists. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_is_point_disabled: + +.. rst-class:: classref-method + +:ref:`bool` **is_point_disabled**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether a point is disabled or not for pathfinding. By default, all points are enabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_remove_point: + +.. rst-class:: classref-method + +|void| **remove_point**\ (\ id\: :ref:`int`\ ) :ref:`🔗` + +Removes the point associated with the given ``id`` from the points pool. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_reserve_space: + +.. rst-class:: classref-method + +|void| **reserve_space**\ (\ num_nodes\: :ref:`int`\ ) :ref:`🔗` + +Reserves space internally for ``num_nodes`` points. Useful if you're adding a known large number of points at once, such as points on a grid. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_set_point_disabled: + +.. rst-class:: classref-method + +|void| **set_point_disabled**\ (\ id\: :ref:`int`, disabled\: :ref:`bool` = true\ ) :ref:`🔗` + +Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_set_point_position: + +.. rst-class:: classref-method + +|void| **set_point_position**\ (\ id\: :ref:`int`, position\: :ref:`Vector3`\ ) :ref:`🔗` + +Sets the ``position`` for the point with the given ``id``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStar3D_method_set_point_weight_scale: + +.. rst-class:: classref-method + +|void| **set_point_weight_scale**\ (\ id\: :ref:`int`, weight_scale\: :ref:`float`\ ) :ref:`🔗` + +Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_astargrid2d.rst b/classes/class_astargrid2d.rst new file mode 100644 index 00000000000..9c74a63e693 --- /dev/null +++ b/classes/class_astargrid2d.rst @@ -0,0 +1,709 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AStarGrid2D.xml. + +.. _class_AStarGrid2D: + +AStarGrid2D +=========== + +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` + +An implementation of A\* for finding the shortest path between two points on a partial 2D grid. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**AStarGrid2D** is a variant of :ref:`AStar2D` that is specialized for partial 2D grids. It is simpler to use because it doesn't require you to manually create points and connect them together. This class also supports multiple types of heuristics, modes for diagonal movement, and a jumping mode to speed up calculations. + +To use **AStarGrid2D**, you only need to set the :ref:`region` of the grid, optionally set the :ref:`cell_size`, and then call the :ref:`update()` method: + + +.. tabs:: + + .. code-tab:: gdscript + + var astar_grid = AStarGrid2D.new() + astar_grid.region = Rect2i(0, 0, 32, 32) + astar_grid.cell_size = Vector2(16, 16) + astar_grid.update() + print(astar_grid.get_id_path(Vector2i(0, 0), Vector2i(3, 4))) # Prints [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)] + print(astar_grid.get_point_path(Vector2i(0, 0), Vector2i(3, 4))) # Prints [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)] + + .. code-tab:: csharp + + AStarGrid2D astarGrid = new AStarGrid2D(); + astarGrid.Region = new Rect2I(0, 0, 32, 32); + astarGrid.CellSize = new Vector2I(16, 16); + astarGrid.Update(); + GD.Print(astarGrid.GetIdPath(Vector2I.Zero, new Vector2I(3, 4))); // Prints [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)] + GD.Print(astarGrid.GetPointPath(Vector2I.Zero, new Vector2I(3, 4))); // Prints [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)] + + + +To remove a point from the pathfinding grid, it must be set as "solid" with :ref:`set_point_solid()`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Grid-based Navigation with AStarGrid2D Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`CellShape` | :ref:`cell_shape` | ``0`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`Vector2` | :ref:`cell_size` | ``Vector2(1, 1)`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`Heuristic` | :ref:`default_compute_heuristic` | ``0`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`Heuristic` | :ref:`default_estimate_heuristic` | ``0`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`DiagonalMode` | :ref:`diagonal_mode` | ``0`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`bool` | :ref:`jumping_enabled` | ``false`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`Vector2` | :ref:`offset` | ``Vector2(0, 0)`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`Rect2i` | :ref:`region` | ``Rect2i(0, 0, 0, 0)`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`Vector2i` | :ref:`size` | ``Vector2i(0, 0)`` | + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`Vector2i`, end_id\: :ref:`Vector2i`\ ) |virtual| |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear`\ (\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fill_solid_region`\ (\ region\: :ref:`Rect2i`, solid\: :ref:`bool` = true\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fill_weight_scale_region`\ (\ region\: :ref:`Rect2i`, weight_scale\: :ref:`float`\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Vector2i`\] | :ref:`get_id_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`get_point_data_in_region`\ (\ region\: :ref:`Rect2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_point_position`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_point_weight_scale`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_dirty`\ (\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_in_bounds`\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_in_boundsv`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_point_solid`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_solid`\ (\ id\: :ref:`Vector2i`, solid\: :ref:`bool` = true\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_weight_scale`\ (\ id\: :ref:`Vector2i`, weight_scale\: :ref:`float`\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`update`\ (\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AStarGrid2D_Heuristic: + +.. rst-class:: classref-enumeration + +enum **Heuristic**: :ref:`🔗` + +.. _class_AStarGrid2D_constant_HEURISTIC_EUCLIDEAN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Heuristic` **HEURISTIC_EUCLIDEAN** = ``0`` + +The `Euclidean heuristic `__ to be used for the pathfinding using the following formula: + +:: + + dx = abs(to_id.x - from_id.x) + dy = abs(to_id.y - from_id.y) + result = sqrt(dx * dx + dy * dy) + +\ **Note:** This is also the internal heuristic used in :ref:`AStar3D` and :ref:`AStar2D` by default (with the inclusion of possible z-axis coordinate). + +.. _class_AStarGrid2D_constant_HEURISTIC_MANHATTAN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Heuristic` **HEURISTIC_MANHATTAN** = ``1`` + +The `Manhattan heuristic `__ to be used for the pathfinding using the following formula: + +:: + + dx = abs(to_id.x - from_id.x) + dy = abs(to_id.y - from_id.y) + result = dx + dy + +\ **Note:** This heuristic is intended to be used with 4-side orthogonal movements, provided by setting the :ref:`diagonal_mode` to :ref:`DIAGONAL_MODE_NEVER`. + +.. _class_AStarGrid2D_constant_HEURISTIC_OCTILE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Heuristic` **HEURISTIC_OCTILE** = ``2`` + +The Octile heuristic to be used for the pathfinding using the following formula: + +:: + + dx = abs(to_id.x - from_id.x) + dy = abs(to_id.y - from_id.y) + f = sqrt(2) - 1 + result = (dx < dy) ? f * dx + dy : f * dy + dx; + +.. _class_AStarGrid2D_constant_HEURISTIC_CHEBYSHEV: + +.. rst-class:: classref-enumeration-constant + +:ref:`Heuristic` **HEURISTIC_CHEBYSHEV** = ``3`` + +The `Chebyshev heuristic `__ to be used for the pathfinding using the following formula: + +:: + + dx = abs(to_id.x - from_id.x) + dy = abs(to_id.y - from_id.y) + result = max(dx, dy) + +.. _class_AStarGrid2D_constant_HEURISTIC_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`Heuristic` **HEURISTIC_MAX** = ``4`` + +Represents the size of the :ref:`Heuristic` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AStarGrid2D_DiagonalMode: + +.. rst-class:: classref-enumeration + +enum **DiagonalMode**: :ref:`🔗` + +.. _class_AStarGrid2D_constant_DIAGONAL_MODE_ALWAYS: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiagonalMode` **DIAGONAL_MODE_ALWAYS** = ``0`` + +The pathfinding algorithm will ignore solid neighbors around the target cell and allow passing using diagonals. + +.. _class_AStarGrid2D_constant_DIAGONAL_MODE_NEVER: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiagonalMode` **DIAGONAL_MODE_NEVER** = ``1`` + +The pathfinding algorithm will ignore all diagonals and the way will be always orthogonal. + +.. _class_AStarGrid2D_constant_DIAGONAL_MODE_AT_LEAST_ONE_WALKABLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiagonalMode` **DIAGONAL_MODE_AT_LEAST_ONE_WALKABLE** = ``2`` + +The pathfinding algorithm will avoid using diagonals if at least two obstacles have been placed around the neighboring cells of the specific path segment. + +.. _class_AStarGrid2D_constant_DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiagonalMode` **DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES** = ``3`` + +The pathfinding algorithm will avoid using diagonals if any obstacle has been placed around the neighboring cells of the specific path segment. + +.. _class_AStarGrid2D_constant_DIAGONAL_MODE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiagonalMode` **DIAGONAL_MODE_MAX** = ``4`` + +Represents the size of the :ref:`DiagonalMode` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AStarGrid2D_CellShape: + +.. rst-class:: classref-enumeration + +enum **CellShape**: :ref:`🔗` + +.. _class_AStarGrid2D_constant_CELL_SHAPE_SQUARE: + +.. rst-class:: classref-enumeration-constant + +:ref:`CellShape` **CELL_SHAPE_SQUARE** = ``0`` + +Rectangular cell shape. + +.. _class_AStarGrid2D_constant_CELL_SHAPE_ISOMETRIC_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`CellShape` **CELL_SHAPE_ISOMETRIC_RIGHT** = ``1`` + +Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes up-right, and the vertical one goes down-right. + +.. _class_AStarGrid2D_constant_CELL_SHAPE_ISOMETRIC_DOWN: + +.. rst-class:: classref-enumeration-constant + +:ref:`CellShape` **CELL_SHAPE_ISOMETRIC_DOWN** = ``2`` + +Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes down-right, and the vertical one goes down-left. + +.. _class_AStarGrid2D_constant_CELL_SHAPE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`CellShape` **CELL_SHAPE_MAX** = ``3`` + +Represents the size of the :ref:`CellShape` enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AStarGrid2D_property_cell_shape: + +.. rst-class:: classref-property + +:ref:`CellShape` **cell_shape** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_cell_shape**\ (\ value\: :ref:`CellShape`\ ) +- :ref:`CellShape` **get_cell_shape**\ (\ ) + +The cell shape. Affects how the positions are placed in the grid. If changed, :ref:`update()` needs to be called before finding the next path. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_property_cell_size: + +.. rst-class:: classref-property + +:ref:`Vector2` **cell_size** = ``Vector2(1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_cell_size**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_cell_size**\ (\ ) + +The size of the point cell which will be applied to calculate the resulting point position returned by :ref:`get_point_path()`. If changed, :ref:`update()` needs to be called before finding the next path. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_property_default_compute_heuristic: + +.. rst-class:: classref-property + +:ref:`Heuristic` **default_compute_heuristic** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_default_compute_heuristic**\ (\ value\: :ref:`Heuristic`\ ) +- :ref:`Heuristic` **get_default_compute_heuristic**\ (\ ) + +The default :ref:`Heuristic` which will be used to calculate the cost between two points if :ref:`_compute_cost()` was not overridden. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_property_default_estimate_heuristic: + +.. rst-class:: classref-property + +:ref:`Heuristic` **default_estimate_heuristic** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_default_estimate_heuristic**\ (\ value\: :ref:`Heuristic`\ ) +- :ref:`Heuristic` **get_default_estimate_heuristic**\ (\ ) + +The default :ref:`Heuristic` which will be used to calculate the cost between the point and the end point if :ref:`_estimate_cost()` was not overridden. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_property_diagonal_mode: + +.. rst-class:: classref-property + +:ref:`DiagonalMode` **diagonal_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_diagonal_mode**\ (\ value\: :ref:`DiagonalMode`\ ) +- :ref:`DiagonalMode` **get_diagonal_mode**\ (\ ) + +A specific :ref:`DiagonalMode` mode which will force the path to avoid or accept the specified diagonals. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_property_jumping_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **jumping_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_jumping_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_jumping_enabled**\ (\ ) + +Enables or disables jumping to skip up the intermediate points and speeds up the searching algorithm. + +\ **Note:** Currently, toggling it on disables the consideration of weight scaling in pathfinding. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_property_offset: + +.. rst-class:: classref-property + +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_offset**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_offset**\ (\ ) + +The offset of the grid which will be applied to calculate the resulting point position returned by :ref:`get_point_path()`. If changed, :ref:`update()` needs to be called before finding the next path. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_property_region: + +.. rst-class:: classref-property + +:ref:`Rect2i` **region** = ``Rect2i(0, 0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_region**\ (\ value\: :ref:`Rect2i`\ ) +- :ref:`Rect2i` **get_region**\ (\ ) + +The region of grid cells available for pathfinding. If changed, :ref:`update()` needs to be called before finding the next path. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_property_size: + +.. rst-class:: classref-property + +:ref:`Vector2i` **size** = ``Vector2i(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_size**\ (\ value\: :ref:`Vector2i`\ ) +- :ref:`Vector2i` **get_size**\ (\ ) + +**Deprecated:** Use :ref:`region` instead. + +The size of the grid (number of cells of size :ref:`cell_size` on each axis). If changed, :ref:`update()` needs to be called before finding the next path. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AStarGrid2D_private_method__compute_cost: + +.. rst-class:: classref-method + +:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| :ref:`🔗` + +Called when computing the cost between two connected points. + +Note that this function is hidden in the default **AStarGrid2D** class. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_private_method__estimate_cost: + +.. rst-class:: classref-method + +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`Vector2i`, end_id\: :ref:`Vector2i`\ ) |virtual| |const| :ref:`🔗` + +Called when estimating the cost between a point and the path's ending point. + +Note that this function is hidden in the default **AStarGrid2D** class. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_clear: + +.. rst-class:: classref-method + +|void| **clear**\ (\ ) :ref:`🔗` + +Clears the grid and sets the :ref:`region` to ``Rect2i(0, 0, 0, 0)``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_fill_solid_region: + +.. rst-class:: classref-method + +|void| **fill_solid_region**\ (\ region\: :ref:`Rect2i`, solid\: :ref:`bool` = true\ ) :ref:`🔗` + +Fills the given ``region`` on the grid with the specified value for the solid flag. + +\ **Note:** Calling :ref:`update()` is not needed after the call of this function. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_fill_weight_scale_region: + +.. rst-class:: classref-method + +|void| **fill_weight_scale_region**\ (\ region\: :ref:`Rect2i`, weight_scale\: :ref:`float`\ ) :ref:`🔗` + +Fills the given ``region`` on the grid with the specified value for the weight scale. + +\ **Note:** Calling :ref:`update()` is not needed after the call of this function. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_get_id_path: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Vector2i`\] **get_id_path**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` + +Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. + +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is solid the search may take an unusually long time to finish. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_get_point_data_in_region: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Dictionary`\] **get_point_data_in_region**\ (\ region\: :ref:`Rect2i`\ ) |const| :ref:`🔗` + +Returns an array of dictionaries with point data (``id``: :ref:`Vector2i`, ``position``: :ref:`Vector2`, ``solid``: :ref:`bool`, ``weight_scale``: :ref:`float`) within a ``region``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_get_point_path: + +.. rst-class:: classref-method + +:ref:`PackedVector2Array` **get_point_path**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` + +Returns an array with the points that are in the path found by **AStarGrid2D** between the given points. The array is ordered from the starting point to the ending point of the path. + +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe; it can only be used from a single :ref:`Thread` at a given time. Consider using :ref:`Mutex` to ensure exclusive access to one thread to avoid race conditions. + +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is solid the search may take an unusually long time to finish. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_get_point_position: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_point_position**\ (\ id\: :ref:`Vector2i`\ ) |const| :ref:`🔗` + +Returns the position of the point associated with the given ``id``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_get_point_weight_scale: + +.. rst-class:: classref-method + +:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`Vector2i`\ ) |const| :ref:`🔗` + +Returns the weight scale of the point associated with the given ``id``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_is_dirty: + +.. rst-class:: classref-method + +:ref:`bool` **is_dirty**\ (\ ) |const| :ref:`🔗` + +Indicates that the grid parameters were changed and :ref:`update()` needs to be called. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_is_in_bounds: + +.. rst-class:: classref-method + +:ref:`bool` **is_in_bounds**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the ``x`` and ``y`` is a valid grid coordinate (id), i.e. if it is inside :ref:`region`. Equivalent to ``region.has_point(Vector2i(x, y))``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_is_in_boundsv: + +.. rst-class:: classref-method + +:ref:`bool` **is_in_boundsv**\ (\ id\: :ref:`Vector2i`\ ) |const| :ref:`🔗` + +Returns ``true`` if the ``id`` vector is a valid grid coordinate, i.e. if it is inside :ref:`region`. Equivalent to ``region.has_point(id)``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_is_point_solid: + +.. rst-class:: classref-method + +:ref:`bool` **is_point_solid**\ (\ id\: :ref:`Vector2i`\ ) |const| :ref:`🔗` + +Returns ``true`` if a point is disabled for pathfinding. By default, all points are enabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_set_point_solid: + +.. rst-class:: classref-method + +|void| **set_point_solid**\ (\ id\: :ref:`Vector2i`, solid\: :ref:`bool` = true\ ) :ref:`🔗` + +Disables or enables the specified point for pathfinding. Useful for making an obstacle. By default, all points are enabled. + +\ **Note:** Calling :ref:`update()` is not needed after the call of this function. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_set_point_weight_scale: + +.. rst-class:: classref-method + +|void| **set_point_weight_scale**\ (\ id\: :ref:`Vector2i`, weight_scale\: :ref:`float`\ ) :ref:`🔗` + +Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. + +\ **Note:** Calling :ref:`update()` is not needed after the call of this function. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_update: + +.. rst-class:: classref-method + +|void| **update**\ (\ ) :ref:`🔗` + +Updates the internal state of the grid according to the parameters to prepare it to search the path. Needs to be called if parameters like :ref:`region`, :ref:`cell_size` or :ref:`offset` are changed. :ref:`is_dirty()` will return ``true`` if this is the case and this needs to be called. + +\ **Note:** All point data (solidity and weight scale) will be cleared. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_atlastexture.rst b/classes/class_atlastexture.rst index 1420ac51278..9dc025ebfd0 100644 --- a/classes/class_atlastexture.rst +++ b/classes/class_atlastexture.rst @@ -1,96 +1,129 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AtlasTexture.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AtlasTexture.xml. .. _class_AtlasTexture: AtlasTexture ============ -**Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Packs multiple small textures in a single, bigger one. Helps to optimize video memory costs and render calls. +A texture that crops out part of another Texture2D. + +.. rst-class:: classref-introduction-group Description ----------- -:ref:`Texture2D` resource aimed at managing big textures files that pack multiple smaller textures. Consists of a :ref:`Texture2D`, a margin that defines the border width, and a region that defines the actual area of the AtlasTexture. +:ref:`Texture2D` resource that draws only part of its :ref:`atlas` texture, as defined by the :ref:`region`. An additional :ref:`margin` can also be set, which is useful for small adjustments. + +Multiple **AtlasTexture** resources can be cropped from the same :ref:`atlas`. Packing many smaller textures into a singular large texture helps to optimize video memory costs and render calls. + +\ **Note:** **AtlasTexture** cannot be used in an :ref:`AnimatedTexture`, and will not tile properly in nodes such as :ref:`TextureRect` or :ref:`Sprite2D`. To tile an **AtlasTexture**, modify its :ref:`region` instead. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------+-------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`atlas` | | -+-----------------------------------+-------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`filter_clip` | ``false`` | -+-----------------------------------+-------------------------------------------------------------+-------------------------+ -| :ref:`Rect2` | :ref:`margin` | ``Rect2( 0, 0, 0, 0 )`` | -+-----------------------------------+-------------------------------------------------------------+-------------------------+ -| :ref:`Rect2` | :ref:`region` | ``Rect2( 0, 0, 0, 0 )`` | -+-----------------------------------+-------------------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +-----------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`atlas` | | + +-----------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`filter_clip` | ``false`` | + +-----------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`Rect2` | :ref:`margin` | ``Rect2(0, 0, 0, 0)`` | + +-----------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`Rect2` | :ref:`region` | ``Rect2(0, 0, 0, 0)`` | + +-----------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | resource_local_to_scene | ``false`` (overrides :ref:`Resource`) | + +-----------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AtlasTexture_property_atlas: -- :ref:`Texture2D` **atlas** +.. rst-class:: classref-property + +:ref:`Texture2D` **atlas** :ref:`🔗` -+----------+------------------+ -| *Setter* | set_atlas(value) | -+----------+------------------+ -| *Getter* | get_atlas() | -+----------+------------------+ +.. rst-class:: classref-property-setget -The texture that contains the atlas. Can be any :ref:`Texture2D` subtype. +- |void| **set_atlas**\ (\ value\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_atlas**\ (\ ) + +The texture that contains the atlas. Can be any type inheriting from :ref:`Texture2D`, including another **AtlasTexture**. + +.. rst-class:: classref-item-separator ---- .. _class_AtlasTexture_property_filter_clip: -- :ref:`bool` **filter_clip** +.. rst-class:: classref-property + +:ref:`bool` **filter_clip** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_filter_clip**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **has_filter_clip**\ (\ ) -+-----------+------------------------+ -| *Default* | ``false`` | -+-----------+------------------------+ -| *Setter* | set_filter_clip(value) | -+-----------+------------------------+ -| *Getter* | has_filter_clip() | -+-----------+------------------------+ +If ``true``, the area outside of the :ref:`region` is clipped to avoid bleeding of the surrounding texture pixels. -If ``true``, clips the area outside of the region to avoid bleeding of the surrounding texture pixels. +.. rst-class:: classref-item-separator ---- .. _class_AtlasTexture_property_margin: -- :ref:`Rect2` **margin** +.. rst-class:: classref-property -+-----------+-------------------------+ -| *Default* | ``Rect2( 0, 0, 0, 0 )`` | -+-----------+-------------------------+ -| *Setter* | set_margin(value) | -+-----------+-------------------------+ -| *Getter* | get_margin() | -+-----------+-------------------------+ +:ref:`Rect2` **margin** = ``Rect2(0, 0, 0, 0)`` :ref:`🔗` -The margin around the region. The :ref:`Rect2`'s :ref:`Rect2.size` parameter ("w" and "h" in the editor) resizes the texture so it fits within the margin. +.. rst-class:: classref-property-setget + +- |void| **set_margin**\ (\ value\: :ref:`Rect2`\ ) +- :ref:`Rect2` **get_margin**\ (\ ) + +The margin around the :ref:`region`. Useful for small adjustments. If the :ref:`Rect2.size` of this property ("w" and "h" in the editor) is set, the drawn texture is resized to fit within the margin. + +.. rst-class:: classref-item-separator ---- .. _class_AtlasTexture_property_region: -- :ref:`Rect2` **region** +.. rst-class:: classref-property + +:ref:`Rect2` **region** = ``Rect2(0, 0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``Rect2( 0, 0, 0, 0 )`` | -+-----------+-------------------------+ -| *Setter* | set_region(value) | -+-----------+-------------------------+ -| *Getter* | get_region() | -+-----------+-------------------------+ +- |void| **set_region**\ (\ value\: :ref:`Rect2`\ ) +- :ref:`Rect2` **get_region**\ (\ ) -The AtlasTexture's used region. +The region used to draw the :ref:`atlas`. If either dimension of the region's size is ``0``, the value from :ref:`atlas` size will be used for that axis instead. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiobuslayout.rst b/classes/class_audiobuslayout.rst index b692b32ee26..9ad3ccbf1f5 100644 --- a/classes/class_audiobuslayout.rst +++ b/classes/class_audiobuslayout.rst @@ -1,20 +1,32 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioBusLayout.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioBusLayout.xml. .. _class_AudioBusLayout: AudioBusLayout ============== -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Stores information about the audio buses. +.. rst-class:: classref-introduction-group + Description ----------- Stores position, muting, solo, bypass, effects, effect position, volume, and the connections between buses. See :ref:`AudioServer` for usage. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffect.rst b/classes/class_audioeffect.rst index 10b6c311580..fc5631d5312 100644 --- a/classes/class_audioeffect.rst +++ b/classes/class_audioeffect.rst @@ -1,22 +1,88 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffect.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffect.xml. .. _class_AudioEffect: AudioEffect =========== -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AudioEffectAmplify`, :ref:`AudioEffectChorus`, :ref:`AudioEffectCompressor`, :ref:`AudioEffectDelay`, :ref:`AudioEffectDistortion`, :ref:`AudioEffectEQ`, :ref:`AudioEffectFilter`, :ref:`AudioEffectLimiter`, :ref:`AudioEffectPanner`, :ref:`AudioEffectPhaser`, :ref:`AudioEffectPitchShift`, :ref:`AudioEffectRecord`, :ref:`AudioEffectReverb`, :ref:`AudioEffectSpectrumAnalyzer`, :ref:`AudioEffectStereoEnhance` +**Inherited By:** :ref:`AudioEffectAmplify`, :ref:`AudioEffectCapture`, :ref:`AudioEffectChorus`, :ref:`AudioEffectCompressor`, :ref:`AudioEffectDelay`, :ref:`AudioEffectDistortion`, :ref:`AudioEffectEQ`, :ref:`AudioEffectFilter`, :ref:`AudioEffectHardLimiter`, :ref:`AudioEffectLimiter`, :ref:`AudioEffectPanner`, :ref:`AudioEffectPhaser`, :ref:`AudioEffectPitchShift`, :ref:`AudioEffectRecord`, :ref:`AudioEffectReverb`, :ref:`AudioEffectSpectrumAnalyzer`, :ref:`AudioEffectStereoEnhance` -Audio effect for audio. +Base class for audio effect resources. + +.. rst-class:: classref-introduction-group Description ----------- -Base resource for audio bus. Applies an audio effect on the bus that the resource is applied on. +The base :ref:`Resource` for every audio effect. In the editor, an audio effect can be added to the current bus layout through the Audio panel. At run-time, it is also possible to manipulate audio effects through :ref:`AudioServer.add_bus_effect()`, :ref:`AudioServer.remove_bus_effect()`, and :ref:`AudioServer.get_bus_effect()`. + +When applied on a bus, an audio effect creates a corresponding :ref:`AudioEffectInstance`. The instance is directly responsible for manipulating the sound, based on the original audio effect's properties. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +- `Audio Microphone Record Demo `__ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + | :ref:`AudioEffectInstance` | :ref:`_instantiate`\ (\ ) |virtual| |required| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioEffect_private_method__instantiate: + +.. rst-class:: classref-method + +:ref:`AudioEffectInstance` **_instantiate**\ (\ ) |virtual| |required| :ref:`🔗` + +Override this method to customize the :ref:`AudioEffectInstance` created when this effect is applied on a bus in the editor's Audio panel, or through :ref:`AudioServer.add_bus_effect()`. + +:: + + extends AudioEffect + + @export var strength = 4.0 + + func _instantiate(): + var effect = CustomAudioEffectInstance.new() + effect.base = self + + return effect + +\ **Note:** It is recommended to keep a reference to the original **AudioEffect** in the new instance. Depending on the implementation this allows the effect instance to listen for changes at run-time and be modified accordingly. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectamplify.rst b/classes/class_audioeffectamplify.rst index 4ba61f7943c..764c65e237d 100644 --- a/classes/class_audioeffectamplify.rst +++ b/classes/class_audioeffectamplify.rst @@ -1,46 +1,94 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectAmplify.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectAmplify.xml. .. _class_AudioEffectAmplify: AudioEffectAmplify ================== -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds an amplifying audio effect to an audio bus. -Increases or decreases the volume of the selected audio bus. +.. rst-class:: classref-introduction-group Description ----------- Increases or decreases the volume being routed through the audio bus. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+---------------------------+---------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`volume_db` | ``0.0`` | -+---------------------------+---------------------------------------------------------------+---------+ +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`volume_db` | ``0.0`` | + +---------------------------+-----------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`volume_linear` | | + +---------------------------+-----------------------------------------------------------------------+---------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectAmplify_property_volume_db: -- :ref:`float` **volume_db** +.. rst-class:: classref-property + +:ref:`float` **volume_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``0.0`` | -+-----------+----------------------+ -| *Setter* | set_volume_db(value) | -+-----------+----------------------+ -| *Getter* | get_volume_db() | -+-----------+----------------------+ +- |void| **set_volume_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_db**\ (\ ) Amount of amplification in decibels. Positive values make the sound louder, negative values make it quieter. Value can range from -80 to 24. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectAmplify_property_volume_linear: + +.. rst-class:: classref-property + +:ref:`float` **volume_linear** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_linear**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_linear**\ (\ ) + +Amount of amplification as a linear value. + +\ **Note:** This member modifies :ref:`volume_db` for convenience. The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on :ref:`volume_db`. Setting this member is equivalent to setting :ref:`volume_db` to the result of :ref:`@GlobalScope.linear_to_db()` on a value. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectbandlimitfilter.rst b/classes/class_audioeffectbandlimitfilter.rst index 251edfe1eea..1fdfe575356 100644 --- a/classes/class_audioeffectbandlimitfilter.rst +++ b/classes/class_audioeffectbandlimitfilter.rst @@ -1,20 +1,39 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectBandLimitFilter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectBandLimitFilter.xml. .. _class_AudioEffectBandLimitFilter: AudioEffectBandLimitFilter ========================== -**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a band limit filter to the audio bus. +.. rst-class:: classref-introduction-group + Description ----------- Limits the frequencies in a range around the :ref:`AudioEffectFilter.cutoff_hz` and allows frequencies outside of this range to pass. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectbandpassfilter.rst b/classes/class_audioeffectbandpassfilter.rst index c07d1c4d3a2..1647ea0cdc9 100644 --- a/classes/class_audioeffectbandpassfilter.rst +++ b/classes/class_audioeffectbandpassfilter.rst @@ -1,20 +1,39 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectBandPassFilter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectBandPassFilter.xml. .. _class_AudioEffectBandPassFilter: AudioEffectBandPassFilter ========================= -**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a band pass filter to the audio bus. +.. rst-class:: classref-introduction-group + Description ----------- Attenuates the frequencies inside of a range around the :ref:`AudioEffectFilter.cutoff_hz` and cuts frequencies outside of this band. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectcapture.rst b/classes/class_audioeffectcapture.rst new file mode 100644 index 00000000000..e4ce9269afb --- /dev/null +++ b/classes/class_audioeffectcapture.rst @@ -0,0 +1,196 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectCapture.xml. + +.. _class_AudioEffectCapture: + +AudioEffectCapture +================== + +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Captures audio from an audio bus in real-time. + +.. rst-class:: classref-introduction-group + +Description +----------- + +AudioEffectCapture is an AudioEffect which copies all audio frames from the attached audio effect bus into its internal ring buffer. + +Application code should consume these audio frames from this ring buffer using :ref:`get_buffer()` and process it as needed, for example to capture data from an :ref:`AudioStreamMicrophone`, implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating-point PCM. + +Unlike :ref:`AudioEffectRecord`, this effect only returns the raw audio samples instead of encoding them into an :ref:`AudioStream`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`buffer_length` | ``0.1`` | + +---------------------------+-----------------------------------------------------------------------+---------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`can_get_buffer`\ (\ frames\: :ref:`int`\ ) |const| | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_buffer`\ (\ ) | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`get_buffer`\ (\ frames\: :ref:`int`\ ) | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_buffer_length_frames`\ (\ ) |const| | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_discarded_frames`\ (\ ) |const| | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_frames_available`\ (\ ) |const| | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_pushed_frames`\ (\ ) |const| | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioEffectCapture_property_buffer_length: + +.. rst-class:: classref-property + +:ref:`float` **buffer_length** = ``0.1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_buffer_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_buffer_length**\ (\ ) + +Length of the internal ring buffer, in seconds. Setting the buffer length will have no effect if already initialized. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioEffectCapture_method_can_get_buffer: + +.. rst-class:: classref-method + +:ref:`bool` **can_get_buffer**\ (\ frames\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if at least ``frames`` audio frames are available to read in the internal ring buffer. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectCapture_method_clear_buffer: + +.. rst-class:: classref-method + +|void| **clear_buffer**\ (\ ) :ref:`🔗` + +Clears the internal ring buffer. + +\ **Note:** Calling this during a capture can cause the loss of samples which causes popping in the playback. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectCapture_method_get_buffer: + +.. rst-class:: classref-method + +:ref:`PackedVector2Array` **get_buffer**\ (\ frames\: :ref:`int`\ ) :ref:`🔗` + +Gets the next ``frames`` audio samples from the internal ring buffer. + +Returns a :ref:`PackedVector2Array` containing exactly ``frames`` audio samples if available, or an empty :ref:`PackedVector2Array` if insufficient data was available. + +The samples are signed floating-point PCM between ``-1`` and ``1``. You will have to scale them if you want to use them as 8 or 16-bit integer samples. (``v = 0x7fff * samples[0].x``) + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectCapture_method_get_buffer_length_frames: + +.. rst-class:: classref-method + +:ref:`int` **get_buffer_length_frames**\ (\ ) |const| :ref:`🔗` + +Returns the total size of the internal ring buffer in frames. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectCapture_method_get_discarded_frames: + +.. rst-class:: classref-method + +:ref:`int` **get_discarded_frames**\ (\ ) |const| :ref:`🔗` + +Returns the number of audio frames discarded from the audio bus due to full buffer. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectCapture_method_get_frames_available: + +.. rst-class:: classref-method + +:ref:`int` **get_frames_available**\ (\ ) |const| :ref:`🔗` + +Returns the number of frames available to read using :ref:`get_buffer()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectCapture_method_get_pushed_frames: + +.. rst-class:: classref-method + +:ref:`int` **get_pushed_frames**\ (\ ) |const| :ref:`🔗` + +Returns the number of audio frames inserted from the audio bus. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectchorus.rst b/classes/class_audioeffectchorus.rst index 15076723243..92dff8bb269 100644 --- a/classes/class_audioeffectchorus.rst +++ b/classes/class_audioeffectchorus.rst @@ -1,590 +1,774 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectChorus.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectChorus.xml. .. _class_AudioEffectChorus: AudioEffectChorus ================= -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a chorus audio effect. +.. rst-class:: classref-introduction-group + Description ----------- Adds a chorus audio effect. The effect applies a filter with voices to duplicate the audio source and manipulate it through the filter. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`dry` | ``1.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/1/cutoff_hz` | ``8000.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/1/delay_ms` | ``15.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/1/depth_ms` | ``2.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/1/level_db` | ``0.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/1/pan` | ``-0.5`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/1/rate_hz` | ``0.8`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/2/cutoff_hz` | ``8000.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/2/delay_ms` | ``20.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/2/depth_ms` | ``3.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/2/level_db` | ``0.0`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/2/pan` | ``0.5`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/2/rate_hz` | ``1.2`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/3/cutoff_hz` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/3/delay_ms` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/3/depth_ms` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/3/level_db` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/3/pan` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/3/rate_hz` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/4/cutoff_hz` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/4/delay_ms` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/4/depth_ms` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/4/level_db` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/4/pan` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`voice/4/rate_hz` | | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`int` | :ref:`voice_count` | ``2`` | -+---------------------------+------------------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`wet` | ``0.5`` | -+---------------------------+------------------------------------------------------------------------------+------------+ +.. table:: + :widths: auto + + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`dry` | ``1.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/1/cutoff_hz` | ``8000.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/1/delay_ms` | ``15.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/1/depth_ms` | ``2.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/1/level_db` | ``0.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/1/pan` | ``-0.5`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/1/rate_hz` | ``0.8`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/2/cutoff_hz` | ``8000.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/2/delay_ms` | ``20.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/2/depth_ms` | ``3.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/2/level_db` | ``0.0`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/2/pan` | ``0.5`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/2/rate_hz` | ``1.2`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/3/cutoff_hz` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/3/delay_ms` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/3/depth_ms` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/3/level_db` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/3/pan` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/3/rate_hz` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/4/cutoff_hz` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/4/delay_ms` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/4/depth_ms` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/4/level_db` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/4/pan` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`voice/4/rate_hz` | | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`int` | :ref:`voice_count` | ``2`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`wet` | ``0.5`` | + +---------------------------+------------------------------------------------------------------------------+------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_voice_cutoff_hz` **(** :ref:`int` voice_idx **)** const | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_voice_delay_ms` **(** :ref:`int` voice_idx **)** const | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_voice_depth_ms` **(** :ref:`int` voice_idx **)** const | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_voice_level_db` **(** :ref:`int` voice_idx **)** const | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_voice_pan` **(** :ref:`int` voice_idx **)** const | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_voice_rate_hz` **(** :ref:`int` voice_idx **)** const | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_voice_cutoff_hz` **(** :ref:`int` voice_idx, :ref:`float` cutoff_hz **)** | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_voice_delay_ms` **(** :ref:`int` voice_idx, :ref:`float` delay_ms **)** | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_voice_depth_ms` **(** :ref:`int` voice_idx, :ref:`float` depth_ms **)** | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_voice_level_db` **(** :ref:`int` voice_idx, :ref:`float` level_db **)** | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_voice_pan` **(** :ref:`int` voice_idx, :ref:`float` pan **)** | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_voice_rate_hz` **(** :ref:`int` voice_idx, :ref:`float` rate_hz **)** | -+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_voice_cutoff_hz`\ (\ voice_idx\: :ref:`int`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_voice_delay_ms`\ (\ voice_idx\: :ref:`int`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_voice_depth_ms`\ (\ voice_idx\: :ref:`int`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_voice_level_db`\ (\ voice_idx\: :ref:`int`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_voice_pan`\ (\ voice_idx\: :ref:`int`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_voice_rate_hz`\ (\ voice_idx\: :ref:`int`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_voice_cutoff_hz`\ (\ voice_idx\: :ref:`int`, cutoff_hz\: :ref:`float`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_voice_delay_ms`\ (\ voice_idx\: :ref:`int`, delay_ms\: :ref:`float`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_voice_depth_ms`\ (\ voice_idx\: :ref:`int`, depth_ms\: :ref:`float`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_voice_level_db`\ (\ voice_idx\: :ref:`int`, level_db\: :ref:`float`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_voice_pan`\ (\ voice_idx\: :ref:`int`, pan\: :ref:`float`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_voice_rate_hz`\ (\ voice_idx\: :ref:`int`, rate_hz\: :ref:`float`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectChorus_property_dry: -- :ref:`float` **dry** +.. rst-class:: classref-property -+-----------+----------------+ -| *Default* | ``1.0`` | -+-----------+----------------+ -| *Setter* | set_dry(value) | -+-----------+----------------+ -| *Getter* | get_dry() | -+-----------+----------------+ +:ref:`float` **dry** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dry**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_dry**\ (\ ) The effect's raw signal. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/1/cutoff_hz: -- :ref:`float` **voice/1/cutoff_hz** +.. rst-class:: classref-property + +:ref:`float` **voice/1/cutoff_hz** = ``8000.0`` :ref:`🔗` -+-----------+----------------------------+ -| *Default* | ``8000.0`` | -+-----------+----------------------------+ -| *Setter* | set_voice_cutoff_hz(value) | -+-----------+----------------------------+ -| *Getter* | get_voice_cutoff_hz() | -+-----------+----------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`, cutoff_hz\: :ref:`float`\ ) +- :ref:`float` **get_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's cutoff frequency. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/1/delay_ms: -- :ref:`float` **voice/1/delay_ms** +.. rst-class:: classref-property + +:ref:`float` **voice/1/delay_ms** = ``15.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------------+ -| *Default* | ``15.0`` | -+-----------+---------------------------+ -| *Setter* | set_voice_delay_ms(value) | -+-----------+---------------------------+ -| *Getter* | get_voice_delay_ms() | -+-----------+---------------------------+ +- |void| **set_voice_delay_ms**\ (\ voice_idx\: :ref:`int`, delay_ms\: :ref:`float`\ ) +- :ref:`float` **get_voice_delay_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's signal delay. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/1/depth_ms: -- :ref:`float` **voice/1/depth_ms** +.. rst-class:: classref-property + +:ref:`float` **voice/1/depth_ms** = ``2.0`` :ref:`🔗` -+-----------+---------------------------+ -| *Default* | ``2.0`` | -+-----------+---------------------------+ -| *Setter* | set_voice_depth_ms(value) | -+-----------+---------------------------+ -| *Getter* | get_voice_depth_ms() | -+-----------+---------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_depth_ms**\ (\ voice_idx\: :ref:`int`, depth_ms\: :ref:`float`\ ) +- :ref:`float` **get_voice_depth_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice filter's depth. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/1/level_db: -- :ref:`float` **voice/1/level_db** +.. rst-class:: classref-property -+-----------+---------------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------------+ -| *Setter* | set_voice_level_db(value) | -+-----------+---------------------------+ -| *Getter* | get_voice_level_db() | -+-----------+---------------------------+ +:ref:`float` **voice/1/level_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_voice_level_db**\ (\ voice_idx\: :ref:`int`, level_db\: :ref:`float`\ ) +- :ref:`float` **get_voice_level_db**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's volume. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/1/pan: -- :ref:`float` **voice/1/pan** +.. rst-class:: classref-property + +:ref:`float` **voice/1/pan** = ``-0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``-0.5`` | -+-----------+----------------------+ -| *Setter* | set_voice_pan(value) | -+-----------+----------------------+ -| *Getter* | get_voice_pan() | -+-----------+----------------------+ +- |void| **set_voice_pan**\ (\ voice_idx\: :ref:`int`, pan\: :ref:`float`\ ) +- :ref:`float` **get_voice_pan**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's pan level. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/1/rate_hz: -- :ref:`float` **voice/1/rate_hz** +.. rst-class:: classref-property + +:ref:`float` **voice/1/rate_hz** = ``0.8`` :ref:`🔗` -+-----------+--------------------------+ -| *Default* | ``0.8`` | -+-----------+--------------------------+ -| *Setter* | set_voice_rate_hz(value) | -+-----------+--------------------------+ -| *Getter* | get_voice_rate_hz() | -+-----------+--------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_rate_hz**\ (\ voice_idx\: :ref:`int`, rate_hz\: :ref:`float`\ ) +- :ref:`float` **get_voice_rate_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's filter rate. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/2/cutoff_hz: -- :ref:`float` **voice/2/cutoff_hz** +.. rst-class:: classref-property -+-----------+----------------------------+ -| *Default* | ``8000.0`` | -+-----------+----------------------------+ -| *Setter* | set_voice_cutoff_hz(value) | -+-----------+----------------------------+ -| *Getter* | get_voice_cutoff_hz() | -+-----------+----------------------------+ +:ref:`float` **voice/2/cutoff_hz** = ``8000.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`, cutoff_hz\: :ref:`float`\ ) +- :ref:`float` **get_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's cutoff frequency. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/2/delay_ms: -- :ref:`float` **voice/2/delay_ms** +.. rst-class:: classref-property + +:ref:`float` **voice/2/delay_ms** = ``20.0`` :ref:`🔗` -+-----------+---------------------------+ -| *Default* | ``20.0`` | -+-----------+---------------------------+ -| *Setter* | set_voice_delay_ms(value) | -+-----------+---------------------------+ -| *Getter* | get_voice_delay_ms() | -+-----------+---------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_delay_ms**\ (\ voice_idx\: :ref:`int`, delay_ms\: :ref:`float`\ ) +- :ref:`float` **get_voice_delay_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's signal delay. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/2/depth_ms: -- :ref:`float` **voice/2/depth_ms** +.. rst-class:: classref-property + +:ref:`float` **voice/2/depth_ms** = ``3.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------------+ -| *Default* | ``3.0`` | -+-----------+---------------------------+ -| *Setter* | set_voice_depth_ms(value) | -+-----------+---------------------------+ -| *Getter* | get_voice_depth_ms() | -+-----------+---------------------------+ +- |void| **set_voice_depth_ms**\ (\ voice_idx\: :ref:`int`, depth_ms\: :ref:`float`\ ) +- :ref:`float` **get_voice_depth_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice filter's depth. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/2/level_db: -- :ref:`float` **voice/2/level_db** +.. rst-class:: classref-property + +:ref:`float` **voice/2/level_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------------+ -| *Setter* | set_voice_level_db(value) | -+-----------+---------------------------+ -| *Getter* | get_voice_level_db() | -+-----------+---------------------------+ +- |void| **set_voice_level_db**\ (\ voice_idx\: :ref:`int`, level_db\: :ref:`float`\ ) +- :ref:`float` **get_voice_level_db**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's volume. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/2/pan: -- :ref:`float` **voice/2/pan** +.. rst-class:: classref-property + +:ref:`float` **voice/2/pan** = ``0.5`` :ref:`🔗` -+-----------+----------------------+ -| *Default* | ``0.5`` | -+-----------+----------------------+ -| *Setter* | set_voice_pan(value) | -+-----------+----------------------+ -| *Getter* | get_voice_pan() | -+-----------+----------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_pan**\ (\ voice_idx\: :ref:`int`, pan\: :ref:`float`\ ) +- :ref:`float` **get_voice_pan**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's pan level. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/2/rate_hz: -- :ref:`float` **voice/2/rate_hz** +.. rst-class:: classref-property + +:ref:`float` **voice/2/rate_hz** = ``1.2`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+--------------------------+ -| *Default* | ``1.2`` | -+-----------+--------------------------+ -| *Setter* | set_voice_rate_hz(value) | -+-----------+--------------------------+ -| *Getter* | get_voice_rate_hz() | -+-----------+--------------------------+ +- |void| **set_voice_rate_hz**\ (\ voice_idx\: :ref:`int`, rate_hz\: :ref:`float`\ ) +- :ref:`float` **get_voice_rate_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's filter rate. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/3/cutoff_hz: -- :ref:`float` **voice/3/cutoff_hz** +.. rst-class:: classref-property + +:ref:`float` **voice/3/cutoff_hz** :ref:`🔗` -+----------+----------------------------+ -| *Setter* | set_voice_cutoff_hz(value) | -+----------+----------------------------+ -| *Getter* | get_voice_cutoff_hz() | -+----------+----------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`, cutoff_hz\: :ref:`float`\ ) +- :ref:`float` **get_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's cutoff frequency. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/3/delay_ms: -- :ref:`float` **voice/3/delay_ms** +.. rst-class:: classref-property -+----------+---------------------------+ -| *Setter* | set_voice_delay_ms(value) | -+----------+---------------------------+ -| *Getter* | get_voice_delay_ms() | -+----------+---------------------------+ +:ref:`float` **voice/3/delay_ms** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_voice_delay_ms**\ (\ voice_idx\: :ref:`int`, delay_ms\: :ref:`float`\ ) +- :ref:`float` **get_voice_delay_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's signal delay. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/3/depth_ms: -- :ref:`float` **voice/3/depth_ms** +.. rst-class:: classref-property + +:ref:`float` **voice/3/depth_ms** :ref:`🔗` -+----------+---------------------------+ -| *Setter* | set_voice_depth_ms(value) | -+----------+---------------------------+ -| *Getter* | get_voice_depth_ms() | -+----------+---------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_depth_ms**\ (\ voice_idx\: :ref:`int`, depth_ms\: :ref:`float`\ ) +- :ref:`float` **get_voice_depth_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice filter's depth. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/3/level_db: -- :ref:`float` **voice/3/level_db** +.. rst-class:: classref-property + +:ref:`float` **voice/3/level_db** :ref:`🔗` -+----------+---------------------------+ -| *Setter* | set_voice_level_db(value) | -+----------+---------------------------+ -| *Getter* | get_voice_level_db() | -+----------+---------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_level_db**\ (\ voice_idx\: :ref:`int`, level_db\: :ref:`float`\ ) +- :ref:`float` **get_voice_level_db**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's volume. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/3/pan: -- :ref:`float` **voice/3/pan** +.. rst-class:: classref-property -+----------+----------------------+ -| *Setter* | set_voice_pan(value) | -+----------+----------------------+ -| *Getter* | get_voice_pan() | -+----------+----------------------+ +:ref:`float` **voice/3/pan** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_voice_pan**\ (\ voice_idx\: :ref:`int`, pan\: :ref:`float`\ ) +- :ref:`float` **get_voice_pan**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's pan level. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/3/rate_hz: -- :ref:`float` **voice/3/rate_hz** +.. rst-class:: classref-property + +:ref:`float` **voice/3/rate_hz** :ref:`🔗` -+----------+--------------------------+ -| *Setter* | set_voice_rate_hz(value) | -+----------+--------------------------+ -| *Getter* | get_voice_rate_hz() | -+----------+--------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_rate_hz**\ (\ voice_idx\: :ref:`int`, rate_hz\: :ref:`float`\ ) +- :ref:`float` **get_voice_rate_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's filter rate. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/4/cutoff_hz: -- :ref:`float` **voice/4/cutoff_hz** +.. rst-class:: classref-property + +:ref:`float` **voice/4/cutoff_hz** :ref:`🔗` + +.. rst-class:: classref-property-setget -+----------+----------------------------+ -| *Setter* | set_voice_cutoff_hz(value) | -+----------+----------------------------+ -| *Getter* | get_voice_cutoff_hz() | -+----------+----------------------------+ +- |void| **set_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`, cutoff_hz\: :ref:`float`\ ) +- :ref:`float` **get_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's cutoff frequency. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/4/delay_ms: -- :ref:`float` **voice/4/delay_ms** +.. rst-class:: classref-property + +:ref:`float` **voice/4/delay_ms** :ref:`🔗` -+----------+---------------------------+ -| *Setter* | set_voice_delay_ms(value) | -+----------+---------------------------+ -| *Getter* | get_voice_delay_ms() | -+----------+---------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_delay_ms**\ (\ voice_idx\: :ref:`int`, delay_ms\: :ref:`float`\ ) +- :ref:`float` **get_voice_delay_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's signal delay. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/4/depth_ms: -- :ref:`float` **voice/4/depth_ms** +.. rst-class:: classref-property -+----------+---------------------------+ -| *Setter* | set_voice_depth_ms(value) | -+----------+---------------------------+ -| *Getter* | get_voice_depth_ms() | -+----------+---------------------------+ +:ref:`float` **voice/4/depth_ms** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_voice_depth_ms**\ (\ voice_idx\: :ref:`int`, depth_ms\: :ref:`float`\ ) +- :ref:`float` **get_voice_depth_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice filter's depth. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/4/level_db: -- :ref:`float` **voice/4/level_db** +.. rst-class:: classref-property + +:ref:`float` **voice/4/level_db** :ref:`🔗` + +.. rst-class:: classref-property-setget -+----------+---------------------------+ -| *Setter* | set_voice_level_db(value) | -+----------+---------------------------+ -| *Getter* | get_voice_level_db() | -+----------+---------------------------+ +- |void| **set_voice_level_db**\ (\ voice_idx\: :ref:`int`, level_db\: :ref:`float`\ ) +- :ref:`float` **get_voice_level_db**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's volume. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/4/pan: -- :ref:`float` **voice/4/pan** +.. rst-class:: classref-property + +:ref:`float` **voice/4/pan** :ref:`🔗` -+----------+----------------------+ -| *Setter* | set_voice_pan(value) | -+----------+----------------------+ -| *Getter* | get_voice_pan() | -+----------+----------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_voice_pan**\ (\ voice_idx\: :ref:`int`, pan\: :ref:`float`\ ) +- :ref:`float` **get_voice_pan**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's pan level. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice/4/rate_hz: -- :ref:`float` **voice/4/rate_hz** +.. rst-class:: classref-property -+----------+--------------------------+ -| *Setter* | set_voice_rate_hz(value) | -+----------+--------------------------+ -| *Getter* | get_voice_rate_hz() | -+----------+--------------------------+ +:ref:`float` **voice/4/rate_hz** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_voice_rate_hz**\ (\ voice_idx\: :ref:`int`, rate_hz\: :ref:`float`\ ) +- :ref:`float` **get_voice_rate_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| The voice's filter rate. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectChorus_property_voice_count: -- :ref:`int` **voice_count** +.. rst-class:: classref-property + +:ref:`int` **voice_count** = ``2`` :ref:`🔗` -+-----------+------------------------+ -| *Default* | ``2`` | -+-----------+------------------------+ -| *Setter* | set_voice_count(value) | -+-----------+------------------------+ -| *Getter* | get_voice_count() | -+-----------+------------------------+ +.. rst-class:: classref-property-setget -The amount of voices in the effect. +- |void| **set_voice_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_voice_count**\ (\ ) + +The number of voices in the effect. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_property_wet: -- :ref:`float` **wet** +.. rst-class:: classref-property + +:ref:`float` **wet** = ``0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------+ -| *Default* | ``0.5`` | -+-----------+----------------+ -| *Setter* | set_wet(value) | -+-----------+----------------+ -| *Getter* | get_wet() | -+-----------+----------------+ +- |void| **set_wet**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_wet**\ (\ ) The effect's processed signal. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- .. _class_AudioEffectChorus_method_get_voice_cutoff_hz: -- :ref:`float` **get_voice_cutoff_hz** **(** :ref:`int` voice_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **get_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_get_voice_delay_ms: -- :ref:`float` **get_voice_delay_ms** **(** :ref:`int` voice_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **get_voice_delay_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_get_voice_depth_ms: -- :ref:`float` **get_voice_depth_ms** **(** :ref:`int` voice_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **get_voice_depth_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_get_voice_level_db: -- :ref:`float` **get_voice_level_db** **(** :ref:`int` voice_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **get_voice_level_db**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_get_voice_pan: -- :ref:`float` **get_voice_pan** **(** :ref:`int` voice_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **get_voice_pan**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_get_voice_rate_hz: -- :ref:`float` **get_voice_rate_hz** **(** :ref:`int` voice_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **get_voice_rate_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_set_voice_cutoff_hz: -- void **set_voice_cutoff_hz** **(** :ref:`int` voice_idx, :ref:`float` cutoff_hz **)** +.. rst-class:: classref-method + +|void| **set_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`, cutoff_hz\: :ref:`float`\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_set_voice_delay_ms: -- void **set_voice_delay_ms** **(** :ref:`int` voice_idx, :ref:`float` delay_ms **)** +.. rst-class:: classref-method + +|void| **set_voice_delay_ms**\ (\ voice_idx\: :ref:`int`, delay_ms\: :ref:`float`\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_set_voice_depth_ms: -- void **set_voice_depth_ms** **(** :ref:`int` voice_idx, :ref:`float` depth_ms **)** +.. rst-class:: classref-method + +|void| **set_voice_depth_ms**\ (\ voice_idx\: :ref:`int`, depth_ms\: :ref:`float`\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_set_voice_level_db: -- void **set_voice_level_db** **(** :ref:`int` voice_idx, :ref:`float` level_db **)** +.. rst-class:: classref-method + +|void| **set_voice_level_db**\ (\ voice_idx\: :ref:`int`, level_db\: :ref:`float`\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_set_voice_pan: -- void **set_voice_pan** **(** :ref:`int` voice_idx, :ref:`float` pan **)** +.. rst-class:: classref-method + +|void| **set_voice_pan**\ (\ voice_idx\: :ref:`int`, pan\: :ref:`float`\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectChorus_method_set_voice_rate_hz: -- void **set_voice_rate_hz** **(** :ref:`int` voice_idx, :ref:`float` rate_hz **)** +.. rst-class:: classref-method + +|void| **set_voice_rate_hz**\ (\ voice_idx\: :ref:`int`, rate_hz\: :ref:`float`\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectcompressor.rst b/classes/class_audioeffectcompressor.rst index be2b6c76554..77abbe9c665 100644 --- a/classes/class_audioeffectcompressor.rst +++ b/classes/class_audioeffectcompressor.rst @@ -1,20 +1,23 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectCompressor.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectCompressor.xml. .. _class_AudioEffectCompressor: AudioEffectCompressor ===================== -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a compressor audio effect to an audio bus. Reduces sounds that exceed a certain threshold level, smooths out the dynamics and increases the overall volume. +.. rst-class:: classref-introduction-group + Description ----------- @@ -22,7 +25,7 @@ Dynamic range compressor reduces the level of the sound when the amplitude goes Compressor has many uses in the mix: -- In the Master bus to compress the whole output (although an :ref:`AudioEffectLimiter` is probably better). +- In the Master bus to compress the whole output (although an :ref:`AudioEffectHardLimiter` is probably better). - In voice channels to ensure they sound as balanced as possible. @@ -30,135 +33,167 @@ Compressor has many uses in the mix: - Accentuates transients by using a wider attack, making effects sound more punchy. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+-------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`attack_us` | ``20.0`` | -+-------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`gain` | ``0.0`` | -+-------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`mix` | ``1.0`` | -+-------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`ratio` | ``4.0`` | -+-------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`release_ms` | ``250.0`` | -+-------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`StringName` | :ref:`sidechain` | ``@""`` | -+-------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`threshold` | ``0.0`` | -+-------------------------------------+--------------------------------------------------------------------+-----------+ +.. table:: + :widths: auto + + +-------------------------------------+--------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`attack_us` | ``20.0`` | + +-------------------------------------+--------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`gain` | ``0.0`` | + +-------------------------------------+--------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`mix` | ``1.0`` | + +-------------------------------------+--------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`ratio` | ``4.0`` | + +-------------------------------------+--------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`release_ms` | ``250.0`` | + +-------------------------------------+--------------------------------------------------------------------+-----------+ + | :ref:`StringName` | :ref:`sidechain` | ``&""`` | + +-------------------------------------+--------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`threshold` | ``0.0`` | + +-------------------------------------+--------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectCompressor_property_attack_us: -- :ref:`float` **attack_us** +.. rst-class:: classref-property + +:ref:`float` **attack_us** = ``20.0`` :ref:`🔗` -+-----------+----------------------+ -| *Default* | ``20.0`` | -+-----------+----------------------+ -| *Setter* | set_attack_us(value) | -+-----------+----------------------+ -| *Getter* | get_attack_us() | -+-----------+----------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_attack_us**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_attack_us**\ (\ ) Compressor's reaction time when the signal exceeds the threshold, in microseconds. Value can range from 20 to 2000. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectCompressor_property_gain: -- :ref:`float` **gain** +.. rst-class:: classref-property -+-----------+-----------------+ -| *Default* | ``0.0`` | -+-----------+-----------------+ -| *Setter* | set_gain(value) | -+-----------+-----------------+ -| *Getter* | get_gain() | -+-----------+-----------------+ +:ref:`float` **gain** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_gain**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_gain**\ (\ ) Gain applied to the output signal. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectCompressor_property_mix: -- :ref:`float` **mix** +.. rst-class:: classref-property -+-----------+----------------+ -| *Default* | ``1.0`` | -+-----------+----------------+ -| *Setter* | set_mix(value) | -+-----------+----------------+ -| *Getter* | get_mix() | -+-----------+----------------+ +:ref:`float` **mix** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mix**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_mix**\ (\ ) Balance between original signal and effect signal. Value can range from 0 (totally dry) to 1 (totally wet). +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectCompressor_property_ratio: -- :ref:`float` **ratio** +.. rst-class:: classref-property + +:ref:`float` **ratio** = ``4.0`` :ref:`🔗` -+-----------+------------------+ -| *Default* | ``4.0`` | -+-----------+------------------+ -| *Setter* | set_ratio(value) | -+-----------+------------------+ -| *Getter* | get_ratio() | -+-----------+------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_ratio**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_ratio**\ (\ ) Amount of compression applied to the audio once it passes the threshold level. The higher the ratio, the more the loud parts of the audio will be compressed. Value can range from 1 to 48. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectCompressor_property_release_ms: -- :ref:`float` **release_ms** +.. rst-class:: classref-property + +:ref:`float` **release_ms** = ``250.0`` :ref:`🔗` -+-----------+-----------------------+ -| *Default* | ``250.0`` | -+-----------+-----------------------+ -| *Setter* | set_release_ms(value) | -+-----------+-----------------------+ -| *Getter* | get_release_ms() | -+-----------+-----------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_release_ms**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_release_ms**\ (\ ) Compressor's delay time to stop reducing the signal after the signal level falls below the threshold, in milliseconds. Value can range from 20 to 2000. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectCompressor_property_sidechain: -- :ref:`StringName` **sidechain** +.. rst-class:: classref-property + +:ref:`StringName` **sidechain** = ``&""`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``@""`` | -+-----------+----------------------+ -| *Setter* | set_sidechain(value) | -+-----------+----------------------+ -| *Getter* | get_sidechain() | -+-----------+----------------------+ +- |void| **set_sidechain**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_sidechain**\ (\ ) Reduce the sound level using another audio bus for threshold detection. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectCompressor_property_threshold: -- :ref:`float` **threshold** +.. rst-class:: classref-property + +:ref:`float` **threshold** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``0.0`` | -+-----------+----------------------+ -| *Setter* | set_threshold(value) | -+-----------+----------------------+ -| *Getter* | get_threshold() | -+-----------+----------------------+ +- |void| **set_threshold**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_threshold**\ (\ ) The level above which compression is applied to the audio. Value can range from -60 to 0. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectdelay.rst b/classes/class_audioeffectdelay.rst index 35d41b3dab4..3bdebd7b4a1 100644 --- a/classes/class_audioeffectdelay.rst +++ b/classes/class_audioeffectdelay.rst @@ -1,262 +1,303 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectDelay.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectDelay.xml. .. _class_AudioEffectDelay: AudioEffectDelay ================ -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a delay audio effect to an audio bus. Plays input signal back after a period of time. Two tap delay and feedback options. +.. rst-class:: classref-introduction-group + Description ----------- Plays input signal back after a period of time. The delayed signal may be played back multiple times to create the sound of a repeating, decaying echo. Delay effects range from a subtle echo effect to a pronounced blending of previous sounds with new sounds. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`dry` | ``1.0`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`bool` | :ref:`feedback/active` | ``false`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`feedback/delay_ms` | ``340.0`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`feedback/level_db` | ``-6.0`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`feedback/lowpass` | ``16000.0`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`bool` | :ref:`tap1/active` | ``true`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`tap1/delay_ms` | ``250.0`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`tap1/level_db` | ``-6.0`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`tap1/pan` | ``0.2`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`bool` | :ref:`tap2/active` | ``true`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`tap2/delay_ms` | ``500.0`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`tap2/level_db` | ``-12.0`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`tap2/pan` | ``-0.4`` | -+---------------------------+-----------------------------------------------------------------------------+-------------+ +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`dry` | ``1.0`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`bool` | :ref:`feedback_active` | ``false`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`feedback_delay_ms` | ``340.0`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`feedback_level_db` | ``-6.0`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`feedback_lowpass` | ``16000.0`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`bool` | :ref:`tap1_active` | ``true`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`tap1_delay_ms` | ``250.0`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`tap1_level_db` | ``-6.0`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`tap1_pan` | ``0.2`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`bool` | :ref:`tap2_active` | ``true`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`tap2_delay_ms` | ``500.0`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`tap2_level_db` | ``-12.0`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`tap2_pan` | ``-0.4`` | + +---------------------------+-----------------------------------------------------------------------------+-------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectDelay_property_dry: -- :ref:`float` **dry** +.. rst-class:: classref-property + +:ref:`float` **dry** = ``1.0`` :ref:`🔗` -+-----------+----------------+ -| *Default* | ``1.0`` | -+-----------+----------------+ -| *Setter* | set_dry(value) | -+-----------+----------------+ -| *Getter* | get_dry() | -+-----------+----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_dry**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_dry**\ (\ ) Output percent of original sound. At 0, only delayed sounds are output. Value can range from 0 to 1. +.. rst-class:: classref-item-separator + ---- -.. _class_AudioEffectDelay_property_feedback/active: +.. _class_AudioEffectDelay_property_feedback_active: + +.. rst-class:: classref-property -- :ref:`bool` **feedback/active** +:ref:`bool` **feedback_active** = ``false`` :ref:`🔗` -+-----------+----------------------------+ -| *Default* | ``false`` | -+-----------+----------------------------+ -| *Setter* | set_feedback_active(value) | -+-----------+----------------------------+ -| *Getter* | is_feedback_active() | -+-----------+----------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_feedback_active**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_feedback_active**\ (\ ) If ``true``, feedback is enabled. +.. rst-class:: classref-item-separator + ---- -.. _class_AudioEffectDelay_property_feedback/delay_ms: +.. _class_AudioEffectDelay_property_feedback_delay_ms: + +.. rst-class:: classref-property -- :ref:`float` **feedback/delay_ms** +:ref:`float` **feedback_delay_ms** = ``340.0`` :ref:`🔗` -+-----------+------------------------------+ -| *Default* | ``340.0`` | -+-----------+------------------------------+ -| *Setter* | set_feedback_delay_ms(value) | -+-----------+------------------------------+ -| *Getter* | get_feedback_delay_ms() | -+-----------+------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_feedback_delay_ms**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_feedback_delay_ms**\ (\ ) Feedback delay time in milliseconds. +.. rst-class:: classref-item-separator + ---- -.. _class_AudioEffectDelay_property_feedback/level_db: +.. _class_AudioEffectDelay_property_feedback_level_db: + +.. rst-class:: classref-property -- :ref:`float` **feedback/level_db** +:ref:`float` **feedback_level_db** = ``-6.0`` :ref:`🔗` -+-----------+------------------------------+ -| *Default* | ``-6.0`` | -+-----------+------------------------------+ -| *Setter* | set_feedback_level_db(value) | -+-----------+------------------------------+ -| *Getter* | get_feedback_level_db() | -+-----------+------------------------------+ +.. rst-class:: classref-property-setget -Sound level for ``tap1``. +- |void| **set_feedback_level_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_feedback_level_db**\ (\ ) + +Sound level for feedback. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioEffectDelay_property_feedback/lowpass: +.. _class_AudioEffectDelay_property_feedback_lowpass: + +.. rst-class:: classref-property -- :ref:`float` **feedback/lowpass** +:ref:`float` **feedback_lowpass** = ``16000.0`` :ref:`🔗` -+-----------+-----------------------------+ -| *Default* | ``16000.0`` | -+-----------+-----------------------------+ -| *Setter* | set_feedback_lowpass(value) | -+-----------+-----------------------------+ -| *Getter* | get_feedback_lowpass() | -+-----------+-----------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_feedback_lowpass**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_feedback_lowpass**\ (\ ) Low-pass filter for feedback, in Hz. Frequencies below this value are filtered out of the source signal. +.. rst-class:: classref-item-separator + ---- -.. _class_AudioEffectDelay_property_tap1/active: +.. _class_AudioEffectDelay_property_tap1_active: -- :ref:`bool` **tap1/active** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``true`` | -+-----------+------------------------+ -| *Setter* | set_tap1_active(value) | -+-----------+------------------------+ -| *Getter* | is_tap1_active() | -+-----------+------------------------+ +:ref:`bool` **tap1_active** = ``true`` :ref:`🔗` -If ``true``, ``tap1`` will be enabled. +.. rst-class:: classref-property-setget + +- |void| **set_tap1_active**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_tap1_active**\ (\ ) + +If ``true``, the first tap will be enabled. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioEffectDelay_property_tap1/delay_ms: +.. _class_AudioEffectDelay_property_tap1_delay_ms: + +.. rst-class:: classref-property + +:ref:`float` **tap1_delay_ms** = ``250.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`float` **tap1/delay_ms** +- |void| **set_tap1_delay_ms**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_tap1_delay_ms**\ (\ ) -+-----------+--------------------------+ -| *Default* | ``250.0`` | -+-----------+--------------------------+ -| *Setter* | set_tap1_delay_ms(value) | -+-----------+--------------------------+ -| *Getter* | get_tap1_delay_ms() | -+-----------+--------------------------+ +First tap delay time in milliseconds. -``tap1`` delay time in milliseconds. +.. rst-class:: classref-item-separator ---- -.. _class_AudioEffectDelay_property_tap1/level_db: +.. _class_AudioEffectDelay_property_tap1_level_db: -- :ref:`float` **tap1/level_db** +.. rst-class:: classref-property -+-----------+--------------------------+ -| *Default* | ``-6.0`` | -+-----------+--------------------------+ -| *Setter* | set_tap1_level_db(value) | -+-----------+--------------------------+ -| *Getter* | get_tap1_level_db() | -+-----------+--------------------------+ +:ref:`float` **tap1_level_db** = ``-6.0`` :ref:`🔗` -Sound level for ``tap1``. +.. rst-class:: classref-property-setget + +- |void| **set_tap1_level_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_tap1_level_db**\ (\ ) + +Sound level for the first tap. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioEffectDelay_property_tap1/pan: +.. _class_AudioEffectDelay_property_tap1_pan: + +.. rst-class:: classref-property + +:ref:`float` **tap1_pan** = ``0.2`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`float` **tap1/pan** +- |void| **set_tap1_pan**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_tap1_pan**\ (\ ) -+-----------+---------------------+ -| *Default* | ``0.2`` | -+-----------+---------------------+ -| *Setter* | set_tap1_pan(value) | -+-----------+---------------------+ -| *Getter* | get_tap1_pan() | -+-----------+---------------------+ +Pan position for the first tap. Value can range from -1 (fully left) to 1 (fully right). -Pan position for ``tap1``. Value can range from -1 (fully left) to 1 (fully right). +.. rst-class:: classref-item-separator ---- -.. _class_AudioEffectDelay_property_tap2/active: +.. _class_AudioEffectDelay_property_tap2_active: -- :ref:`bool` **tap2/active** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``true`` | -+-----------+------------------------+ -| *Setter* | set_tap2_active(value) | -+-----------+------------------------+ -| *Getter* | is_tap2_active() | -+-----------+------------------------+ +:ref:`bool` **tap2_active** = ``true`` :ref:`🔗` -If ``true``, ``tap2`` will be enabled. +.. rst-class:: classref-property-setget + +- |void| **set_tap2_active**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_tap2_active**\ (\ ) + +If ``true``, the second tap will be enabled. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioEffectDelay_property_tap2/delay_ms: +.. _class_AudioEffectDelay_property_tap2_delay_ms: + +.. rst-class:: classref-property + +:ref:`float` **tap2_delay_ms** = ``500.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`float` **tap2/delay_ms** +- |void| **set_tap2_delay_ms**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_tap2_delay_ms**\ (\ ) -+-----------+--------------------------+ -| *Default* | ``500.0`` | -+-----------+--------------------------+ -| *Setter* | set_tap2_delay_ms(value) | -+-----------+--------------------------+ -| *Getter* | get_tap2_delay_ms() | -+-----------+--------------------------+ +Second tap delay time in milliseconds. -**Tap2** delay time in milliseconds. +.. rst-class:: classref-item-separator ---- -.. _class_AudioEffectDelay_property_tap2/level_db: +.. _class_AudioEffectDelay_property_tap2_level_db: -- :ref:`float` **tap2/level_db** +.. rst-class:: classref-property -+-----------+--------------------------+ -| *Default* | ``-12.0`` | -+-----------+--------------------------+ -| *Setter* | set_tap2_level_db(value) | -+-----------+--------------------------+ -| *Getter* | get_tap2_level_db() | -+-----------+--------------------------+ +:ref:`float` **tap2_level_db** = ``-12.0`` :ref:`🔗` -Sound level for ``tap2``. +.. rst-class:: classref-property-setget + +- |void| **set_tap2_level_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_tap2_level_db**\ (\ ) + +Sound level for the second tap. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioEffectDelay_property_tap2/pan: +.. _class_AudioEffectDelay_property_tap2_pan: + +.. rst-class:: classref-property + +:ref:`float` **tap2_pan** = ``-0.4`` :ref:`🔗` -- :ref:`float` **tap2/pan** +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``-0.4`` | -+-----------+---------------------+ -| *Setter* | set_tap2_pan(value) | -+-----------+---------------------+ -| *Getter* | get_tap2_pan() | -+-----------+---------------------+ +- |void| **set_tap2_pan**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_tap2_pan**\ (\ ) -Pan position for ``tap2``. Value can range from -1 (fully left) to 1 (fully right). +Pan position for the second tap. Value can range from -1 (fully left) to 1 (fully right). +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectdistortion.rst b/classes/class_audioeffectdistortion.rst index a46c87e3751..f5fffb1af89 100644 --- a/classes/class_audioeffectdistortion.rst +++ b/classes/class_audioeffectdistortion.rst @@ -1,147 +1,212 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectDistortion.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectDistortion.xml. .. _class_AudioEffectDistortion: AudioEffectDistortion ===================== -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a distortion audio effect to an Audio bus. -Modify the sound to make it dirty. +Modifies the sound to make it distorted. + +.. rst-class:: classref-introduction-group Description ----------- -Modify the sound and make it dirty. Different types are available: clip, tan, lo-fi (bit crushing), overdrive, or waveshape. +Different types are available: clip, tan, lo-fi (bit crushing), overdrive, or waveshape. + +By distorting the waveform the frequency content changes, which will often make the sound "crunchy" or "abrasive". For games, it can simulate sound coming from some saturated device or speaker very efficiently. + +.. rst-class:: classref-introduction-group -By distorting the waveform the frequency content change, which will often make the sound "crunchy" or "abrasive". For games, it can simulate sound coming from some saturated device or speaker very efficiently. +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group Properties ---------- -+----------------------------------------------+--------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`drive` | ``0.0`` | -+----------------------------------------------+--------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`keep_hf_hz` | ``16000.0`` | -+----------------------------------------------+--------------------------------------------------------------------+-------------+ -| :ref:`Mode` | :ref:`mode` | ``0`` | -+----------------------------------------------+--------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`post_gain` | ``0.0`` | -+----------------------------------------------+--------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`pre_gain` | ``0.0`` | -+----------------------------------------------+--------------------------------------------------------------------+-------------+ +.. table:: + :widths: auto + + +----------------------------------------------+--------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`drive` | ``0.0`` | + +----------------------------------------------+--------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`keep_hf_hz` | ``16000.0`` | + +----------------------------------------------+--------------------------------------------------------------------+-------------+ + | :ref:`Mode` | :ref:`mode` | ``0`` | + +----------------------------------------------+--------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`post_gain` | ``0.0`` | + +----------------------------------------------+--------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`pre_gain` | ``0.0`` | + +----------------------------------------------+--------------------------------------------------------------------+-------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_AudioEffectDistortion_Mode: +.. rst-class:: classref-enumeration + +enum **Mode**: :ref:`🔗` + .. _class_AudioEffectDistortion_constant_MODE_CLIP: +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_CLIP** = ``0`` + +Digital distortion effect which cuts off peaks at the top and bottom of the waveform. + .. _class_AudioEffectDistortion_constant_MODE_ATAN: +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_ATAN** = ``1`` + +.. container:: contribute + + There is currently no description for this enum. Please help us by `contributing one `__! + + + .. _class_AudioEffectDistortion_constant_MODE_LOFI: +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_LOFI** = ``2`` + +Low-resolution digital distortion effect (bit depth reduction). You can use it to emulate the sound of early digital audio devices. + .. _class_AudioEffectDistortion_constant_MODE_OVERDRIVE: +.. rst-class:: classref-enumeration-constant + +:ref:`Mode` **MODE_OVERDRIVE** = ``3`` + +Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. The :ref:`drive` property has no effect in this mode. + .. _class_AudioEffectDistortion_constant_MODE_WAVESHAPE: -enum **Mode**: +.. rst-class:: classref-enumeration-constant -- **MODE_CLIP** = **0** --- Digital distortion effect which cuts off peaks at the top and bottom of the waveform. +:ref:`Mode` **MODE_WAVESHAPE** = ``4`` -- **MODE_ATAN** = **1** +Waveshaper distortions are used mainly by electronic musicians to achieve an extra-abrasive sound. -- **MODE_LOFI** = **2** --- Low-resolution digital distortion effect. You can use it to emulate the sound of early digital audio devices. +.. rst-class:: classref-section-separator -- **MODE_OVERDRIVE** = **3** --- Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. +---- -- **MODE_WAVESHAPE** = **4** --- Waveshaper distortions are used mainly by electronic musicians to achieve an extra-abrasive sound. +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectDistortion_property_drive: -- :ref:`float` **drive** +.. rst-class:: classref-property + +:ref:`float` **drive** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------+ -| *Default* | ``0.0`` | -+-----------+------------------+ -| *Setter* | set_drive(value) | -+-----------+------------------+ -| *Getter* | get_drive() | -+-----------+------------------+ +- |void| **set_drive**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_drive**\ (\ ) Distortion power. Value can range from 0 to 1. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectDistortion_property_keep_hf_hz: -- :ref:`float` **keep_hf_hz** +.. rst-class:: classref-property + +:ref:`float` **keep_hf_hz** = ``16000.0`` :ref:`🔗` -+-----------+-----------------------+ -| *Default* | ``16000.0`` | -+-----------+-----------------------+ -| *Setter* | set_keep_hf_hz(value) | -+-----------+-----------------------+ -| *Getter* | get_keep_hf_hz() | -+-----------+-----------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_keep_hf_hz**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_keep_hf_hz**\ (\ ) High-pass filter, in Hz. Frequencies higher than this value will not be affected by the distortion. Value can range from 1 to 20000. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectDistortion_property_mode: -- :ref:`Mode` **mode** +.. rst-class:: classref-property + +:ref:`Mode` **mode** = ``0`` :ref:`🔗` -+-----------+-----------------+ -| *Default* | ``0`` | -+-----------+-----------------+ -| *Setter* | set_mode(value) | -+-----------+-----------------+ -| *Getter* | get_mode() | -+-----------+-----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_mode**\ (\ value\: :ref:`Mode`\ ) +- :ref:`Mode` **get_mode**\ (\ ) Distortion type. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectDistortion_property_post_gain: -- :ref:`float` **post_gain** +.. rst-class:: classref-property -+-----------+----------------------+ -| *Default* | ``0.0`` | -+-----------+----------------------+ -| *Setter* | set_post_gain(value) | -+-----------+----------------------+ -| *Getter* | get_post_gain() | -+-----------+----------------------+ +:ref:`float` **post_gain** = ``0.0`` :ref:`🔗` -Increases or decreases the volume after the effect. Value can range from -80 to 24. +.. rst-class:: classref-property-setget + +- |void| **set_post_gain**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_post_gain**\ (\ ) + +Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectDistortion_property_pre_gain: -- :ref:`float` **pre_gain** +.. rst-class:: classref-property + +:ref:`float` **pre_gain** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_pre_gain(value) | -+-----------+---------------------+ -| *Getter* | get_pre_gain() | -+-----------+---------------------+ +- |void| **set_pre_gain**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pre_gain**\ (\ ) -Increases or decreases the volume before the effect. Value can range from -60 to 60. +Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffecteq.rst b/classes/class_audioeffecteq.rst index 1ca800425ec..b2d3eb11077 100644 --- a/classes/class_audioeffecteq.rst +++ b/classes/class_audioeffecteq.rst @@ -1,15 +1,16 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectEQ.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectEQ.xml. .. _class_AudioEffectEQ: AudioEffectEQ ============= -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` **Inherited By:** :ref:`AudioEffectEQ10`, :ref:`AudioEffectEQ21`, :ref:`AudioEffectEQ6` @@ -17,44 +18,83 @@ Base class for audio equalizers. Gives you control over frequencies. Use it to create a custom equalizer if :ref:`AudioEffectEQ6`, :ref:`AudioEffectEQ10` or :ref:`AudioEffectEQ21` don't fit your needs. +.. rst-class:: classref-introduction-group + Description ----------- AudioEffectEQ gives you control over frequencies. Use it to compensate for existing deficiencies in audio. AudioEffectEQs are useful on the Master bus to completely master a mix and give it more character. They are also useful when a game is run on a mobile device, to adjust the mix to that kind of speakers (it can be added but disabled when headphones are plugged). +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Methods ------- -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_band_count` **(** **)** const | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_band_gain_db` **(** :ref:`int` band_idx **)** const | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_band_gain_db` **(** :ref:`int` band_idx, :ref:`float` volume_db **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_band_count`\ (\ ) |const| | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_band_gain_db`\ (\ band_idx\: :ref:`int`\ ) |const| | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_band_gain_db`\ (\ band_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) | + +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AudioEffectEQ_method_get_band_count: -- :ref:`int` **get_band_count** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_band_count**\ (\ ) |const| :ref:`🔗` Returns the number of bands of the equalizer. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectEQ_method_get_band_gain_db: -- :ref:`float` **get_band_gain_db** **(** :ref:`int` band_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **get_band_gain_db**\ (\ band_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the band's gain at the specified index, in dB. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectEQ_method_set_band_gain_db: -- void **set_band_gain_db** **(** :ref:`int` band_idx, :ref:`float` volume_db **)** +.. rst-class:: classref-method + +|void| **set_band_gain_db**\ (\ band_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) :ref:`🔗` Sets band's gain at the specified index, in dB. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffecteq10.rst b/classes/class_audioeffecteq10.rst index 5148d931693..fab663d26c3 100644 --- a/classes/class_audioeffecteq10.rst +++ b/classes/class_audioeffecteq10.rst @@ -1,20 +1,23 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectEQ10.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectEQ10.xml. .. _class_AudioEffectEQ10: AudioEffectEQ10 =============== -**Inherits:** :ref:`AudioEffectEQ` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectEQ` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a 10-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 31 Hz to 16000 Hz. Each frequency can be modulated between -60/+24 dB. +.. rst-class:: classref-introduction-group + Description ----------- @@ -42,3 +45,19 @@ Band 10: 16000 Hz See also :ref:`AudioEffectEQ`, :ref:`AudioEffectEQ6`, :ref:`AudioEffectEQ21`. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffecteq21.rst b/classes/class_audioeffecteq21.rst index 5015751367d..403e88699d6 100644 --- a/classes/class_audioeffecteq21.rst +++ b/classes/class_audioeffecteq21.rst @@ -1,20 +1,23 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectEQ21.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectEQ21.xml. .. _class_AudioEffectEQ21: AudioEffectEQ21 =============== -**Inherits:** :ref:`AudioEffectEQ` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectEQ` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a 21-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 22 Hz to 22000 Hz. Each frequency can be modulated between -60/+24 dB. +.. rst-class:: classref-introduction-group + Description ----------- @@ -64,3 +67,19 @@ Band 21: 22000 Hz See also :ref:`AudioEffectEQ`, :ref:`AudioEffectEQ6`, :ref:`AudioEffectEQ10`. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffecteq6.rst b/classes/class_audioeffecteq6.rst index e4677ee64bb..a0c8de1cc31 100644 --- a/classes/class_audioeffecteq6.rst +++ b/classes/class_audioeffecteq6.rst @@ -1,20 +1,23 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectEQ6.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectEQ6.xml. .. _class_AudioEffectEQ6: AudioEffectEQ6 ============== -**Inherits:** :ref:`AudioEffectEQ` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectEQ` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Adds a 6-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 32 Hz to 10000 Hz. +Adds a 6-band equalizer audio effect to an audio bus. Gives you control over frequencies from 32 Hz to 10000 Hz. Each frequency can be modulated between -60/+24 dB. +.. rst-class:: classref-introduction-group + Description ----------- @@ -34,3 +37,19 @@ Band 6: 10000 Hz See also :ref:`AudioEffectEQ`, :ref:`AudioEffectEQ10`, :ref:`AudioEffectEQ21`. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectfilter.rst b/classes/class_audioeffectfilter.rst index 01ab714f605..0f177335876 100644 --- a/classes/class_audioeffectfilter.rst +++ b/classes/class_audioeffectfilter.rst @@ -1,121 +1,179 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectFilter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectFilter.xml. .. _class_AudioEffectFilter: AudioEffectFilter ================= -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` **Inherited By:** :ref:`AudioEffectBandLimitFilter`, :ref:`AudioEffectBandPassFilter`, :ref:`AudioEffectHighPassFilter`, :ref:`AudioEffectHighShelfFilter`, :ref:`AudioEffectLowPassFilter`, :ref:`AudioEffectLowShelfFilter`, :ref:`AudioEffectNotchFilter` Adds a filter to the audio bus. +.. rst-class:: classref-introduction-group + Description ----------- Allows frequencies other than the :ref:`cutoff_hz` to pass. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+--------------------------------------------------+--------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`cutoff_hz` | ``2000.0`` | -+--------------------------------------------------+--------------------------------------------------------------+------------+ -| :ref:`FilterDB` | :ref:`db` | ``0`` | -+--------------------------------------------------+--------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`gain` | ``1.0`` | -+--------------------------------------------------+--------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`resonance` | ``0.5`` | -+--------------------------------------------------+--------------------------------------------------------------+------------+ +.. table:: + :widths: auto + + +--------------------------------------------------+--------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`cutoff_hz` | ``2000.0`` | + +--------------------------------------------------+--------------------------------------------------------------+------------+ + | :ref:`FilterDB` | :ref:`db` | ``0`` | + +--------------------------------------------------+--------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`gain` | ``1.0`` | + +--------------------------------------------------+--------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`resonance` | ``0.5`` | + +--------------------------------------------------+--------------------------------------------------------------+------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_AudioEffectFilter_FilterDB: +.. rst-class:: classref-enumeration + +enum **FilterDB**: :ref:`🔗` + .. _class_AudioEffectFilter_constant_FILTER_6DB: +.. rst-class:: classref-enumeration-constant + +:ref:`FilterDB` **FILTER_6DB** = ``0`` + +Cutting off at 6dB per octave. + .. _class_AudioEffectFilter_constant_FILTER_12DB: +.. rst-class:: classref-enumeration-constant + +:ref:`FilterDB` **FILTER_12DB** = ``1`` + +Cutting off at 12dB per octave. + .. _class_AudioEffectFilter_constant_FILTER_18DB: +.. rst-class:: classref-enumeration-constant + +:ref:`FilterDB` **FILTER_18DB** = ``2`` + +Cutting off at 18dB per octave. + .. _class_AudioEffectFilter_constant_FILTER_24DB: -enum **FilterDB**: +.. rst-class:: classref-enumeration-constant -- **FILTER_6DB** = **0** +:ref:`FilterDB` **FILTER_24DB** = ``3`` -- **FILTER_12DB** = **1** +Cutting off at 24dB per octave. -- **FILTER_18DB** = **2** +.. rst-class:: classref-section-separator + +---- -- **FILTER_24DB** = **3** +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectFilter_property_cutoff_hz: -- :ref:`float` **cutoff_hz** +.. rst-class:: classref-property -+-----------+-------------------+ -| *Default* | ``2000.0`` | -+-----------+-------------------+ -| *Setter* | set_cutoff(value) | -+-----------+-------------------+ -| *Getter* | get_cutoff() | -+-----------+-------------------+ +:ref:`float` **cutoff_hz** = ``2000.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_cutoff**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_cutoff**\ (\ ) Threshold frequency for the filter, in Hz. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectFilter_property_db: -- :ref:`FilterDB` **db** +.. rst-class:: classref-property + +:ref:`FilterDB` **db** = ``0`` :ref:`🔗` -+-----------+---------------+ -| *Default* | ``0`` | -+-----------+---------------+ -| *Setter* | set_db(value) | -+-----------+---------------+ -| *Getter* | get_db() | -+-----------+---------------+ +.. rst-class:: classref-property-setget + +- |void| **set_db**\ (\ value\: :ref:`FilterDB`\ ) +- :ref:`FilterDB` **get_db**\ (\ ) + +Steepness of the cutoff curve in dB per octave, also known as the order of the filter. Higher orders have a more aggressive cutoff. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectFilter_property_gain: -- :ref:`float` **gain** +.. rst-class:: classref-property + +:ref:`float` **gain** = ``1.0`` :ref:`🔗` -+-----------+-----------------+ -| *Default* | ``1.0`` | -+-----------+-----------------+ -| *Setter* | set_gain(value) | -+-----------+-----------------+ -| *Getter* | get_gain() | -+-----------+-----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_gain**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_gain**\ (\ ) Gain amount of the frequencies after the filter. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectFilter_property_resonance: -- :ref:`float` **resonance** +.. rst-class:: classref-property + +:ref:`float` **resonance** = ``0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``0.5`` | -+-----------+----------------------+ -| *Setter* | set_resonance(value) | -+-----------+----------------------+ -| *Getter* | get_resonance() | -+-----------+----------------------+ +- |void| **set_resonance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_resonance**\ (\ ) -Amount of boost in the overtones near the cutoff frequency. +Amount of boost in the frequency range near the cutoff frequency. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffecthardlimiter.rst b/classes/class_audioeffecthardlimiter.rst new file mode 100644 index 00000000000..3620fdd7967 --- /dev/null +++ b/classes/class_audioeffecthardlimiter.rst @@ -0,0 +1,113 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectHardLimiter.xml. + +.. _class_AudioEffectHardLimiter: + +AudioEffectHardLimiter +====================== + +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Adds a hard limiter audio effect to an Audio bus. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A limiter is an effect designed to disallow sound from going over a given dB threshold. Hard limiters predict volume peaks, and will smoothly apply gain reduction when a peak crosses the ceiling threshold to prevent clipping and distortion. It preserves the waveform and prevents it from crossing the ceiling threshold. Adding one in the Master bus is recommended as a safety measure to prevent sudden volume peaks from occurring, and to prevent distortion caused by clipping. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`ceiling_db` | ``-0.3`` | + +---------------------------+-----------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`pre_gain_db` | ``0.0`` | + +---------------------------+-----------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`release` | ``0.1`` | + +---------------------------+-----------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioEffectHardLimiter_property_ceiling_db: + +.. rst-class:: classref-property + +:ref:`float` **ceiling_db** = ``-0.3`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_ceiling_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_ceiling_db**\ (\ ) + +The waveform's maximum allowed value, in decibels. This value can range from ``-24.0`` to ``0.0``. + +The default value of ``-0.3`` prevents potential inter-sample peaks (ISP) from crossing over 0 dB, which can cause slight distortion on some older hardware. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectHardLimiter_property_pre_gain_db: + +.. rst-class:: classref-property + +:ref:`float` **pre_gain_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pre_gain_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pre_gain_db**\ (\ ) + +Gain to apply before limiting, in decibels. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectHardLimiter_property_release: + +.. rst-class:: classref-property + +:ref:`float` **release** = ``0.1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_release**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_release**\ (\ ) + +Time it takes in seconds for the gain reduction to fully release. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffecthighpassfilter.rst b/classes/class_audioeffecthighpassfilter.rst index c5a37b83fd7..8c480cb82af 100644 --- a/classes/class_audioeffecthighpassfilter.rst +++ b/classes/class_audioeffecthighpassfilter.rst @@ -1,20 +1,39 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectHighPassFilter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectHighPassFilter.xml. .. _class_AudioEffectHighPassFilter: AudioEffectHighPassFilter ========================= -**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Adds a high-pass filter to the Audio Bus. +Adds a high-pass filter to the audio bus. + +.. rst-class:: classref-introduction-group Description ----------- Cuts frequencies lower than the :ref:`AudioEffectFilter.cutoff_hz` and allows higher frequencies to pass. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffecthighshelffilter.rst b/classes/class_audioeffecthighshelffilter.rst index 1e24a4f496b..7c7e01d55ba 100644 --- a/classes/class_audioeffecthighshelffilter.rst +++ b/classes/class_audioeffecthighshelffilter.rst @@ -1,15 +1,39 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectHighShelfFilter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectHighShelfFilter.xml. .. _class_AudioEffectHighShelfFilter: AudioEffectHighShelfFilter ========================== -**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` +Adds a high-shelf filter to the audio bus. +.. rst-class:: classref-introduction-group +Description +----------- + +Reduces all frequencies above the :ref:`AudioEffectFilter.cutoff_hz`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectinstance.rst b/classes/class_audioeffectinstance.rst index 5cc23c22029..6d55bf36234 100644 --- a/classes/class_audioeffectinstance.rst +++ b/classes/class_audioeffectinstance.rst @@ -1,17 +1,88 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectInstance.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectInstance.xml. .. _class_AudioEffectInstance: AudioEffectInstance =================== -**Inherits:** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` **Inherited By:** :ref:`AudioEffectSpectrumAnalyzerInstance` +Manipulates the audio it receives for a given effect. +.. rst-class:: classref-introduction-group +Description +----------- + +An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an :ref:`AudioEffect` when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with :ref:`AudioServer.get_bus_effect_instance()`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_process`\ (\ src_buffer\: ``const void*``, dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| |required| | + +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_process_silence`\ (\ ) |virtual| |const| | + +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioEffectInstance_private_method__process: + +.. rst-class:: classref-method + +|void| **_process**\ (\ src_buffer\: ``const void*``, dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| |required| :ref:`🔗` + +Called by the :ref:`AudioServer` to process this effect. When :ref:`_process_silence()` is not overridden or it returns ``false``, this method is called only when the bus is active. + +\ **Note:** It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectInstance_private_method__process_silence: + +.. rst-class:: classref-method + +:ref:`bool` **_process_silence**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to customize the processing behavior of this effect instance. + +Should return ``true`` to force the :ref:`AudioServer` to always call :ref:`_process()`, even if the bus has been muted or cannot otherwise be heard. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectlimiter.rst b/classes/class_audioeffectlimiter.rst index 8ac78d5270a..652e2dd426b 100644 --- a/classes/class_audioeffectlimiter.rst +++ b/classes/class_audioeffectlimiter.rst @@ -1,18 +1,23 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectLimiter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectLimiter.xml. .. _class_AudioEffectLimiter: AudioEffectLimiter ================== -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Deprecated:** Use :ref:`AudioEffectHardLimiter` instead. + +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a soft-clip limiter audio effect to an Audio bus. +.. rst-class:: classref-introduction-group + Description ----------- @@ -20,79 +25,112 @@ A limiter is similar to a compressor, but it's less flexible and designed to dis Soft clipping starts to reduce the peaks a little below the threshold level and progressively increases its effect as the input level increases such that the threshold is never exceeded. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+---------------------------+---------------------------------------------------------------------------+----------+ -| :ref:`float` | :ref:`ceiling_db` | ``-0.1`` | -+---------------------------+---------------------------------------------------------------------------+----------+ -| :ref:`float` | :ref:`soft_clip_db` | ``2.0`` | -+---------------------------+---------------------------------------------------------------------------+----------+ -| :ref:`float` | :ref:`soft_clip_ratio` | ``10.0`` | -+---------------------------+---------------------------------------------------------------------------+----------+ -| :ref:`float` | :ref:`threshold_db` | ``0.0`` | -+---------------------------+---------------------------------------------------------------------------+----------+ +.. table:: + :widths: auto + + +---------------------------+---------------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`ceiling_db` | ``-0.1`` | + +---------------------------+---------------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`soft_clip_db` | ``2.0`` | + +---------------------------+---------------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`soft_clip_ratio` | ``10.0`` | + +---------------------------+---------------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`threshold_db` | ``0.0`` | + +---------------------------+---------------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectLimiter_property_ceiling_db: -- :ref:`float` **ceiling_db** +.. rst-class:: classref-property + +:ref:`float` **ceiling_db** = ``-0.1`` :ref:`🔗` -+-----------+-----------------------+ -| *Default* | ``-0.1`` | -+-----------+-----------------------+ -| *Setter* | set_ceiling_db(value) | -+-----------+-----------------------+ -| *Getter* | get_ceiling_db() | -+-----------+-----------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_ceiling_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_ceiling_db**\ (\ ) The waveform's maximum allowed value, in decibels. Value can range from -20 to -0.1. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectLimiter_property_soft_clip_db: -- :ref:`float` **soft_clip_db** +.. rst-class:: classref-property + +:ref:`float` **soft_clip_db** = ``2.0`` :ref:`🔗` -+-----------+-------------------------+ -| *Default* | ``2.0`` | -+-----------+-------------------------+ -| *Setter* | set_soft_clip_db(value) | -+-----------+-------------------------+ -| *Getter* | get_soft_clip_db() | -+-----------+-------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_soft_clip_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_soft_clip_db**\ (\ ) Applies a gain to the limited waves, in decibels. Value can range from 0 to 6. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectLimiter_property_soft_clip_ratio: -- :ref:`float` **soft_clip_ratio** +.. rst-class:: classref-property + +:ref:`float` **soft_clip_ratio** = ``10.0`` :ref:`🔗` -+-----------+----------------------------+ -| *Default* | ``10.0`` | -+-----------+----------------------------+ -| *Setter* | set_soft_clip_ratio(value) | -+-----------+----------------------------+ -| *Getter* | get_soft_clip_ratio() | -+-----------+----------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_soft_clip_ratio**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_soft_clip_ratio**\ (\ ) + +.. container:: contribute + + There is currently no description for this property. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectLimiter_property_threshold_db: -- :ref:`float` **threshold_db** +.. rst-class:: classref-property + +:ref:`float` **threshold_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------------+ -| *Setter* | set_threshold_db(value) | -+-----------+-------------------------+ -| *Getter* | get_threshold_db() | -+-----------+-------------------------+ +- |void| **set_threshold_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_threshold_db**\ (\ ) Threshold from which the limiter begins to be active, in decibels. Value can range from -30 to 0. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectlowpassfilter.rst b/classes/class_audioeffectlowpassfilter.rst index 53a9d49d1f4..6975557b248 100644 --- a/classes/class_audioeffectlowpassfilter.rst +++ b/classes/class_audioeffectlowpassfilter.rst @@ -1,20 +1,39 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectLowPassFilter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectLowPassFilter.xml. .. _class_AudioEffectLowPassFilter: AudioEffectLowPassFilter ======================== -**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Adds a low-pass filter to the Audio bus. +Adds a low-pass filter to the audio bus. + +.. rst-class:: classref-introduction-group Description ----------- Cuts frequencies higher than the :ref:`AudioEffectFilter.cutoff_hz` and allows lower frequencies to pass. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectlowshelffilter.rst b/classes/class_audioeffectlowshelffilter.rst index aa026543243..33e2b5653f6 100644 --- a/classes/class_audioeffectlowshelffilter.rst +++ b/classes/class_audioeffectlowshelffilter.rst @@ -1,15 +1,39 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectLowShelfFilter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectLowShelfFilter.xml. .. _class_AudioEffectLowShelfFilter: AudioEffectLowShelfFilter ========================= -**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` +Adds a low-shelf filter to the audio bus. +.. rst-class:: classref-introduction-group +Description +----------- + +Reduces all frequencies below the :ref:`AudioEffectFilter.cutoff_hz`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectnotchfilter.rst b/classes/class_audioeffectnotchfilter.rst index 92adb4be8d1..d701c1b46bc 100644 --- a/classes/class_audioeffectnotchfilter.rst +++ b/classes/class_audioeffectnotchfilter.rst @@ -1,20 +1,39 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectNotchFilter.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectNotchFilter.xml. .. _class_AudioEffectNotchFilter: AudioEffectNotchFilter ====================== -**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a notch filter to the Audio bus. +.. rst-class:: classref-introduction-group + Description ----------- Attenuates frequencies in a narrow band around the :ref:`AudioEffectFilter.cutoff_hz` and cuts frequencies outside of this range. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectpanner.rst b/classes/class_audioeffectpanner.rst index 1e947be1d9f..6927fb5b8d3 100644 --- a/classes/class_audioeffectpanner.rst +++ b/classes/class_audioeffectpanner.rst @@ -1,44 +1,73 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectPanner.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectPanner.xml. .. _class_AudioEffectPanner: AudioEffectPanner ================= -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Adds a panner audio effect to an Audio bus. Pans sound left or right. +Adds a panner audio effect to an audio bus. Pans sound left or right. + +.. rst-class:: classref-introduction-group Description ----------- Determines how much of an audio signal is sent to the left and right buses. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+---------------------------+--------------------------------------------------+---------+ -| :ref:`float` | :ref:`pan` | ``0.0`` | -+---------------------------+--------------------------------------------------+---------+ +.. table:: + :widths: auto + + +---------------------------+--------------------------------------------------+---------+ + | :ref:`float` | :ref:`pan` | ``0.0`` | + +---------------------------+--------------------------------------------------+---------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectPanner_property_pan: -- :ref:`float` **pan** +.. rst-class:: classref-property + +:ref:`float` **pan** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------+ -| *Default* | ``0.0`` | -+-----------+----------------+ -| *Setter* | set_pan(value) | -+-----------+----------------+ -| *Getter* | get_pan() | -+-----------+----------------+ +- |void| **set_pan**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pan**\ (\ ) Pan position. Value can range from -1 (fully left) to 1 (fully right). +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectphaser.rst b/classes/class_audioeffectphaser.rst index 617e2f14685..9f696b69b75 100644 --- a/classes/class_audioeffectphaser.rst +++ b/classes/class_audioeffectphaser.rst @@ -1,118 +1,151 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectPhaser.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectPhaser.xml. .. _class_AudioEffectPhaser: AudioEffectPhaser ================= -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Adds a phaser audio effect to an Audio bus. +Adds a phaser audio effect to an audio bus. Combines the original signal with a copy that is slightly out of phase with the original. +.. rst-class:: classref-introduction-group + Description ----------- Combines phase-shifted signals with the original signal. The movement of the phase-shifted signals is controlled using a low-frequency oscillator. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+---------------------------+--------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`depth` | ``1.0`` | -+---------------------------+--------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`feedback` | ``0.7`` | -+---------------------------+--------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`range_max_hz` | ``1600.0`` | -+---------------------------+--------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`range_min_hz` | ``440.0`` | -+---------------------------+--------------------------------------------------------------------+------------+ -| :ref:`float` | :ref:`rate_hz` | ``0.5`` | -+---------------------------+--------------------------------------------------------------------+------------+ +.. table:: + :widths: auto + + +---------------------------+--------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`depth` | ``1.0`` | + +---------------------------+--------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`feedback` | ``0.7`` | + +---------------------------+--------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`range_max_hz` | ``1600.0`` | + +---------------------------+--------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`range_min_hz` | ``440.0`` | + +---------------------------+--------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`rate_hz` | ``0.5`` | + +---------------------------+--------------------------------------------------------------------+------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectPhaser_property_depth: -- :ref:`float` **depth** +.. rst-class:: classref-property + +:ref:`float` **depth** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------+ -| *Default* | ``1.0`` | -+-----------+------------------+ -| *Setter* | set_depth(value) | -+-----------+------------------+ -| *Getter* | get_depth() | -+-----------+------------------+ +- |void| **set_depth**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_depth**\ (\ ) -Governs how high the filter frequencies sweep. Low value will primarily affect bass frequencies. High value can sweep high into the treble. Value can range from 0.1 to 4. +Determines how high the filter frequencies sweep. Low value will primarily affect bass frequencies. High value can sweep high into the treble. Value can range from ``0.1`` to ``4.0``. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectPhaser_property_feedback: -- :ref:`float` **feedback** +.. rst-class:: classref-property + +:ref:`float` **feedback** = ``0.7`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``0.7`` | -+-----------+---------------------+ -| *Setter* | set_feedback(value) | -+-----------+---------------------+ -| *Getter* | get_feedback() | -+-----------+---------------------+ +- |void| **set_feedback**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_feedback**\ (\ ) Output percent of modified sound. Value can range from 0.1 to 0.9. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectPhaser_property_range_max_hz: -- :ref:`float` **range_max_hz** +.. rst-class:: classref-property + +:ref:`float` **range_max_hz** = ``1600.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``1600.0`` | -+-----------+-------------------------+ -| *Setter* | set_range_max_hz(value) | -+-----------+-------------------------+ -| *Getter* | get_range_max_hz() | -+-----------+-------------------------+ +- |void| **set_range_max_hz**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_range_max_hz**\ (\ ) Determines the maximum frequency affected by the LFO modulations, in Hz. Value can range from 10 to 10000. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectPhaser_property_range_min_hz: -- :ref:`float` **range_min_hz** +.. rst-class:: classref-property + +:ref:`float` **range_min_hz** = ``440.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``440.0`` | -+-----------+-------------------------+ -| *Setter* | set_range_min_hz(value) | -+-----------+-------------------------+ -| *Getter* | get_range_min_hz() | -+-----------+-------------------------+ +- |void| **set_range_min_hz**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_range_min_hz**\ (\ ) Determines the minimum frequency affected by the LFO modulations, in Hz. Value can range from 10 to 10000. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectPhaser_property_rate_hz: -- :ref:`float` **rate_hz** +.. rst-class:: classref-property + +:ref:`float` **rate_hz** = ``0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+--------------------+ -| *Default* | ``0.5`` | -+-----------+--------------------+ -| *Setter* | set_rate_hz(value) | -+-----------+--------------------+ -| *Getter* | get_rate_hz() | -+-----------+--------------------+ +- |void| **set_rate_hz**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_rate_hz**\ (\ ) Adjusts the rate in Hz at which the effect sweeps up and down across the frequency range. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectpitchshift.rst b/classes/class_audioeffectpitchshift.rst index 91339af5ab3..bde396a6197 100644 --- a/classes/class_audioeffectpitchshift.rst +++ b/classes/class_audioeffectpitchshift.rst @@ -1,109 +1,176 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectPitchShift.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectPitchShift.xml. .. _class_AudioEffectPitchShift: AudioEffectPitchShift ===================== -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Adds a pitch-shifting audio effect to an Audio bus. +Adds a pitch-shifting audio effect to an audio bus. Raises or lowers the pitch of original sound. +.. rst-class:: classref-introduction-group + Description ----------- Allows modulation of pitch independently of tempo. All frequencies can be increased/decreased with minimal effect on transients. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + Properties ---------- -+------------------------------------------------------+------------------------------------------------------------------------+---------+ -| :ref:`FFT_Size` | :ref:`fft_size` | ``3`` | -+------------------------------------------------------+------------------------------------------------------------------------+---------+ -| :ref:`int` | :ref:`oversampling` | ``4`` | -+------------------------------------------------------+------------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`pitch_scale` | ``1.0`` | -+------------------------------------------------------+------------------------------------------------------------------------+---------+ +.. table:: + :widths: auto + + +----------------------------------------------------+------------------------------------------------------------------------+---------+ + | :ref:`FFTSize` | :ref:`fft_size` | ``3`` | + +----------------------------------------------------+------------------------------------------------------------------------+---------+ + | :ref:`int` | :ref:`oversampling` | ``4`` | + +----------------------------------------------------+------------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`pitch_scale` | ``1.0`` | + +----------------------------------------------------+------------------------------------------------------------------------+---------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ -.. _enum_AudioEffectPitchShift_FFT_Size: +.. _enum_AudioEffectPitchShift_FFTSize: + +.. rst-class:: classref-enumeration + +enum **FFTSize**: :ref:`🔗` .. _class_AudioEffectPitchShift_constant_FFT_SIZE_256: +.. rst-class:: classref-enumeration-constant + +:ref:`FFTSize` **FFT_SIZE_256** = ``0`` + +Use a buffer of 256 samples for the Fast Fourier transform. Lowest latency, but least stable over time. + .. _class_AudioEffectPitchShift_constant_FFT_SIZE_512: +.. rst-class:: classref-enumeration-constant + +:ref:`FFTSize` **FFT_SIZE_512** = ``1`` + +Use a buffer of 512 samples for the Fast Fourier transform. Low latency, but less stable over time. + .. _class_AudioEffectPitchShift_constant_FFT_SIZE_1024: +.. rst-class:: classref-enumeration-constant + +:ref:`FFTSize` **FFT_SIZE_1024** = ``2`` + +Use a buffer of 1024 samples for the Fast Fourier transform. This is a compromise between latency and stability over time. + .. _class_AudioEffectPitchShift_constant_FFT_SIZE_2048: +.. rst-class:: classref-enumeration-constant + +:ref:`FFTSize` **FFT_SIZE_2048** = ``3`` + +Use a buffer of 2048 samples for the Fast Fourier transform. High latency, but stable over time. + .. _class_AudioEffectPitchShift_constant_FFT_SIZE_4096: -.. _class_AudioEffectPitchShift_constant_FFT_SIZE_MAX: +.. rst-class:: classref-enumeration-constant -enum **FFT_Size**: +:ref:`FFTSize` **FFT_SIZE_4096** = ``4`` -- **FFT_SIZE_256** = **0** +Use a buffer of 4096 samples for the Fast Fourier transform. Highest latency, but most stable over time. -- **FFT_SIZE_512** = **1** +.. _class_AudioEffectPitchShift_constant_FFT_SIZE_MAX: + +.. rst-class:: classref-enumeration-constant -- **FFT_SIZE_1024** = **2** +:ref:`FFTSize` **FFT_SIZE_MAX** = ``5`` -- **FFT_SIZE_2048** = **3** +Represents the size of the :ref:`FFTSize` enum. -- **FFT_SIZE_4096** = **4** +.. rst-class:: classref-section-separator -- **FFT_SIZE_MAX** = **5** --- Represents the size of the :ref:`FFT_Size` enum. +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectPitchShift_property_fft_size: -- :ref:`FFT_Size` **fft_size** +.. rst-class:: classref-property + +:ref:`FFTSize` **fft_size** = ``3`` :ref:`🔗` -+-----------+---------------------+ -| *Default* | ``3`` | -+-----------+---------------------+ -| *Setter* | set_fft_size(value) | -+-----------+---------------------+ -| *Getter* | get_fft_size() | -+-----------+---------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_fft_size**\ (\ value\: :ref:`FFTSize`\ ) +- :ref:`FFTSize` **get_fft_size**\ (\ ) + +The size of the `Fast Fourier transform `__ buffer. Higher values smooth out the effect over time, but have greater latency. The effects of this higher latency are especially noticeable on sounds that have sudden amplitude changes. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectPitchShift_property_oversampling: -- :ref:`int` **oversampling** +.. rst-class:: classref-property + +:ref:`int` **oversampling** = ``4`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``4`` | -+-----------+-------------------------+ -| *Setter* | set_oversampling(value) | -+-----------+-------------------------+ -| *Getter* | get_oversampling() | -+-----------+-------------------------+ +- |void| **set_oversampling**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_oversampling**\ (\ ) + +The oversampling factor to use. Higher values result in better quality, but are more demanding on the CPU and may cause audio cracking if the CPU can't keep up. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectPitchShift_property_pitch_scale: -- :ref:`float` **pitch_scale** +.. rst-class:: classref-property + +:ref:`float` **pitch_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_pitch_scale(value) | -+-----------+------------------------+ -| *Getter* | get_pitch_scale() | -+-----------+------------------------+ +- |void| **set_pitch_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pitch_scale**\ (\ ) -Pitch value. Can range from 0 (-1 octave) to 16 (+16 octaves). +The pitch scale to use. ``1.0`` is the default pitch and plays sounds unaffected. :ref:`pitch_scale` can range from ``0.0`` (infinitely low pitch, inaudible) to ``16`` (16 times higher than the initial pitch). +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectrecord.rst b/classes/class_audioeffectrecord.rst index 366d6d2313e..cb5eccc6914 100644 --- a/classes/class_audioeffectrecord.rst +++ b/classes/class_audioeffectrecord.rst @@ -1,80 +1,138 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectRecord.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectRecord.xml. .. _class_AudioEffectRecord: AudioEffectRecord ================= -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Audio effect used for recording sound from a microphone. +Audio effect used for recording the sound from an audio bus. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Allows the user to record the sound from an audio bus into an :ref:`AudioStreamWAV`. When used on the "Master" audio bus, this includes all audio output by Godot. + +Unlike :ref:`AudioEffectCapture`, this effect encodes the recording with the given format (8-bit, 16-bit, or compressed) instead of giving access to the raw audio samples. + +Can be used (with an :ref:`AudioStreamMicrophone`) to record from a microphone. + +\ **Note:** :ref:`ProjectSettings.audio/driver/enable_input` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/audio/recording_with_microphone` +- :doc:`Recording with microphone <../tutorials/audio/recording_with_microphone>` + +- `Audio Microphone Record Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+----------------------------------------------+--------------------------------------------------------+-------+ -| :ref:`Format` | :ref:`format` | ``1`` | -+----------------------------------------------+--------------------------------------------------------+-------+ +.. table:: + :widths: auto + + +-------------------------------------------+--------------------------------------------------------+-------+ + | :ref:`Format` | :ref:`format` | ``1`` | + +-------------------------------------------+--------------------------------------------------------+-------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AudioStreamSample` | :ref:`get_recording` **(** **)** const | -+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_recording_active` **(** **)** const | -+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_recording_active` **(** :ref:`bool` record **)** | -+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamWAV` | :ref:`get_recording`\ (\ ) |const| | + +---------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_recording_active`\ (\ ) |const| | + +---------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_recording_active`\ (\ record\: :ref:`bool`\ ) | + +---------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectRecord_property_format: -- :ref:`Format` **format** +.. rst-class:: classref-property + +:ref:`Format` **format** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------+ -| *Default* | ``1`` | -+-----------+-------------------+ -| *Setter* | set_format(value) | -+-----------+-------------------+ -| *Getter* | get_format() | -+-----------+-------------------+ +- |void| **set_format**\ (\ value\: :ref:`Format`\ ) +- :ref:`Format` **get_format**\ (\ ) -Specifies the format in which the sample will be recorded. See :ref:`Format` for available formats. +Specifies the format in which the sample will be recorded. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AudioEffectRecord_method_get_recording: -- :ref:`AudioStreamSample` **get_recording** **(** **)** const +.. rst-class:: classref-method + +:ref:`AudioStreamWAV` **get_recording**\ (\ ) |const| :ref:`🔗` Returns the recorded sample. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectRecord_method_is_recording_active: -- :ref:`bool` **is_recording_active** **(** **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_recording_active**\ (\ ) |const| :ref:`🔗` Returns whether the recording is active or not. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectRecord_method_set_recording_active: -- void **set_recording_active** **(** :ref:`bool` record **)** +.. rst-class:: classref-method + +|void| **set_recording_active**\ (\ record\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the sound will be recorded. Note that restarting the recording will remove the previously recorded sample. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectreverb.rst b/classes/class_audioeffectreverb.rst index b0ea1157a7f..7b82e1f9273 100644 --- a/classes/class_audioeffectreverb.rst +++ b/classes/class_audioeffectreverb.rst @@ -1,172 +1,208 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectReverb.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectReverb.xml. .. _class_AudioEffectReverb: AudioEffectReverb ================= -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a reverberation audio effect to an Audio bus. -Simulates the sound of acoustic environments such as rooms, concert halls, caverns, or an open spaces. +.. rst-class:: classref-introduction-group Description ----------- -Simulates rooms of different sizes. Its parameters can be adjusted to simulate the sound of a specific room. +Simulates the sound of acoustic environments such as rooms, concert halls, caverns, or an open spaces. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`damping` | ``0.5`` | -+---------------------------+------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`dry` | ``1.0`` | -+---------------------------+------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`hipass` | ``0.0`` | -+---------------------------+------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`predelay_feedback` | ``0.4`` | -+---------------------------+------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`predelay_msec` | ``150.0`` | -+---------------------------+------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`room_size` | ``0.8`` | -+---------------------------+------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`spread` | ``1.0`` | -+---------------------------+------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`wet` | ``0.5`` | -+---------------------------+------------------------------------------------------------------------------+-----------+ +.. table:: + :widths: auto + + +---------------------------+------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`damping` | ``0.5`` | + +---------------------------+------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`dry` | ``1.0`` | + +---------------------------+------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`hipass` | ``0.0`` | + +---------------------------+------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`predelay_feedback` | ``0.4`` | + +---------------------------+------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`predelay_msec` | ``150.0`` | + +---------------------------+------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`room_size` | ``0.8`` | + +---------------------------+------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`spread` | ``1.0`` | + +---------------------------+------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`wet` | ``0.5`` | + +---------------------------+------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectReverb_property_damping: -- :ref:`float` **damping** +.. rst-class:: classref-property + +:ref:`float` **damping** = ``0.5`` :ref:`🔗` -+-----------+--------------------+ -| *Default* | ``0.5`` | -+-----------+--------------------+ -| *Setter* | set_damping(value) | -+-----------+--------------------+ -| *Getter* | get_damping() | -+-----------+--------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_damping**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_damping**\ (\ ) Defines how reflective the imaginary room's walls are. Value can range from 0 to 1. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectReverb_property_dry: -- :ref:`float` **dry** +.. rst-class:: classref-property -+-----------+----------------+ -| *Default* | ``1.0`` | -+-----------+----------------+ -| *Setter* | set_dry(value) | -+-----------+----------------+ -| *Getter* | get_dry() | -+-----------+----------------+ +:ref:`float` **dry** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dry**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_dry**\ (\ ) Output percent of original sound. At 0, only modified sound is outputted. Value can range from 0 to 1. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectReverb_property_hipass: -- :ref:`float` **hipass** +.. rst-class:: classref-property + +:ref:`float` **hipass** = ``0.0`` :ref:`🔗` -+-----------+----------------+ -| *Default* | ``0.0`` | -+-----------+----------------+ -| *Setter* | set_hpf(value) | -+-----------+----------------+ -| *Getter* | get_hpf() | -+-----------+----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_hpf**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_hpf**\ (\ ) High-pass filter passes signals with a frequency higher than a certain cutoff frequency and attenuates signals with frequencies lower than the cutoff frequency. Value can range from 0 to 1. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectReverb_property_predelay_feedback: -- :ref:`float` **predelay_feedback** +.. rst-class:: classref-property + +:ref:`float` **predelay_feedback** = ``0.4`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------------+ -| *Default* | ``0.4`` | -+-----------+------------------------------+ -| *Setter* | set_predelay_feedback(value) | -+-----------+------------------------------+ -| *Getter* | get_predelay_feedback() | -+-----------+------------------------------+ +- |void| **set_predelay_feedback**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_predelay_feedback**\ (\ ) Output percent of predelay. Value can range from 0 to 1. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectReverb_property_predelay_msec: -- :ref:`float` **predelay_msec** +.. rst-class:: classref-property + +:ref:`float` **predelay_msec** = ``150.0`` :ref:`🔗` -+-----------+--------------------------+ -| *Default* | ``150.0`` | -+-----------+--------------------------+ -| *Setter* | set_predelay_msec(value) | -+-----------+--------------------------+ -| *Getter* | get_predelay_msec() | -+-----------+--------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_predelay_msec**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_predelay_msec**\ (\ ) Time between the original signal and the early reflections of the reverb signal, in milliseconds. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectReverb_property_room_size: -- :ref:`float` **room_size** +.. rst-class:: classref-property -+-----------+----------------------+ -| *Default* | ``0.8`` | -+-----------+----------------------+ -| *Setter* | set_room_size(value) | -+-----------+----------------------+ -| *Getter* | get_room_size() | -+-----------+----------------------+ +:ref:`float` **room_size** = ``0.8`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_room_size**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_room_size**\ (\ ) Dimensions of simulated room. Bigger means more echoes. Value can range from 0 to 1. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectReverb_property_spread: -- :ref:`float` **spread** +.. rst-class:: classref-property + +:ref:`float` **spread** = ``1.0`` :ref:`🔗` -+-----------+-------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------+ -| *Setter* | set_spread(value) | -+-----------+-------------------+ -| *Getter* | get_spread() | -+-----------+-------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_spread**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_spread**\ (\ ) Widens or narrows the stereo image of the reverb tail. 1 means fully widens. Value can range from 0 to 1. +.. rst-class:: classref-item-separator + ---- .. _class_AudioEffectReverb_property_wet: -- :ref:`float` **wet** +.. rst-class:: classref-property + +:ref:`float` **wet** = ``0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------+ -| *Default* | ``0.5`` | -+-----------+----------------+ -| *Setter* | set_wet(value) | -+-----------+----------------+ -| *Getter* | get_wet() | -+-----------+----------------+ +- |void| **set_wet**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_wet**\ (\ ) Output percent of modified sound. At 0, only original sound is outputted. Value can range from 0 to 1. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectspectrumanalyzer.rst b/classes/class_audioeffectspectrumanalyzer.rst index 565fc728734..b769cec6ff3 100644 --- a/classes/class_audioeffectspectrumanalyzer.rst +++ b/classes/class_audioeffectspectrumanalyzer.rst @@ -1,100 +1,180 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectSpectrumAnalyzer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectSpectrumAnalyzer.xml. .. _class_AudioEffectSpectrumAnalyzer: AudioEffectSpectrumAnalyzer =========================== -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` +Audio effect that can be used for real-time audio visualizations. +.. rst-class:: classref-introduction-group + +Description +----------- + +This audio effect does not affect sound output, but can be used for real-time audio visualizations. + +This resource configures an :ref:`AudioEffectSpectrumAnalyzerInstance`, which performs the actual analysis at runtime. An instance can be obtained with :ref:`AudioServer.get_bus_effect_instance()`. + +See also :ref:`AudioStreamGenerator` for procedurally generating sounds. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Audio Spectrum Visualizer Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+------------------------------------------------------------+--------------------------------------------------------------------------------+----------+ -| :ref:`float` | :ref:`buffer_length` | ``2.0`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+----------+ -| :ref:`FFT_Size` | :ref:`fft_size` | ``2`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+----------+ -| :ref:`float` | :ref:`tap_back_pos` | ``0.01`` | -+------------------------------------------------------------+--------------------------------------------------------------------------------+----------+ +.. table:: + :widths: auto + + +----------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`buffer_length` | ``2.0`` | + +----------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`FFTSize` | :ref:`fft_size` | ``2`` | + +----------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`tap_back_pos` | ``0.01`` | + +----------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ -.. _enum_AudioEffectSpectrumAnalyzer_FFT_Size: +.. _enum_AudioEffectSpectrumAnalyzer_FFTSize: + +.. rst-class:: classref-enumeration + +enum **FFTSize**: :ref:`🔗` .. _class_AudioEffectSpectrumAnalyzer_constant_FFT_SIZE_256: +.. rst-class:: classref-enumeration-constant + +:ref:`FFTSize` **FFT_SIZE_256** = ``0`` + +Use a buffer of 256 samples for the Fast Fourier transform. Lowest latency, but least stable over time. + .. _class_AudioEffectSpectrumAnalyzer_constant_FFT_SIZE_512: +.. rst-class:: classref-enumeration-constant + +:ref:`FFTSize` **FFT_SIZE_512** = ``1`` + +Use a buffer of 512 samples for the Fast Fourier transform. Low latency, but less stable over time. + .. _class_AudioEffectSpectrumAnalyzer_constant_FFT_SIZE_1024: +.. rst-class:: classref-enumeration-constant + +:ref:`FFTSize` **FFT_SIZE_1024** = ``2`` + +Use a buffer of 1024 samples for the Fast Fourier transform. This is a compromise between latency and stability over time. + .. _class_AudioEffectSpectrumAnalyzer_constant_FFT_SIZE_2048: +.. rst-class:: classref-enumeration-constant + +:ref:`FFTSize` **FFT_SIZE_2048** = ``3`` + +Use a buffer of 2048 samples for the Fast Fourier transform. High latency, but stable over time. + .. _class_AudioEffectSpectrumAnalyzer_constant_FFT_SIZE_4096: -.. _class_AudioEffectSpectrumAnalyzer_constant_FFT_SIZE_MAX: +.. rst-class:: classref-enumeration-constant -enum **FFT_Size**: +:ref:`FFTSize` **FFT_SIZE_4096** = ``4`` -- **FFT_SIZE_256** = **0** +Use a buffer of 4096 samples for the Fast Fourier transform. Highest latency, but most stable over time. -- **FFT_SIZE_512** = **1** +.. _class_AudioEffectSpectrumAnalyzer_constant_FFT_SIZE_MAX: + +.. rst-class:: classref-enumeration-constant -- **FFT_SIZE_1024** = **2** +:ref:`FFTSize` **FFT_SIZE_MAX** = ``5`` -- **FFT_SIZE_2048** = **3** +Represents the size of the :ref:`FFTSize` enum. -- **FFT_SIZE_4096** = **4** +.. rst-class:: classref-section-separator -- **FFT_SIZE_MAX** = **5** --- Represents the size of the :ref:`FFT_Size` enum. +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectSpectrumAnalyzer_property_buffer_length: -- :ref:`float` **buffer_length** +.. rst-class:: classref-property + +:ref:`float` **buffer_length** = ``2.0`` :ref:`🔗` -+-----------+--------------------------+ -| *Default* | ``2.0`` | -+-----------+--------------------------+ -| *Setter* | set_buffer_length(value) | -+-----------+--------------------------+ -| *Getter* | get_buffer_length() | -+-----------+--------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_buffer_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_buffer_length**\ (\ ) + +The length of the buffer to keep (in seconds). Higher values keep data around for longer, but require more memory. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectSpectrumAnalyzer_property_fft_size: -- :ref:`FFT_Size` **fft_size** +.. rst-class:: classref-property + +:ref:`FFTSize` **fft_size** = ``2`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_fft_size**\ (\ value\: :ref:`FFTSize`\ ) +- :ref:`FFTSize` **get_fft_size**\ (\ ) -+-----------+---------------------+ -| *Default* | ``2`` | -+-----------+---------------------+ -| *Setter* | set_fft_size(value) | -+-----------+---------------------+ -| *Getter* | get_fft_size() | -+-----------+---------------------+ +The size of the `Fast Fourier transform `__ buffer. Higher values smooth out the spectrum analysis over time, but have greater latency. The effects of this higher latency are especially noticeable with sudden amplitude changes. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectSpectrumAnalyzer_property_tap_back_pos: -- :ref:`float` **tap_back_pos** +.. rst-class:: classref-property + +:ref:`float` **tap_back_pos** = ``0.01`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_tap_back_pos**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_tap_back_pos**\ (\ ) + +.. container:: contribute -+-----------+-------------------------+ -| *Default* | ``0.01`` | -+-----------+-------------------------+ -| *Setter* | set_tap_back_pos(value) | -+-----------+-------------------------+ -| *Getter* | get_tap_back_pos() | -+-----------+-------------------------+ + There is currently no description for this property. Please help us by `contributing one `__! +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectspectrumanalyzerinstance.rst b/classes/class_audioeffectspectrumanalyzerinstance.rst index 5160d104abb..bcabc22201a 100644 --- a/classes/class_audioeffectspectrumanalyzerinstance.rst +++ b/classes/class_audioeffectspectrumanalyzerinstance.rst @@ -1,44 +1,103 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectSpectrumAnalyzerInstance.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectSpectrumAnalyzerInstance.xml. .. _class_AudioEffectSpectrumAnalyzerInstance: AudioEffectSpectrumAnalyzerInstance =================================== -**Inherits:** :ref:`AudioEffectInstance` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffectInstance` **<** :ref:`RefCounted` **<** :ref:`Object` +Queryable instance of an :ref:`AudioEffectSpectrumAnalyzer`. +.. rst-class:: classref-introduction-group + +Description +----------- + +The runtime part of an :ref:`AudioEffectSpectrumAnalyzer`, which can be used to query the magnitude of a frequency range on its host bus. + +An instance of this class can be obtained with :ref:`AudioServer.get_bus_effect_instance()`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Audio Spectrum Visualizer Demo `__ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_magnitude_for_frequency_range` **(** :ref:`float` from_hz, :ref:`float` to_hz, :ref:`MagnitudeMode` mode=1 **)** const | -+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_magnitude_for_frequency_range`\ (\ from_hz\: :ref:`float`, to_hz\: :ref:`float`, mode\: :ref:`MagnitudeMode` = 1\ ) |const| | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_AudioEffectSpectrumAnalyzerInstance_MagnitudeMode: +.. rst-class:: classref-enumeration + +enum **MagnitudeMode**: :ref:`🔗` + .. _class_AudioEffectSpectrumAnalyzerInstance_constant_MAGNITUDE_AVERAGE: +.. rst-class:: classref-enumeration-constant + +:ref:`MagnitudeMode` **MAGNITUDE_AVERAGE** = ``0`` + +Use the average value across the frequency range as magnitude. + .. _class_AudioEffectSpectrumAnalyzerInstance_constant_MAGNITUDE_MAX: -enum **MagnitudeMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`MagnitudeMode` **MAGNITUDE_MAX** = ``1`` -- **MAGNITUDE_AVERAGE** = **0** --- Use the average value as magnitude. +Use the maximum value of the frequency range as magnitude. -- **MAGNITUDE_MAX** = **1** --- Use the maximum value as magnitude. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AudioEffectSpectrumAnalyzerInstance_method_get_magnitude_for_frequency_range: -- :ref:`Vector2` **get_magnitude_for_frequency_range** **(** :ref:`float` from_hz, :ref:`float` to_hz, :ref:`MagnitudeMode` mode=1 **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **get_magnitude_for_frequency_range**\ (\ from_hz\: :ref:`float`, to_hz\: :ref:`float`, mode\: :ref:`MagnitudeMode` = 1\ ) |const| :ref:`🔗` + +Returns the magnitude of the frequencies from ``from_hz`` to ``to_hz`` in linear energy as a Vector2. The ``x`` component of the return value represents the left stereo channel, and ``y`` represents the right channel. + +\ ``mode`` determines how the frequency range will be processed. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffectstereoenhance.rst b/classes/class_audioeffectstereoenhance.rst index 08866c2bcc9..7d492e9ca5b 100644 --- a/classes/class_audioeffectstereoenhance.rst +++ b/classes/class_audioeffectstereoenhance.rst @@ -1,69 +1,111 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioEffectStereoEnhance.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioEffectStereoEnhance.xml. .. _class_AudioEffectStereoEnhance: AudioEffectStereoEnhance ======================== -**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` +An audio effect that can be used to adjust the intensity of stereo panning. +.. rst-class:: classref-introduction-group + +Description +----------- + +An audio effect that can be used to adjust the intensity of stereo panning. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+---------------------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`pan_pullout` | ``1.0`` | -+---------------------------+---------------------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`surround` | ``0.0`` | -+---------------------------+---------------------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`time_pullout_ms` | ``0.0`` | -+---------------------------+---------------------------------------------------------------------------------+---------+ +.. table:: + :widths: auto + + +---------------------------+---------------------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`pan_pullout` | ``1.0`` | + +---------------------------+---------------------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`surround` | ``0.0`` | + +---------------------------+---------------------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`time_pullout_ms` | ``0.0`` | + +---------------------------+---------------------------------------------------------------------------------+---------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioEffectStereoEnhance_property_pan_pullout: -- :ref:`float` **pan_pullout** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_pan_pullout(value) | -+-----------+------------------------+ -| *Getter* | get_pan_pullout() | -+-----------+------------------------+ +:ref:`float` **pan_pullout** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pan_pullout**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pan_pullout**\ (\ ) + +Amplifies the difference between stereo channels, increasing or decreasing existing panning. A value of 0.0 will downmix stereo to mono. Does not affect a mono signal. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectStereoEnhance_property_surround: -- :ref:`float` **surround** +.. rst-class:: classref-property + +:ref:`float` **surround** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_surround(value) | -+-----------+---------------------+ -| *Getter* | get_surround() | -+-----------+---------------------+ +- |void| **set_surround**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_surround**\ (\ ) + +Widens sound stage through phase shifting in conjunction with :ref:`time_pullout_ms`. Just pans sound to the left channel if :ref:`time_pullout_ms` is 0. + +.. rst-class:: classref-item-separator ---- .. _class_AudioEffectStereoEnhance_property_time_pullout_ms: -- :ref:`float` **time_pullout_ms** +.. rst-class:: classref-property + +:ref:`float` **time_pullout_ms** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_time_pullout**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_time_pullout**\ (\ ) -+-----------+-------------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------------+ -| *Setter* | set_time_pullout(value) | -+-----------+-------------------------+ -| *Getter* | get_time_pullout() | -+-----------+-------------------------+ +Widens sound stage through phase shifting in conjunction with :ref:`surround`. Just delays the right channel if :ref:`surround` is 0. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiolistener2d.rst b/classes/class_audiolistener2d.rst new file mode 100644 index 00000000000..1d9d0da1d2c --- /dev/null +++ b/classes/class_audiolistener2d.rst @@ -0,0 +1,96 @@ +:github_url: hide + +.. meta:: + :keywords: sound + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioListener2D.xml. + +.. _class_AudioListener2D: + +AudioListener2D +=============== + +**Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` + +Overrides the location sounds are heard from. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Once added to the scene tree and enabled using :ref:`make_current()`, this node will override the location sounds are heard from. Only one **AudioListener2D** can be current. Using :ref:`make_current()` will disable the previous **AudioListener2D**. + +If there is no active **AudioListener2D** in the current :ref:`Viewport`, center of the screen will be used as a hearing point for the audio. **AudioListener2D** needs to be inside :ref:`SceneTree` to function. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------+--------------------------------------------------------------------------+ + | |void| | :ref:`clear_current`\ (\ ) | + +-------------------------+--------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_current`\ (\ ) |const| | + +-------------------------+--------------------------------------------------------------------------+ + | |void| | :ref:`make_current`\ (\ ) | + +-------------------------+--------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioListener2D_method_clear_current: + +.. rst-class:: classref-method + +|void| **clear_current**\ (\ ) :ref:`🔗` + +Disables the **AudioListener2D**. If it's not set as current, this method will have no effect. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioListener2D_method_is_current: + +.. rst-class:: classref-method + +:ref:`bool` **is_current**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if this **AudioListener2D** is currently active. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioListener2D_method_make_current: + +.. rst-class:: classref-method + +|void| **make_current**\ (\ ) :ref:`🔗` + +Makes the **AudioListener2D** active, setting it as the hearing point for the sounds. If there is already another active **AudioListener2D**, it will be disabled. + +This method will have no effect if the **AudioListener2D** is not added to :ref:`SceneTree`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiolistener3d.rst b/classes/class_audiolistener3d.rst new file mode 100644 index 00000000000..5bc0d1f88c0 --- /dev/null +++ b/classes/class_audiolistener3d.rst @@ -0,0 +1,183 @@ +:github_url: hide + +.. meta:: + :keywords: sound + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioListener3D.xml. + +.. _class_AudioListener3D: + +AudioListener3D +=============== + +**Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +Overrides the location sounds are heard from. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Once added to the scene tree and enabled using :ref:`make_current()`, this node will override the location sounds are heard from. This can be used to listen from a location different from the :ref:`Camera3D`. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +--------------------------------------------------------------+--------------------------------------------------------------------------+-------+ + | :ref:`DopplerTracking` | :ref:`doppler_tracking` | ``0`` | + +--------------------------------------------------------------+--------------------------------------------------------------------------+-------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+--------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_current`\ (\ ) | + +---------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`Transform3D` | :ref:`get_listener_transform`\ (\ ) |const| | + +---------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_current`\ (\ ) |const| | + +---------------------------------------+--------------------------------------------------------------------------------------------------+ + | |void| | :ref:`make_current`\ (\ ) | + +---------------------------------------+--------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AudioListener3D_DopplerTracking: + +.. rst-class:: classref-enumeration + +enum **DopplerTracking**: :ref:`🔗` + +.. _class_AudioListener3D_constant_DOPPLER_TRACKING_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_DISABLED** = ``0`` + +Disables `Doppler effect `__ simulation (default). + +.. _class_AudioListener3D_constant_DOPPLER_TRACKING_IDLE_STEP: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_IDLE_STEP** = ``1`` + +Simulate `Doppler effect `__ by tracking positions of objects that are changed in ``_process``. Changes in the relative velocity of this listener compared to those objects affect how audio is perceived (changing the audio's :ref:`AudioStreamPlayer3D.pitch_scale`). + +.. _class_AudioListener3D_constant_DOPPLER_TRACKING_PHYSICS_STEP: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_PHYSICS_STEP** = ``2`` + +Simulate `Doppler effect `__ by tracking positions of objects that are changed in ``_physics_process``. Changes in the relative velocity of this listener compared to those objects affect how audio is perceived (changing the audio's :ref:`AudioStreamPlayer3D.pitch_scale`). + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioListener3D_property_doppler_tracking: + +.. rst-class:: classref-property + +:ref:`DopplerTracking` **doppler_tracking** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_doppler_tracking**\ (\ value\: :ref:`DopplerTracking`\ ) +- :ref:`DopplerTracking` **get_doppler_tracking**\ (\ ) + +If not :ref:`DOPPLER_TRACKING_DISABLED`, this listener will simulate the `Doppler effect `__ for objects changed in particular ``_process`` methods. + +\ **Note:** The Doppler effect will only be heard on :ref:`AudioStreamPlayer3D`\ s if :ref:`AudioStreamPlayer3D.doppler_tracking` is not set to :ref:`AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioListener3D_method_clear_current: + +.. rst-class:: classref-method + +|void| **clear_current**\ (\ ) :ref:`🔗` + +Disables the listener to use the current camera's listener instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioListener3D_method_get_listener_transform: + +.. rst-class:: classref-method + +:ref:`Transform3D` **get_listener_transform**\ (\ ) |const| :ref:`🔗` + +Returns the listener's global orthonormalized :ref:`Transform3D`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioListener3D_method_is_current: + +.. rst-class:: classref-method + +:ref:`bool` **is_current**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the listener was made current using :ref:`make_current()`, ``false`` otherwise. + +\ **Note:** There may be more than one AudioListener3D marked as "current" in the scene tree, but only the one that was made current last will be used. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioListener3D_method_make_current: + +.. rst-class:: classref-method + +|void| **make_current**\ (\ ) :ref:`🔗` + +Enables the listener. This will override the current camera's listener. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiosample.rst b/classes/class_audiosample.rst new file mode 100644 index 00000000000..76b59731696 --- /dev/null +++ b/classes/class_audiosample.rst @@ -0,0 +1,34 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioSample.xml. + +.. _class_AudioSample: + +AudioSample +=========== + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` + +Base class for audio samples. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Base class for audio samples. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiosampleplayback.rst b/classes/class_audiosampleplayback.rst new file mode 100644 index 00000000000..ea722e18d2c --- /dev/null +++ b/classes/class_audiosampleplayback.rst @@ -0,0 +1,34 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioSamplePlayback.xml. + +.. _class_AudioSamplePlayback: + +AudioSamplePlayback +=================== + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` + +Meta class for playing back audio samples. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Meta class for playing back audio samples. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioserver.rst b/classes/class_audioserver.rst index 7d38be6488e..45d8a6efcb5 100644 --- a/classes/class_audioserver.rst +++ b/classes/class_audioserver.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioServer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioServer.xml. .. _class_AudioServer: @@ -13,513 +14,920 @@ AudioServer Server interface for low-level audio access. +.. rst-class:: classref-introduction-group + Description ----------- -``AudioServer`` is a low-level server interface for audio access. It is in charge of creating sample data (playable audio) as well as its playback via a voice interface. +**AudioServer** is a low-level server interface for audio access. It is in charge of creating sample data (playable audio) as well as its playback via a voice interface. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/audio/audio_buses` +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +- `Audio Device Changer Demo `__ + +- `Audio Microphone Record Demo `__ + +- `Audio Spectrum Visualizer Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`int` | :ref:`bus_count` | ``1`` | -+-----------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`String` | :ref:`device` | ``"Default"`` | -+-----------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`global_rate_scale` | ``1.0`` | -+-----------------------------+------------------------------------------------------------------------+---------------+ +.. table:: + :widths: auto + + +-----------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`int` | :ref:`bus_count` | ``1`` | + +-----------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`String` | :ref:`input_device` | ``"Default"`` | + +-----------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`String` | :ref:`output_device` | ``"Default"`` | + +-----------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`playback_speed_scale` | ``1.0`` | + +-----------------------------+------------------------------------------------------------------------------+---------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_bus` **(** :ref:`int` at_position=-1 **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_bus_effect` **(** :ref:`int` bus_idx, :ref:`AudioEffect` effect, :ref:`int` at_position=-1 **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`capture_get_device` **(** **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`capture_get_device_list` **(** **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`capture_set_device` **(** :ref:`String` name **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AudioBusLayout` | :ref:`generate_bus_layout` **(** **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_bus_channels` **(** :ref:`int` bus_idx **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AudioEffect` | :ref:`get_bus_effect` **(** :ref:`int` bus_idx, :ref:`int` effect_idx **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_bus_effect_count` **(** :ref:`int` bus_idx **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`AudioEffectInstance` | :ref:`get_bus_effect_instance` **(** :ref:`int` bus_idx, :ref:`int` effect_idx, :ref:`int` channel=0 **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_bus_index` **(** :ref:`StringName` bus_name **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_bus_name` **(** :ref:`int` bus_idx **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_bus_peak_volume_left_db` **(** :ref:`int` bus_idx, :ref:`int` channel **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_bus_peak_volume_right_db` **(** :ref:`int` bus_idx, :ref:`int` channel **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_bus_send` **(** :ref:`int` bus_idx **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_bus_volume_db` **(** :ref:`int` bus_idx **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_device_list` **(** **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_mix_rate` **(** **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_output_latency` **(** **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`SpeakerMode` | :ref:`get_speaker_mode` **(** **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_time_since_last_mix` **(** **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_time_to_next_mix` **(** **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_bus_bypassing_effects` **(** :ref:`int` bus_idx **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_bus_effect_enabled` **(** :ref:`int` bus_idx, :ref:`int` effect_idx **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_bus_mute` **(** :ref:`int` bus_idx **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_bus_solo` **(** :ref:`int` bus_idx **)** const | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`lock` **(** **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`move_bus` **(** :ref:`int` index, :ref:`int` to_index **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_bus` **(** :ref:`int` index **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_bus_effect` **(** :ref:`int` bus_idx, :ref:`int` effect_idx **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bus_bypass_effects` **(** :ref:`int` bus_idx, :ref:`bool` enable **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bus_effect_enabled` **(** :ref:`int` bus_idx, :ref:`int` effect_idx, :ref:`bool` enabled **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bus_layout` **(** :ref:`AudioBusLayout` bus_layout **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bus_mute` **(** :ref:`int` bus_idx, :ref:`bool` enable **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bus_name` **(** :ref:`int` bus_idx, :ref:`String` name **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bus_send` **(** :ref:`int` bus_idx, :ref:`StringName` send **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bus_solo` **(** :ref:`int` bus_idx, :ref:`bool` enable **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bus_volume_db` **(** :ref:`int` bus_idx, :ref:`float` volume_db **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`swap_bus_effects` **(** :ref:`int` bus_idx, :ref:`int` effect_idx, :ref:`int` by_effect_idx **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`unlock` **(** **)** | -+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_bus`\ (\ at_position\: :ref:`int` = -1\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_bus_effect`\ (\ bus_idx\: :ref:`int`, effect\: :ref:`AudioEffect`, at_position\: :ref:`int` = -1\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioBusLayout` | :ref:`generate_bus_layout`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_bus_channels`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioEffect` | :ref:`get_bus_effect`\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_bus_effect_count`\ (\ bus_idx\: :ref:`int`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioEffectInstance` | :ref:`get_bus_effect_instance`\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, channel\: :ref:`int` = 0\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_bus_index`\ (\ bus_name\: :ref:`StringName`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_bus_name`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_bus_peak_volume_left_db`\ (\ bus_idx\: :ref:`int`, channel\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_bus_peak_volume_right_db`\ (\ bus_idx\: :ref:`int`, channel\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_bus_send`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_bus_volume_db`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_bus_volume_linear`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_driver_name`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_input_device_list`\ (\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_input_mix_rate`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_mix_rate`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_output_device_list`\ (\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_output_latency`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`SpeakerMode` | :ref:`get_speaker_mode`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_time_since_last_mix`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_time_to_next_mix`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_bus_bypassing_effects`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_bus_effect_enabled`\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_bus_mute`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_bus_solo`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_stream_registered_as_sample`\ (\ stream\: :ref:`AudioStream`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`lock`\ (\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`move_bus`\ (\ index\: :ref:`int`, to_index\: :ref:`int`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`register_stream_as_sample`\ (\ stream\: :ref:`AudioStream`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_bus`\ (\ index\: :ref:`int`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_bus_effect`\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_bypass_effects`\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_effect_enabled`\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_layout`\ (\ bus_layout\: :ref:`AudioBusLayout`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_mute`\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_name`\ (\ bus_idx\: :ref:`int`, name\: :ref:`String`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_send`\ (\ bus_idx\: :ref:`int`, send\: :ref:`StringName`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_solo`\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_volume_db`\ (\ bus_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_volume_linear`\ (\ bus_idx\: :ref:`int`, volume_linear\: :ref:`float`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_enable_tagging_used_audio_streams`\ (\ enable\: :ref:`bool`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`swap_bus_effects`\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, by_effect_idx\: :ref:`int`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`unlock`\ (\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_AudioServer_signal_bus_layout_changed: -- **bus_layout_changed** **(** **)** +.. rst-class:: classref-signal + +**bus_layout_changed**\ (\ ) :ref:`🔗` + +Emitted when an audio bus is added, deleted, or moved. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_signal_bus_renamed: -Emitted when the :ref:`AudioBusLayout` changes. +.. rst-class:: classref-signal + +**bus_renamed**\ (\ bus_index\: :ref:`int`, old_name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when the audio bus at ``bus_index`` is renamed from ``old_name`` to ``new_name``. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_AudioServer_SpeakerMode: +.. rst-class:: classref-enumeration + +enum **SpeakerMode**: :ref:`🔗` + .. _class_AudioServer_constant_SPEAKER_MODE_STEREO: +.. rst-class:: classref-enumeration-constant + +:ref:`SpeakerMode` **SPEAKER_MODE_STEREO** = ``0`` + +Two or fewer speakers were detected. + .. _class_AudioServer_constant_SPEAKER_SURROUND_31: +.. rst-class:: classref-enumeration-constant + +:ref:`SpeakerMode` **SPEAKER_SURROUND_31** = ``1`` + +A 3.1 channel surround setup was detected. + .. _class_AudioServer_constant_SPEAKER_SURROUND_51: +.. rst-class:: classref-enumeration-constant + +:ref:`SpeakerMode` **SPEAKER_SURROUND_51** = ``2`` + +A 5.1 channel surround setup was detected. + .. _class_AudioServer_constant_SPEAKER_SURROUND_71: -enum **SpeakerMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`SpeakerMode` **SPEAKER_SURROUND_71** = ``3`` + +A 7.1 channel surround setup was detected. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioServer_PlaybackType: + +.. rst-class:: classref-enumeration + +enum **PlaybackType**: :ref:`🔗` + +.. _class_AudioServer_constant_PLAYBACK_TYPE_DEFAULT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackType` **PLAYBACK_TYPE_DEFAULT** = ``0`` + +**Experimental:** This constant may be changed or removed in future versions. + +The playback will be considered of the type declared at :ref:`ProjectSettings.audio/general/default_playback_type`. + +.. _class_AudioServer_constant_PLAYBACK_TYPE_STREAM: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackType` **PLAYBACK_TYPE_STREAM** = ``1`` + +**Experimental:** This constant may be changed or removed in future versions. + +Force the playback to be considered as a stream. + +.. _class_AudioServer_constant_PLAYBACK_TYPE_SAMPLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackType` **PLAYBACK_TYPE_SAMPLE** = ``2`` + +**Experimental:** This constant may be changed or removed in future versions. + +Force the playback to be considered as a sample. This can provide lower latency and more stable playback (with less risk of audio crackling), at the cost of having less flexibility. + +\ **Note:** Only currently supported on the web platform. + +\ **Note:** :ref:`AudioEffect`\ s are not supported when playback is considered as a sample. -- **SPEAKER_MODE_STEREO** = **0** --- Two or fewer speakers were detected. +.. _class_AudioServer_constant_PLAYBACK_TYPE_MAX: -- **SPEAKER_SURROUND_31** = **1** --- A 3.1 channel surround setup was detected. +.. rst-class:: classref-enumeration-constant -- **SPEAKER_SURROUND_51** = **2** --- A 5.1 channel surround setup was detected. +:ref:`PlaybackType` **PLAYBACK_TYPE_MAX** = ``3`` -- **SPEAKER_SURROUND_71** = **3** --- A 7.1 channel surround setup was detected. +**Experimental:** This constant may be changed or removed in future versions. + +Represents the size of the :ref:`PlaybackType` enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioServer_property_bus_count: -- :ref:`int` **bus_count** +.. rst-class:: classref-property + +:ref:`int` **bus_count** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``1`` | -+-----------+----------------------+ -| *Setter* | set_bus_count(value) | -+-----------+----------------------+ -| *Getter* | get_bus_count() | -+-----------+----------------------+ +- |void| **set_bus_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_bus_count**\ (\ ) Number of available audio buses. +.. rst-class:: classref-item-separator + ---- -.. _class_AudioServer_property_device: +.. _class_AudioServer_property_input_device: -- :ref:`String` **device** +.. rst-class:: classref-property -+-----------+-------------------+ -| *Default* | ``"Default"`` | -+-----------+-------------------+ -| *Setter* | set_device(value) | -+-----------+-------------------+ -| *Getter* | get_device() | -+-----------+-------------------+ +:ref:`String` **input_device** = ``"Default"`` :ref:`🔗` -Name of the current device for audio output (see :ref:`get_device_list`). +.. rst-class:: classref-property-setget ----- +- |void| **set_input_device**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_input_device**\ (\ ) -.. _class_AudioServer_property_global_rate_scale: +Name of the current device for audio input (see :ref:`get_input_device_list()`). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value ``"Default"`` will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to ``"Default"``. -- :ref:`float` **global_rate_scale** +\ **Note:** :ref:`ProjectSettings.audio/driver/enable_input` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. -+-----------+------------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------------+ -| *Setter* | set_global_rate_scale(value) | -+-----------+------------------------------+ -| *Getter* | get_global_rate_scale() | -+-----------+------------------------------+ +.. rst-class:: classref-item-separator -Scales the rate at which audio is played (i.e. setting it to ``0.5`` will make the audio be played twice as fast). +---- -Method Descriptions -------------------- +.. _class_AudioServer_property_output_device: -.. _class_AudioServer_method_add_bus: +.. rst-class:: classref-property -- void **add_bus** **(** :ref:`int` at_position=-1 **)** +:ref:`String` **output_device** = ``"Default"`` :ref:`🔗` -Adds a bus at ``at_position``. +.. rst-class:: classref-property-setget + +- |void| **set_output_device**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_output_device**\ (\ ) + +Name of the current device for audio output (see :ref:`get_output_device_list()`). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value ``"Default"`` will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to ``"Default"``. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioServer_method_add_bus_effect: +.. _class_AudioServer_property_playback_speed_scale: -- void **add_bus_effect** **(** :ref:`int` bus_idx, :ref:`AudioEffect` effect, :ref:`int` at_position=-1 **)** +.. rst-class:: classref-property -Adds an :ref:`AudioEffect` effect to the bus ``bus_idx`` at ``at_position``. +:ref:`float` **playback_speed_scale** = ``1.0`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_AudioServer_method_capture_get_device: +- |void| **set_playback_speed_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_playback_speed_scale**\ (\ ) -- :ref:`String` **capture_get_device** **(** **)** +Scales the rate at which audio is played (i.e. setting it to ``0.5`` will make the audio be played at half its speed). See also :ref:`Engine.time_scale` to affect the general simulation speed, which is independent from :ref:`playback_speed_scale`. -Name of the current device for audio input (see :ref:`capture_get_device_list`). +.. rst-class:: classref-section-separator ---- -.. _class_AudioServer_method_capture_get_device_list: +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- -- :ref:`Array` **capture_get_device_list** **(** **)** +.. _class_AudioServer_method_add_bus: -Returns the names of all audio input devices detected on the system. +.. rst-class:: classref-method + +|void| **add_bus**\ (\ at_position\: :ref:`int` = -1\ ) :ref:`🔗` + +Adds a bus at ``at_position``. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioServer_method_capture_set_device: +.. _class_AudioServer_method_add_bus_effect: + +.. rst-class:: classref-method -- void **capture_set_device** **(** :ref:`String` name **)** +|void| **add_bus_effect**\ (\ bus_idx\: :ref:`int`, effect\: :ref:`AudioEffect`, at_position\: :ref:`int` = -1\ ) :ref:`🔗` -Sets which audio input device is used for audio capture. +Adds an :ref:`AudioEffect` effect to the bus ``bus_idx`` at ``at_position``. + +.. rst-class:: classref-item-separator ---- .. _class_AudioServer_method_generate_bus_layout: -- :ref:`AudioBusLayout` **generate_bus_layout** **(** **)** const +.. rst-class:: classref-method + +:ref:`AudioBusLayout` **generate_bus_layout**\ (\ ) |const| :ref:`🔗` Generates an :ref:`AudioBusLayout` using the available buses and effects. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_bus_channels: -- :ref:`int` **get_bus_channels** **(** :ref:`int` bus_idx **)** const +.. rst-class:: classref-method -Returns the amount of channels of the bus at index ``bus_idx``. +:ref:`int` **get_bus_channels**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the number of channels of the bus at index ``bus_idx``. + +.. rst-class:: classref-item-separator ---- .. _class_AudioServer_method_get_bus_effect: -- :ref:`AudioEffect` **get_bus_effect** **(** :ref:`int` bus_idx, :ref:`int` effect_idx **)** +.. rst-class:: classref-method + +:ref:`AudioEffect` **get_bus_effect**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) :ref:`🔗` Returns the :ref:`AudioEffect` at position ``effect_idx`` in bus ``bus_idx``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_bus_effect_count: -- :ref:`int` **get_bus_effect_count** **(** :ref:`int` bus_idx **)** +.. rst-class:: classref-method + +:ref:`int` **get_bus_effect_count**\ (\ bus_idx\: :ref:`int`\ ) :ref:`🔗` Returns the number of effects on the bus at ``bus_idx``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_bus_effect_instance: -- :ref:`AudioEffectInstance` **get_bus_effect_instance** **(** :ref:`int` bus_idx, :ref:`int` effect_idx, :ref:`int` channel=0 **)** +.. rst-class:: classref-method + +:ref:`AudioEffectInstance` **get_bus_effect_instance**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, channel\: :ref:`int` = 0\ ) :ref:`🔗` Returns the :ref:`AudioEffectInstance` assigned to the given bus and effect indices (and optionally channel). +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_bus_index: -- :ref:`int` **get_bus_index** **(** :ref:`StringName` bus_name **)** const +.. rst-class:: classref-method + +:ref:`int` **get_bus_index**\ (\ bus_name\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns the index of the bus with the name ``bus_name``. +Returns the index of the bus with the name ``bus_name``. Returns ``-1`` if no bus with the specified name exist. + +.. rst-class:: classref-item-separator ---- .. _class_AudioServer_method_get_bus_name: -- :ref:`String` **get_bus_name** **(** :ref:`int` bus_idx **)** const +.. rst-class:: classref-method + +:ref:`String` **get_bus_name**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the name of the bus with the index ``bus_idx``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_bus_peak_volume_left_db: -- :ref:`float` **get_bus_peak_volume_left_db** **(** :ref:`int` bus_idx, :ref:`int` channel **)** const +.. rst-class:: classref-method + +:ref:`float` **get_bus_peak_volume_left_db**\ (\ bus_idx\: :ref:`int`, channel\: :ref:`int`\ ) |const| :ref:`🔗` Returns the peak volume of the left speaker at bus index ``bus_idx`` and channel index ``channel``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_bus_peak_volume_right_db: -- :ref:`float` **get_bus_peak_volume_right_db** **(** :ref:`int` bus_idx, :ref:`int` channel **)** const +.. rst-class:: classref-method + +:ref:`float` **get_bus_peak_volume_right_db**\ (\ bus_idx\: :ref:`int`, channel\: :ref:`int`\ ) |const| :ref:`🔗` Returns the peak volume of the right speaker at bus index ``bus_idx`` and channel index ``channel``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_bus_send: -- :ref:`StringName` **get_bus_send** **(** :ref:`int` bus_idx **)** const +.. rst-class:: classref-method + +:ref:`StringName` **get_bus_send**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the name of the bus that the bus at index ``bus_idx`` sends to. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_bus_volume_db: -- :ref:`float` **get_bus_volume_db** **(** :ref:`int` bus_idx **)** const +.. rst-class:: classref-method + +:ref:`float` **get_bus_volume_db**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the volume of the bus at index ``bus_idx`` in dB. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_get_bus_volume_linear: + +.. rst-class:: classref-method + +:ref:`float` **get_bus_volume_linear**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the volume of the bus at index ``bus_idx`` as a linear value. + +\ **Note:** The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on the result of :ref:`get_bus_volume_db()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_get_driver_name: + +.. rst-class:: classref-method + +:ref:`String` **get_driver_name**\ (\ ) |const| :ref:`🔗` + +Returns the name of the current audio driver. The default usually depends on the operating system, but may be overridden via the ``--audio-driver`` :doc:`command line argument <../tutorials/editor/command_line_tutorial>`. ``--headless`` also automatically sets the audio driver to ``Dummy``. See also :ref:`ProjectSettings.audio/driver/driver`. + +.. rst-class:: classref-item-separator + ---- -.. _class_AudioServer_method_get_device_list: +.. _class_AudioServer_method_get_input_device_list: -- :ref:`Array` **get_device_list** **(** **)** +.. rst-class:: classref-method -Returns the names of all audio devices detected on the system. +:ref:`PackedStringArray` **get_input_device_list**\ (\ ) :ref:`🔗` + +Returns the names of all audio input devices detected on the system. + +\ **Note:** :ref:`ProjectSettings.audio/driver/enable_input` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_get_input_mix_rate: + +.. rst-class:: classref-method + +:ref:`float` **get_input_mix_rate**\ (\ ) |const| :ref:`🔗` + +Returns the sample rate at the input of the **AudioServer**. + +.. rst-class:: classref-item-separator ---- .. _class_AudioServer_method_get_mix_rate: -- :ref:`float` **get_mix_rate** **(** **)** const +.. rst-class:: classref-method + +:ref:`float` **get_mix_rate**\ (\ ) |const| :ref:`🔗` + +Returns the sample rate at the output of the **AudioServer**. + +.. rst-class:: classref-item-separator -Returns the sample rate at the output of the ``AudioServer``. +---- + +.. _class_AudioServer_method_get_output_device_list: + +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_output_device_list**\ (\ ) :ref:`🔗` + +Returns the names of all audio output devices detected on the system. + +.. rst-class:: classref-item-separator ---- .. _class_AudioServer_method_get_output_latency: -- :ref:`float` **get_output_latency** **(** **)** const +.. rst-class:: classref-method + +:ref:`float` **get_output_latency**\ (\ ) |const| :ref:`🔗` -Returns the audio driver's output latency. +Returns the audio driver's effective output latency. This is based on :ref:`ProjectSettings.audio/driver/output_latency`, but the exact returned value will differ depending on the operating system and audio driver. + +\ **Note:** This can be expensive; it is not recommended to call :ref:`get_output_latency()` every frame. + +.. rst-class:: classref-item-separator ---- .. _class_AudioServer_method_get_speaker_mode: -- :ref:`SpeakerMode` **get_speaker_mode** **(** **)** const +.. rst-class:: classref-method + +:ref:`SpeakerMode` **get_speaker_mode**\ (\ ) |const| :ref:`🔗` Returns the speaker configuration. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_time_since_last_mix: -- :ref:`float` **get_time_since_last_mix** **(** **)** const +.. rst-class:: classref-method + +:ref:`float` **get_time_since_last_mix**\ (\ ) |const| :ref:`🔗` Returns the relative time since the last mix occurred. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_get_time_to_next_mix: -- :ref:`float` **get_time_to_next_mix** **(** **)** const +.. rst-class:: classref-method + +:ref:`float` **get_time_to_next_mix**\ (\ ) |const| :ref:`🔗` Returns the relative time until the next mix occurs. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_is_bus_bypassing_effects: -- :ref:`bool` **is_bus_bypassing_effects** **(** :ref:`int` bus_idx **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_bus_bypassing_effects**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is bypassing effects. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_is_bus_effect_enabled: -- :ref:`bool` **is_bus_effect_enabled** **(** :ref:`int` bus_idx, :ref:`int` effect_idx **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_bus_effect_enabled**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the effect at index ``effect_idx`` on the bus at index ``bus_idx`` is enabled. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_is_bus_mute: -- :ref:`bool` **is_bus_mute** **(** :ref:`int` bus_idx **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_bus_mute**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is muted. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_is_bus_solo: -- :ref:`bool` **is_bus_solo** **(** :ref:`int` bus_idx **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_bus_solo**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is in solo mode. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_is_stream_registered_as_sample: + +.. rst-class:: classref-method + +:ref:`bool` **is_stream_registered_as_sample**\ (\ stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +If ``true``, the stream is registered as a sample. The engine will not have to register it before playing the sample. + +If ``false``, the stream will have to be registered before playing it. To prevent lag spikes, register the stream as sample with :ref:`register_stream_as_sample()`. + +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_lock: -- void **lock** **(** **)** +.. rst-class:: classref-method + +|void| **lock**\ (\ ) :ref:`🔗` Locks the audio driver's main loop. -**Note:** Remember to unlock it afterwards. +\ **Note:** Remember to unlock it afterwards. + +.. rst-class:: classref-item-separator ---- .. _class_AudioServer_method_move_bus: -- void **move_bus** **(** :ref:`int` index, :ref:`int` to_index **)** +.. rst-class:: classref-method + +|void| **move_bus**\ (\ index\: :ref:`int`, to_index\: :ref:`int`\ ) :ref:`🔗` Moves the bus from index ``index`` to index ``to_index``. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_register_stream_as_sample: + +.. rst-class:: classref-method + +|void| **register_stream_as_sample**\ (\ stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Forces the registration of a stream as a sample. + +\ **Note:** Lag spikes may occur when calling this method, especially on single-threaded builds. It is suggested to call this method while loading assets, where the lag spike could be masked, instead of registering the sample right before it needs to be played. + +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_remove_bus: -- void **remove_bus** **(** :ref:`int` index **)** +.. rst-class:: classref-method + +|void| **remove_bus**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Removes the bus at index ``index``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_remove_bus_effect: -- void **remove_bus_effect** **(** :ref:`int` bus_idx, :ref:`int` effect_idx **)** +.. rst-class:: classref-method + +|void| **remove_bus_effect**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) :ref:`🔗` Removes the effect at index ``effect_idx`` from the bus at index ``bus_idx``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_set_bus_bypass_effects: -- void **set_bus_bypass_effects** **(** :ref:`int` bus_idx, :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_bus_bypass_effects**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is bypassing effects. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_set_bus_effect_enabled: -- void **set_bus_effect_enabled** **(** :ref:`int` bus_idx, :ref:`int` effect_idx, :ref:`bool` enabled **)** +.. rst-class:: classref-method + +|void| **set_bus_effect_enabled**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the effect at index ``effect_idx`` on the bus at index ``bus_idx`` is enabled. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_set_bus_layout: -- void **set_bus_layout** **(** :ref:`AudioBusLayout` bus_layout **)** +.. rst-class:: classref-method + +|void| **set_bus_layout**\ (\ bus_layout\: :ref:`AudioBusLayout`\ ) :ref:`🔗` Overwrites the currently used :ref:`AudioBusLayout`. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_set_bus_mute: -- void **set_bus_mute** **(** :ref:`int` bus_idx, :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_bus_mute**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is muted. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_set_bus_name: -- void **set_bus_name** **(** :ref:`int` bus_idx, :ref:`String` name **)** +.. rst-class:: classref-method + +|void| **set_bus_name**\ (\ bus_idx\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` Sets the name of the bus at index ``bus_idx`` to ``name``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_set_bus_send: -- void **set_bus_send** **(** :ref:`int` bus_idx, :ref:`StringName` send **)** +.. rst-class:: classref-method + +|void| **set_bus_send**\ (\ bus_idx\: :ref:`int`, send\: :ref:`StringName`\ ) :ref:`🔗` Connects the output of the bus at ``bus_idx`` to the bus named ``send``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_set_bus_solo: -- void **set_bus_solo** **(** :ref:`int` bus_idx, :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_bus_solo**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is in solo mode. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_set_bus_volume_db: -- void **set_bus_volume_db** **(** :ref:`int` bus_idx, :ref:`float` volume_db **)** +.. rst-class:: classref-method + +|void| **set_bus_volume_db**\ (\ bus_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) :ref:`🔗` + +Sets the volume in decibels of the bus at index ``bus_idx`` to ``volume_db``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_set_bus_volume_linear: + +.. rst-class:: classref-method -Sets the volume of the bus at index ``bus_idx`` to ``volume_db``. +|void| **set_bus_volume_linear**\ (\ bus_idx\: :ref:`int`, volume_linear\: :ref:`float`\ ) :ref:`🔗` + +Sets the volume as a linear value of the bus at index ``bus_idx`` to ``volume_linear``. + +\ **Note:** Using this method is equivalent to calling :ref:`set_bus_volume_db()` with the result of :ref:`@GlobalScope.linear_to_db()` on a value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_set_enable_tagging_used_audio_streams: + +.. rst-class:: classref-method + +|void| **set_enable_tagging_used_audio_streams**\ (\ enable\: :ref:`bool`\ ) :ref:`🔗` + +If set to ``true``, all instances of :ref:`AudioStreamPlayback` will call :ref:`AudioStreamPlayback._tag_used_streams()` every mix step. + +\ **Note:** This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews. + +.. rst-class:: classref-item-separator ---- .. _class_AudioServer_method_swap_bus_effects: -- void **swap_bus_effects** **(** :ref:`int` bus_idx, :ref:`int` effect_idx, :ref:`int` by_effect_idx **)** +.. rst-class:: classref-method + +|void| **swap_bus_effects**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, by_effect_idx\: :ref:`int`\ ) :ref:`🔗` Swaps the position of two effects in bus ``bus_idx``. +.. rst-class:: classref-item-separator + ---- .. _class_AudioServer_method_unlock: -- void **unlock** **(** **)** +.. rst-class:: classref-method + +|void| **unlock**\ (\ ) :ref:`🔗` Unlocks the audio driver's main loop. (After locking it, you should always unlock it.) +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostream.rst b/classes/class_audiostream.rst index e4dab81c113..584198bdd4c 100644 --- a/classes/class_audiostream.rst +++ b/classes/class_audiostream.rst @@ -1,43 +1,313 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStream.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStream.xml. .. _class_AudioStream: AudioStream =========== -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AudioStreamGenerator`, :ref:`AudioStreamMicrophone`, :ref:`AudioStreamOGGVorbis`, :ref:`AudioStreamRandomPitch`, :ref:`AudioStreamSample` +**Inherited By:** :ref:`AudioStreamGenerator`, :ref:`AudioStreamInteractive`, :ref:`AudioStreamMicrophone`, :ref:`AudioStreamMP3`, :ref:`AudioStreamOggVorbis`, :ref:`AudioStreamPlaylist`, :ref:`AudioStreamPolyphonic`, :ref:`AudioStreamRandomizer`, :ref:`AudioStreamSynchronized`, :ref:`AudioStreamWAV` Base class for audio streams. +.. rst-class:: classref-introduction-group + Description ----------- -Base class for audio streams. Audio streams are used for sound effects and music playback, and support WAV (via :ref:`AudioStreamSample`) and OGG (via :ref:`AudioStreamOGGVorbis`) file formats. +Base class for audio streams. Audio streams are used for sound effects and music playback, and support WAV (via :ref:`AudioStreamWAV`) and Ogg (via :ref:`AudioStreamOggVorbis`) file formats. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/audio/audio_streams` +- :doc:`Audio streams <../tutorials/audio/audio_streams>` + +- `Audio Generator Demo `__ + +- `Audio Microphone Record Demo `__ + +- `Audio Spectrum Visualizer Demo `__ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------+--------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_length` **(** **)** const | -+---------------------------+--------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_get_bar_beats`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_get_beat_count`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_get_bpm`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_get_length`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`_get_parameter_list`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`_get_stream_name`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`_get_tags`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_has_loop`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamPlayback` | :ref:`_instantiate_playback`\ (\ ) |virtual| |required| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_is_monophonic`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`can_be_sampled`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioSample` | :ref:`generate_sample`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_length`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamPlayback` | :ref:`instantiate_playback`\ (\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_meta_stream`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_monophonic`\ (\ ) |const| | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_AudioStream_signal_parameter_list_changed: + +.. rst-class:: classref-signal + +**parameter_list_changed**\ (\ ) :ref:`🔗` + +Signal to be emitted to notify when the parameter list changed. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- +.. _class_AudioStream_private_method__get_bar_beats: + +.. rst-class:: classref-method + +:ref:`int` **_get_bar_beats**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to return the bar beats of this stream. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__get_beat_count: + +.. rst-class:: classref-method + +:ref:`int` **_get_beat_count**\ (\ ) |virtual| |const| :ref:`🔗` + +Overridable method. Should return the total number of beats of this audio stream. Used by the engine to determine the position of every beat. + +Ideally, the returned value should be based off the stream's sample rate (:ref:`AudioStreamWAV.mix_rate`, for example). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__get_bpm: + +.. rst-class:: classref-method + +:ref:`float` **_get_bpm**\ (\ ) |virtual| |const| :ref:`🔗` + +Overridable method. Should return the tempo of this audio stream, in beats per minute (BPM). Used by the engine to determine the position of every beat. + +Ideally, the returned value should be based off the stream's sample rate (:ref:`AudioStreamWAV.mix_rate`, for example). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__get_length: + +.. rst-class:: classref-method + +:ref:`float` **_get_length**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to customize the returned value of :ref:`get_length()`. Should return the length of this audio stream, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__get_parameter_list: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Dictionary`\] **_get_parameter_list**\ (\ ) |virtual| |const| :ref:`🔗` + +Return the controllable parameters of this stream. This array contains dictionaries with a property info description format (see :ref:`Object.get_property_list()`). Additionally, the default value for this parameter must be added tho each dictionary in "default_value" field. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__get_stream_name: + +.. rst-class:: classref-method + +:ref:`String` **_get_stream_name**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to customize the name assigned to this audio stream. Unused by the engine. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__get_tags: + +.. rst-class:: classref-method + +:ref:`Dictionary` **_get_tags**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to customize the tags for this audio stream. Should return a :ref:`Dictionary` of strings with the tag as the key and its content as the value. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__has_loop: + +.. rst-class:: classref-method + +:ref:`bool` **_has_loop**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to return ``true`` if this stream has a loop. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__instantiate_playback: + +.. rst-class:: classref-method + +:ref:`AudioStreamPlayback` **_instantiate_playback**\ (\ ) |virtual| |required| |const| :ref:`🔗` + +Override this method to customize the returned value of :ref:`instantiate_playback()`. Should return a new :ref:`AudioStreamPlayback` created when the stream is played (such as by an :ref:`AudioStreamPlayer`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__is_monophonic: + +.. rst-class:: classref-method + +:ref:`bool` **_is_monophonic**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to customize the returned value of :ref:`is_monophonic()`. Should return ``true`` if this audio stream only supports one channel. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_method_can_be_sampled: + +.. rst-class:: classref-method + +:ref:`bool` **can_be_sampled**\ (\ ) |const| :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Returns if the current **AudioStream** can be used as a sample. Only static streams can be sampled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_method_generate_sample: + +.. rst-class:: classref-method + +:ref:`AudioSample` **generate_sample**\ (\ ) |const| :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Generates an :ref:`AudioSample` based on the current stream. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioStream_method_get_length: -- :ref:`float` **get_length** **(** **)** const +.. rst-class:: classref-method + +:ref:`float` **get_length**\ (\ ) |const| :ref:`🔗` + +Returns the length of the audio stream in seconds. If this stream is an :ref:`AudioStreamRandomizer`, returns the length of the last played stream. If this stream has an indefinite length (such as for :ref:`AudioStreamGenerator` and :ref:`AudioStreamMicrophone`), returns ``0.0``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_method_instantiate_playback: + +.. rst-class:: classref-method + +:ref:`AudioStreamPlayback` **instantiate_playback**\ (\ ) :ref:`🔗` + +Returns a newly created :ref:`AudioStreamPlayback` intended to play this audio stream. Useful for when you want to extend :ref:`_instantiate_playback()` but call :ref:`instantiate_playback()` from an internally held AudioStream subresource. An example of this can be found in the source code for ``AudioStreamRandomPitch::instantiate_playback``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_method_is_meta_stream: + +.. rst-class:: classref-method + +:ref:`bool` **is_meta_stream**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the stream is a collection of other streams, ``false`` otherwise. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_method_is_monophonic: + +.. rst-class:: classref-method + +:ref:`bool` **is_monophonic**\ (\ ) |const| :ref:`🔗` -Returns the length of the audio stream in seconds. +Returns ``true`` if this audio stream only supports one channel (*monophony*), or ``false`` if the audio stream supports two or more channels (*polyphony*). +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamgenerator.rst b/classes/class_audiostreamgenerator.rst index f6da08a01e9..6cd9e6adc22 100644 --- a/classes/class_audiostreamgenerator.rst +++ b/classes/class_audiostreamgenerator.rst @@ -1,58 +1,231 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamGenerator.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamGenerator.xml. .. _class_AudioStreamGenerator: AudioStreamGenerator ==================== -**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` +An audio stream with utilities for procedural sound generation. +.. rst-class:: classref-introduction-group + +Description +----------- + +**AudioStreamGenerator** is a type of audio stream that does not play back sounds on its own; instead, it expects a script to generate audio data for it. See also :ref:`AudioStreamGeneratorPlayback`. + +Here's a sample on how to use it to generate a sine wave: + + +.. tabs:: + + .. code-tab:: gdscript + + var playback # Will hold the AudioStreamGeneratorPlayback. + @onready var sample_hz = $AudioStreamPlayer.stream.mix_rate + var pulse_hz = 440.0 # The frequency of the sound wave. + var phase = 0.0 + + func _ready(): + $AudioStreamPlayer.play() + playback = $AudioStreamPlayer.get_stream_playback() + fill_buffer() + + func fill_buffer(): + var increment = pulse_hz / sample_hz + var frames_available = playback.get_frames_available() + + for i in range(frames_available): + playback.push_frame(Vector2.ONE * sin(phase * TAU)) + phase = fmod(phase + increment, 1.0) + + .. code-tab:: csharp + + [Export] public AudioStreamPlayer Player { get; set; } + + private AudioStreamGeneratorPlayback _playback; // Will hold the AudioStreamGeneratorPlayback. + private float _sampleHz; + private float _pulseHz = 440.0f; // The frequency of the sound wave. + private double phase = 0.0; + + public override void _Ready() + { + if (Player.Stream is AudioStreamGenerator generator) // Type as a generator to access MixRate. + { + _sampleHz = generator.MixRate; + Player.Play(); + _playback = (AudioStreamGeneratorPlayback)Player.GetStreamPlayback(); + FillBuffer(); + } + } + + public void FillBuffer() + { + float increment = _pulseHz / _sampleHz; + int framesAvailable = _playback.GetFramesAvailable(); + + for (int i = 0; i < framesAvailable; i++) + { + _playback.PushFrame(Vector2.One * (float)Mathf.Sin(phase * Mathf.Tau)); + phase = Mathf.PosMod(phase + increment, 1.0); + } + } + + + +In the example above, the "AudioStreamPlayer" node must use an **AudioStreamGenerator** as its stream. The ``fill_buffer`` function provides audio data for approximating a sine wave. + +See also :ref:`AudioEffectSpectrumAnalyzer` for performing real-time audio spectrum analysis. + +\ **Note:** Due to performance constraints, this class is best used from C# or from a compiled language via GDExtension. If you still want to use this class from GDScript, consider using a lower :ref:`mix_rate` such as 11,025 Hz or 22,050 Hz. + +.. rst-class:: classref-introduction-group Tutorials --------- -- `https://github.com/godotengine/godot-demo-projects/tree/master/audio/generator `_ +- `Audio Generator Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+-------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`buffer_length` | ``0.5`` | -+---------------------------+-------------------------------------------------------------------------+-------------+ -| :ref:`float` | :ref:`mix_rate` | ``44100.0`` | -+---------------------------+-------------------------------------------------------------------------+-------------+ +.. table:: + :widths: auto + + +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`buffer_length` | ``0.5`` | + +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`mix_rate` | ``44100.0`` | + +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+ + | :ref:`AudioStreamGeneratorMixRate` | :ref:`mix_rate_mode` | ``2`` | + +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AudioStreamGenerator_AudioStreamGeneratorMixRate: + +.. rst-class:: classref-enumeration + +enum **AudioStreamGeneratorMixRate**: :ref:`🔗` + +.. _class_AudioStreamGenerator_constant_MIX_RATE_OUTPUT: + +.. rst-class:: classref-enumeration-constant + +:ref:`AudioStreamGeneratorMixRate` **MIX_RATE_OUTPUT** = ``0`` + +Current :ref:`AudioServer` output mixing rate. + +.. _class_AudioStreamGenerator_constant_MIX_RATE_INPUT: + +.. rst-class:: classref-enumeration-constant + +:ref:`AudioStreamGeneratorMixRate` **MIX_RATE_INPUT** = ``1`` + +Current :ref:`AudioServer` input mixing rate. + +.. _class_AudioStreamGenerator_constant_MIX_RATE_CUSTOM: + +.. rst-class:: classref-enumeration-constant + +:ref:`AudioStreamGeneratorMixRate` **MIX_RATE_CUSTOM** = ``2`` + +Custom mixing rate, specified by :ref:`mix_rate`. + +.. _class_AudioStreamGenerator_constant_MIX_RATE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`AudioStreamGeneratorMixRate` **MIX_RATE_MAX** = ``3`` + +Maximum value for the mixing rate mode enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioStreamGenerator_property_buffer_length: -- :ref:`float` **buffer_length** +.. rst-class:: classref-property + +:ref:`float` **buffer_length** = ``0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+--------------------------+ -| *Default* | ``0.5`` | -+-----------+--------------------------+ -| *Setter* | set_buffer_length(value) | -+-----------+--------------------------+ -| *Getter* | get_buffer_length() | -+-----------+--------------------------+ +- |void| **set_buffer_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_buffer_length**\ (\ ) + +The length of the buffer to generate (in seconds). Lower values result in less latency, but require the script to generate audio data faster, resulting in increased CPU usage and more risk for audio cracking if the CPU can't keep up. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamGenerator_property_mix_rate: -- :ref:`float` **mix_rate** +.. rst-class:: classref-property + +:ref:`float` **mix_rate** = ``44100.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mix_rate**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_mix_rate**\ (\ ) + +The sample rate to use (in Hz). Higher values are more demanding for the CPU to generate, but result in better quality. + +In games, common sample rates in use are ``11025``, ``16000``, ``22050``, ``32000``, ``44100``, and ``48000``. + +According to the `Nyquist-Shannon sampling theorem `__, there is no quality difference to human hearing when going past 40,000 Hz (since most humans can only hear up to ~20,000 Hz, often less). If you are generating lower-pitched sounds such as voices, lower sample rates such as ``32000`` or ``22050`` may be usable with no loss in quality. + +\ **Note:** **AudioStreamGenerator** is not automatically resampling input data, to produce expected result :ref:`mix_rate_mode` should match the sampling rate of input data. + +\ **Note:** If you are using :ref:`AudioEffectCapture` as the source of your data, set :ref:`mix_rate_mode` to :ref:`MIX_RATE_INPUT` or :ref:`MIX_RATE_OUTPUT` to automatically match current :ref:`AudioServer` mixing rate. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamGenerator_property_mix_rate_mode: + +.. rst-class:: classref-property + +:ref:`AudioStreamGeneratorMixRate` **mix_rate_mode** = ``2`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mix_rate_mode**\ (\ value\: :ref:`AudioStreamGeneratorMixRate`\ ) +- :ref:`AudioStreamGeneratorMixRate` **get_mix_rate_mode**\ (\ ) -+-----------+---------------------+ -| *Default* | ``44100.0`` | -+-----------+---------------------+ -| *Setter* | set_mix_rate(value) | -+-----------+---------------------+ -| *Getter* | get_mix_rate() | -+-----------+---------------------+ +Mixing rate mode. If set to :ref:`MIX_RATE_CUSTOM`, :ref:`mix_rate` is used, otherwise current :ref:`AudioServer` mixing rate is used. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamgeneratorplayback.rst b/classes/class_audiostreamgeneratorplayback.rst index 84d744a3348..17314378a8a 100644 --- a/classes/class_audiostreamgeneratorplayback.rst +++ b/classes/class_audiostreamgeneratorplayback.rst @@ -1,74 +1,140 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamGeneratorPlayback.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamGeneratorPlayback.xml. .. _class_AudioStreamGeneratorPlayback: AudioStreamGeneratorPlayback ============================ -**Inherits:** :ref:`AudioStreamPlaybackResampled` **<** :ref:`AudioStreamPlayback` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioStreamPlaybackResampled` **<** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` +Plays back audio generated using :ref:`AudioStreamGenerator`. +.. rst-class:: classref-introduction-group + +Description +----------- + +This class is meant to be used with :ref:`AudioStreamGenerator` to play back the generated audio in real-time. + +.. rst-class:: classref-introduction-group Tutorials --------- -- `https://github.com/godotengine/godot-demo-projects/tree/master/audio/generator `_ +- `Audio Generator Demo `__ + +- `Godot 3.2 will get new audio features `__ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`can_push_buffer` **(** :ref:`int` amount **)** const | -+-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_buffer` **(** **)** | -+-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_frames_available` **(** **)** const | -+-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_skips` **(** **)** const | -+-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`push_buffer` **(** :ref:`PackedVector2Array` frames **)** | -+-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`push_frame` **(** :ref:`Vector2` frame **)** | -+-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`can_push_buffer`\ (\ amount\: :ref:`int`\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_buffer`\ (\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_frames_available`\ (\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_skips`\ (\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`push_buffer`\ (\ frames\: :ref:`PackedVector2Array`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`push_frame`\ (\ frame\: :ref:`Vector2`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AudioStreamGeneratorPlayback_method_can_push_buffer: -- :ref:`bool` **can_push_buffer** **(** :ref:`int` amount **)** const +.. rst-class:: classref-method + +:ref:`bool` **can_push_buffer**\ (\ amount\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if a buffer of the size ``amount`` can be pushed to the audio sample data buffer without overflowing it, ``false`` otherwise. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamGeneratorPlayback_method_clear_buffer: -- void **clear_buffer** **(** **)** +.. rst-class:: classref-method + +|void| **clear_buffer**\ (\ ) :ref:`🔗` + +Clears the audio sample data buffer. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamGeneratorPlayback_method_get_frames_available: -- :ref:`int` **get_frames_available** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_frames_available**\ (\ ) |const| :ref:`🔗` + +Returns the number of frames that can be pushed to the audio sample data buffer without overflowing it. If the result is ``0``, the buffer is full. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamGeneratorPlayback_method_get_skips: -- :ref:`int` **get_skips** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_skips**\ (\ ) |const| :ref:`🔗` + +Returns the number of times the playback skipped due to a buffer underrun in the audio sample data. This value is reset at the start of the playback. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamGeneratorPlayback_method_push_buffer: -- :ref:`bool` **push_buffer** **(** :ref:`PackedVector2Array` frames **)** +.. rst-class:: classref-method + +:ref:`bool` **push_buffer**\ (\ frames\: :ref:`PackedVector2Array`\ ) :ref:`🔗` + +Pushes several audio data frames to the buffer. This is usually more efficient than :ref:`push_frame()` in C# and compiled languages via GDExtension, but :ref:`push_buffer()` may be *less* efficient in GDScript. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamGeneratorPlayback_method_push_frame: -- :ref:`bool` **push_frame** **(** :ref:`Vector2` frame **)** +.. rst-class:: classref-method + +:ref:`bool` **push_frame**\ (\ frame\: :ref:`Vector2`\ ) :ref:`🔗` + +Pushes a single audio data frame to the buffer. This is usually less efficient than :ref:`push_buffer()` in C# and compiled languages via GDExtension, but :ref:`push_frame()` may be *more* efficient in GDScript. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreaminteractive.rst b/classes/class_audiostreaminteractive.rst new file mode 100644 index 00000000000..371782ef65f --- /dev/null +++ b/classes/class_audiostreaminteractive.rst @@ -0,0 +1,556 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/interactive_music/doc_classes/AudioStreamInteractive.xml. + +.. _class_AudioStreamInteractive: + +AudioStreamInteractive +====================== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Audio stream that can playback music interactively, combining clips and a transition table. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This is an audio stream that can playback music interactively, combining clips and a transition table. Clips must be added first, and then the transition rules via the :ref:`add_transition()`. Additionally, this stream exports a property parameter to control the playback via :ref:`AudioStreamPlayer`, :ref:`AudioStreamPlayer2D`, or :ref:`AudioStreamPlayer3D`. + +The way this is used is by filling a number of clips, then configuring the transition table. From there, clips are selected for playback and the music will smoothly go from the current to the new one while using the corresponding transition rule defined in the transition table. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------+-------------------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`clip_count` | ``0`` | + +-----------------------+-------------------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`initial_clip` | ``0`` | + +-----------------------+-------------------------------------------------------------------------+-------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_transition`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`, from_time\: :ref:`TransitionFromTime`, to_time\: :ref:`TransitionToTime`, fade_mode\: :ref:`FadeMode`, fade_beats\: :ref:`float`, use_filler_clip\: :ref:`bool` = false, filler_clip\: :ref:`int` = -1, hold_previous\: :ref:`bool` = false\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`erase_transition`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AutoAdvanceMode` | :ref:`get_clip_auto_advance`\ (\ clip_index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_clip_auto_advance_next_clip`\ (\ clip_index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_clip_name`\ (\ clip_index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStream` | :ref:`get_clip_stream`\ (\ clip_index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_transition_fade_beats`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FadeMode` | :ref:`get_transition_fade_mode`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_transition_filler_clip`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`TransitionFromTime` | :ref:`get_transition_from_time`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`get_transition_list`\ (\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`TransitionToTime` | :ref:`get_transition_to_time`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_transition`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_transition_holding_previous`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_transition_using_filler_clip`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_clip_auto_advance`\ (\ clip_index\: :ref:`int`, mode\: :ref:`AutoAdvanceMode`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_clip_auto_advance_next_clip`\ (\ clip_index\: :ref:`int`, auto_advance_next_clip\: :ref:`int`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_clip_name`\ (\ clip_index\: :ref:`int`, name\: :ref:`StringName`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_clip_stream`\ (\ clip_index\: :ref:`int`, stream\: :ref:`AudioStream`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AudioStreamInteractive_TransitionFromTime: + +.. rst-class:: classref-enumeration + +enum **TransitionFromTime**: :ref:`🔗` + +.. _class_AudioStreamInteractive_constant_TRANSITION_FROM_TIME_IMMEDIATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionFromTime` **TRANSITION_FROM_TIME_IMMEDIATE** = ``0`` + +Start transition as soon as possible, don't wait for any specific time position. + +.. _class_AudioStreamInteractive_constant_TRANSITION_FROM_TIME_NEXT_BEAT: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionFromTime` **TRANSITION_FROM_TIME_NEXT_BEAT** = ``1`` + +Transition when the clip playback position reaches the next beat. + +.. _class_AudioStreamInteractive_constant_TRANSITION_FROM_TIME_NEXT_BAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionFromTime` **TRANSITION_FROM_TIME_NEXT_BAR** = ``2`` + +Transition when the clip playback position reaches the next bar. + +.. _class_AudioStreamInteractive_constant_TRANSITION_FROM_TIME_END: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionFromTime` **TRANSITION_FROM_TIME_END** = ``3`` + +Transition when the current clip finished playing. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioStreamInteractive_TransitionToTime: + +.. rst-class:: classref-enumeration + +enum **TransitionToTime**: :ref:`🔗` + +.. _class_AudioStreamInteractive_constant_TRANSITION_TO_TIME_SAME_POSITION: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionToTime` **TRANSITION_TO_TIME_SAME_POSITION** = ``0`` + +Transition to the same position in the destination clip. This is useful when both clips have exactly the same length and the music should fade between them. + +.. _class_AudioStreamInteractive_constant_TRANSITION_TO_TIME_START: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionToTime` **TRANSITION_TO_TIME_START** = ``1`` + +Transition to the start of the destination clip. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioStreamInteractive_FadeMode: + +.. rst-class:: classref-enumeration + +enum **FadeMode**: :ref:`🔗` + +.. _class_AudioStreamInteractive_constant_FADE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_DISABLED** = ``0`` + +Do not use fade for the transition. This is useful when transitioning from a clip-end to clip-beginning, and each clip has their begin/end. + +.. _class_AudioStreamInteractive_constant_FADE_IN: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_IN** = ``1`` + +Use a fade-in in the next clip, let the current clip finish. + +.. _class_AudioStreamInteractive_constant_FADE_OUT: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_OUT** = ``2`` + +Use a fade-out in the current clip, the next clip will start by itself. + +.. _class_AudioStreamInteractive_constant_FADE_CROSS: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_CROSS** = ``3`` + +Use a cross-fade between clips. + +.. _class_AudioStreamInteractive_constant_FADE_AUTOMATIC: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_AUTOMATIC** = ``4`` + +Use automatic fade logic depending on the transition from/to. It is recommended to use this by default. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioStreamInteractive_AutoAdvanceMode: + +.. rst-class:: classref-enumeration + +enum **AutoAdvanceMode**: :ref:`🔗` + +.. _class_AudioStreamInteractive_constant_AUTO_ADVANCE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`AutoAdvanceMode` **AUTO_ADVANCE_DISABLED** = ``0`` + +Disable auto-advance (default). + +.. _class_AudioStreamInteractive_constant_AUTO_ADVANCE_ENABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`AutoAdvanceMode` **AUTO_ADVANCE_ENABLED** = ``1`` + +Enable auto-advance, a clip must be specified. + +.. _class_AudioStreamInteractive_constant_AUTO_ADVANCE_RETURN_TO_HOLD: + +.. rst-class:: classref-enumeration-constant + +:ref:`AutoAdvanceMode` **AUTO_ADVANCE_RETURN_TO_HOLD** = ``2`` + +Enable auto-advance, but instead of specifying a clip, the playback will return to hold (see :ref:`add_transition()`). + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_AudioStreamInteractive_constant_CLIP_ANY: + +.. rst-class:: classref-constant + +**CLIP_ANY** = ``-1`` :ref:`🔗` + +This constant describes that any clip is valid for a specific transition as either source or destination. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamInteractive_property_clip_count: + +.. rst-class:: classref-property + +:ref:`int` **clip_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_clip_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_clip_count**\ (\ ) + +Amount of clips contained in this interactive player. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_property_initial_clip: + +.. rst-class:: classref-property + +:ref:`int` **initial_clip** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_initial_clip**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_initial_clip**\ (\ ) + +Index of the initial clip, which will be played first when this stream is played. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamInteractive_method_add_transition: + +.. rst-class:: classref-method + +|void| **add_transition**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`, from_time\: :ref:`TransitionFromTime`, to_time\: :ref:`TransitionToTime`, fade_mode\: :ref:`FadeMode`, fade_beats\: :ref:`float`, use_filler_clip\: :ref:`bool` = false, filler_clip\: :ref:`int` = -1, hold_previous\: :ref:`bool` = false\ ) :ref:`🔗` + +Add a transition between two clips. Provide the indices of the source and destination clips, or use the :ref:`CLIP_ANY` constant to indicate that transition happens to/from any clip to this one. + +\* ``from_time`` indicates the moment in the current clip the transition will begin after triggered. + +\* ``to_time`` indicates the time in the next clip that the playback will start from. + +\* ``fade_mode`` indicates how the fade will happen between clips. If unsure, just use :ref:`FADE_AUTOMATIC` which uses the most common type of fade for each situation. + +\* ``fade_beats`` indicates how many beats the fade will take. Using decimals is allowed. + +\* ``use_filler_clip`` indicates that there will be a filler clip used between the source and destination clips. + +\* ``filler_clip`` the index of the filler clip. + +\* If ``hold_previous`` is used, then this clip will be remembered. This can be used together with :ref:`AUTO_ADVANCE_RETURN_TO_HOLD` to return to this clip after another is done playing. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_erase_transition: + +.. rst-class:: classref-method + +|void| **erase_transition**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) :ref:`🔗` + +Erase a transition by providing ``from_clip`` and ``to_clip`` clip indices. :ref:`CLIP_ANY` can be used for either argument or both. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_clip_auto_advance: + +.. rst-class:: classref-method + +:ref:`AutoAdvanceMode` **get_clip_auto_advance**\ (\ clip_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Return whether a clip has auto-advance enabled. See :ref:`set_clip_auto_advance()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_clip_auto_advance_next_clip: + +.. rst-class:: classref-method + +:ref:`int` **get_clip_auto_advance_next_clip**\ (\ clip_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the clip towards which the clip referenced by ``clip_index`` will auto-advance to. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_clip_name: + +.. rst-class:: classref-method + +:ref:`StringName` **get_clip_name**\ (\ clip_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the name of a clip. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_clip_stream: + +.. rst-class:: classref-method + +:ref:`AudioStream` **get_clip_stream**\ (\ clip_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the :ref:`AudioStream` associated with a clip. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_fade_beats: + +.. rst-class:: classref-method + +:ref:`float` **get_transition_fade_beats**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the time (in beats) for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_fade_mode: + +.. rst-class:: classref-method + +:ref:`FadeMode` **get_transition_fade_mode**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the mode for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_filler_clip: + +.. rst-class:: classref-method + +:ref:`int` **get_transition_filler_clip**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the filler clip for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_from_time: + +.. rst-class:: classref-method + +:ref:`TransitionFromTime` **get_transition_from_time**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the source time position for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_list: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **get_transition_list**\ (\ ) |const| :ref:`🔗` + +Return the list of transitions (from, to interleaved). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_to_time: + +.. rst-class:: classref-method + +:ref:`TransitionToTime` **get_transition_to_time**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the destination time position for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_has_transition: + +.. rst-class:: classref-method + +:ref:`bool` **has_transition**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if a given transition exists (was added via :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_is_transition_holding_previous: + +.. rst-class:: classref-method + +:ref:`bool` **is_transition_holding_previous**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return whether a transition uses the *hold previous* functionality (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_is_transition_using_filler_clip: + +.. rst-class:: classref-method + +:ref:`bool` **is_transition_using_filler_clip**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return whether a transition uses the *filler clip* functionality (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_set_clip_auto_advance: + +.. rst-class:: classref-method + +|void| **set_clip_auto_advance**\ (\ clip_index\: :ref:`int`, mode\: :ref:`AutoAdvanceMode`\ ) :ref:`🔗` + +Set whether a clip will auto-advance by changing the auto-advance mode. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_set_clip_auto_advance_next_clip: + +.. rst-class:: classref-method + +|void| **set_clip_auto_advance_next_clip**\ (\ clip_index\: :ref:`int`, auto_advance_next_clip\: :ref:`int`\ ) :ref:`🔗` + +Set the index of the next clip towards which this clip will auto advance to when finished. If the clip being played loops, then auto-advance will be ignored. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_set_clip_name: + +.. rst-class:: classref-method + +|void| **set_clip_name**\ (\ clip_index\: :ref:`int`, name\: :ref:`StringName`\ ) :ref:`🔗` + +Set the name of the current clip (for easier identification). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_set_clip_stream: + +.. rst-class:: classref-method + +|void| **set_clip_stream**\ (\ clip_index\: :ref:`int`, stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +Set the :ref:`AudioStream` associated with the current clip. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreammicrophone.rst b/classes/class_audiostreammicrophone.rst index 8a4707c5c71..8c6a4c0408c 100644 --- a/classes/class_audiostreammicrophone.rst +++ b/classes/class_audiostreammicrophone.rst @@ -1,15 +1,43 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamMicrophone.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamMicrophone.xml. .. _class_AudioStreamMicrophone: AudioStreamMicrophone ===================== -**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` +Plays real-time audio input data. +.. rst-class:: classref-introduction-group +Description +----------- + +When used directly in an :ref:`AudioStreamPlayer` node, **AudioStreamMicrophone** plays back microphone input in real-time. This can be used in conjunction with :ref:`AudioEffectCapture` to process the data or save it. + +\ **Note:** :ref:`ProjectSettings.audio/driver/enable_input` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Recording with microphone <../tutorials/audio/recording_with_microphone>` + +- `Audio Mic Record Demo `__ + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreammp3.rst b/classes/class_audiostreammp3.rst new file mode 100644 index 00000000000..699e061f500 --- /dev/null +++ b/classes/class_audiostreammp3.rst @@ -0,0 +1,239 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/minimp3/doc_classes/AudioStreamMP3.xml. + +.. _class_AudioStreamMP3: + +AudioStreamMP3 +============== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +MP3 audio stream driver. + +.. rst-class:: classref-introduction-group + +Description +----------- + +MP3 audio stream driver. See :ref:`data` if you want to load an MP3 file at run-time. + +\ **Note:** This class can optionally support legacy MP1 and MP2 formats, provided that the engine is compiled with the ``minimp3_extra_formats=yes`` SCons option. These extra formats are not enabled by default. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------------------------+---------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`bar_beats` | ``4`` | + +-----------------------------------------------+---------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`beat_count` | ``0`` | + +-----------------------------------------------+---------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`bpm` | ``0.0`` | + +-----------------------------------------------+---------------------------------------------------------------+-----------------------+ + | :ref:`PackedByteArray` | :ref:`data` | ``PackedByteArray()`` | + +-----------------------------------------------+---------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`loop` | ``false`` | + +-----------------------------------------------+---------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`loop_offset` | ``0.0`` | + +-----------------------------------------------+---------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamMP3` | :ref:`load_from_buffer`\ (\ stream_data\: :ref:`PackedByteArray`\ ) |static| | + +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamMP3` | :ref:`load_from_file`\ (\ path\: :ref:`String`\ ) |static| | + +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamMP3_property_bar_beats: + +.. rst-class:: classref-property + +:ref:`int` **bar_beats** = ``4`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_bar_beats**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_bar_beats**\ (\ ) + +.. container:: contribute + + There is currently no description for this property. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamMP3_property_beat_count: + +.. rst-class:: classref-property + +:ref:`int` **beat_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_beat_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_beat_count**\ (\ ) + +.. container:: contribute + + There is currently no description for this property. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamMP3_property_bpm: + +.. rst-class:: classref-property + +:ref:`float` **bpm** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_bpm**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_bpm**\ (\ ) + +.. container:: contribute + + There is currently no description for this property. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamMP3_property_data: + +.. rst-class:: classref-property + +:ref:`PackedByteArray` **data** = ``PackedByteArray()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_data**\ (\ value\: :ref:`PackedByteArray`\ ) +- :ref:`PackedByteArray` **get_data**\ (\ ) + +Contains the audio data in bytes. + +You can load a file without having to import it beforehand using the code snippet below. Keep in mind that this snippet loads the whole file into memory and may not be ideal for huge files (hundreds of megabytes or more). + + +.. tabs:: + + .. code-tab:: gdscript + + func load_mp3(path): + var file = FileAccess.open(path, FileAccess.READ) + var sound = AudioStreamMP3.new() + sound.data = file.get_buffer(file.get_length()) + return sound + + .. code-tab:: csharp + + public AudioStreamMP3 LoadMP3(string path) + { + using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read); + var sound = new AudioStreamMP3(); + sound.Data = file.GetBuffer(file.GetLength()); + return sound; + } + + + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedByteArray` for more details. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamMP3_property_loop: + +.. rst-class:: classref-property + +:ref:`bool` **loop** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **has_loop**\ (\ ) + +If ``true``, the stream will automatically loop when it reaches the end. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamMP3_property_loop_offset: + +.. rst-class:: classref-property + +:ref:`float` **loop_offset** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop_offset**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_loop_offset**\ (\ ) + +Time in seconds at which the stream starts after being looped. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamMP3_method_load_from_buffer: + +.. rst-class:: classref-method + +:ref:`AudioStreamMP3` **load_from_buffer**\ (\ stream_data\: :ref:`PackedByteArray`\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamMP3** instance from the given buffer. The buffer must contain MP3 data. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamMP3_method_load_from_file: + +.. rst-class:: classref-method + +:ref:`AudioStreamMP3` **load_from_file**\ (\ path\: :ref:`String`\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamMP3** instance from the given file path. The file must be in MP3 format. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamoggvorbis.rst b/classes/class_audiostreamoggvorbis.rst index dab71808d99..e78ffb5501f 100644 --- a/classes/class_audiostreamoggvorbis.rst +++ b/classes/class_audiostreamoggvorbis.rst @@ -1,80 +1,240 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamOGGVorbis.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/vorbis/doc_classes/AudioStreamOggVorbis.xml. -.. _class_AudioStreamOGGVorbis: +.. _class_AudioStreamOggVorbis: -AudioStreamOGGVorbis +AudioStreamOggVorbis ==================== -**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -OGG Vorbis audio stream driver. +A class representing an Ogg Vorbis audio stream. + +.. rst-class:: classref-introduction-group Description ----------- -OGG Vorbis audio stream driver. +The AudioStreamOggVorbis class is a specialized :ref:`AudioStream` for handling Ogg Vorbis file formats. It offers functionality for loading and playing back Ogg Vorbis files, as well as managing looping and other playback properties. This class is part of the audio stream system, which also supports WAV files through the :ref:`AudioStreamWAV` class. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Runtime file loading and saving <../tutorials/io/runtime_file_loading_and_saving>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`PackedByteArray` | :ref:`data` | ``PackedByteArray( )`` | -+-----------------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`loop` | ``false`` | -+-----------------------------------------------+---------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`loop_offset` | ``0.0`` | -+-----------------------------------------------+---------------------------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`bar_beats` | ``4`` | + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`beat_count` | ``0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`bpm` | ``0.0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`loop` | ``false`` | + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`loop_offset` | ``0.0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`OggPacketSequence` | :ref:`packet_sequence` | | + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`Dictionary` | :ref:`tags` | ``{}`` | + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamOggVorbis` | :ref:`load_from_buffer`\ (\ stream_data\: :ref:`PackedByteArray`\ ) |static| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamOggVorbis` | :ref:`load_from_file`\ (\ path\: :ref:`String`\ ) |static| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- -.. _class_AudioStreamOGGVorbis_property_data: +.. _class_AudioStreamOggVorbis_property_bar_beats: + +.. rst-class:: classref-property + +:ref:`int` **bar_beats** = ``4`` :ref:`🔗` -- :ref:`PackedByteArray` **data** +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``PackedByteArray( )`` | -+-----------+-------------------------+ -| *Setter* | set_data(value) | -+-----------+-------------------------+ -| *Getter* | get_data() | -+-----------+-------------------------+ +- |void| **set_bar_beats**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_bar_beats**\ (\ ) -Contains the audio data in bytes. +.. container:: contribute + + There is currently no description for this property. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- -.. _class_AudioStreamOGGVorbis_property_loop: +.. _class_AudioStreamOggVorbis_property_beat_count: + +.. rst-class:: classref-property + +:ref:`int` **beat_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`bool` **loop** +- |void| **set_beat_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_beat_count**\ (\ ) -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_loop(value) | -+-----------+-----------------+ -| *Getter* | has_loop() | -+-----------+-----------------+ +.. container:: contribute -If ``true``, the stream will automatically loop when it reaches the end. + There is currently no description for this property. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator ---- -.. _class_AudioStreamOGGVorbis_property_loop_offset: +.. _class_AudioStreamOggVorbis_property_bpm: + +.. rst-class:: classref-property + +:ref:`float` **bpm** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_bpm**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_bpm**\ (\ ) + +.. container:: contribute + + There is currently no description for this property. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamOggVorbis_property_loop: + +.. rst-class:: classref-property + +:ref:`bool` **loop** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **has_loop**\ (\ ) + +If ``true``, the audio will play again from the specified :ref:`loop_offset` once it is done playing. Useful for ambient sounds and background music. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamOggVorbis_property_loop_offset: + +.. rst-class:: classref-property + +:ref:`float` **loop_offset** = ``0.0`` :ref:`🔗` -- :ref:`float` **loop_offset** +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``0.0`` | -+-----------+------------------------+ -| *Setter* | set_loop_offset(value) | -+-----------+------------------------+ -| *Getter* | get_loop_offset() | -+-----------+------------------------+ +- |void| **set_loop_offset**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_loop_offset**\ (\ ) Time in seconds at which the stream starts after being looped. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamOggVorbis_property_packet_sequence: + +.. rst-class:: classref-property + +:ref:`OggPacketSequence` **packet_sequence** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_packet_sequence**\ (\ value\: :ref:`OggPacketSequence`\ ) +- :ref:`OggPacketSequence` **get_packet_sequence**\ (\ ) + +Contains the raw Ogg data for this stream. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamOggVorbis_property_tags: + +.. rst-class:: classref-property + +:ref:`Dictionary` **tags** = ``{}`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_tags**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_tags**\ (\ ) + +Contains user-defined tags if found in the Ogg Vorbis data. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date`` (``date`` does not have a standard date format). + +\ **Note:** No tag is *guaranteed* to be present in every file, so make sure to account for the keys not always existing. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamOggVorbis_method_load_from_buffer: + +.. rst-class:: classref-method + +:ref:`AudioStreamOggVorbis` **load_from_buffer**\ (\ stream_data\: :ref:`PackedByteArray`\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamOggVorbis** instance from the given buffer. The buffer must contain Ogg Vorbis data. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamOggVorbis_method_load_from_file: + +.. rst-class:: classref-method + +:ref:`AudioStreamOggVorbis` **load_from_file**\ (\ path\: :ref:`String`\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamOggVorbis** instance from the given file path. The file must be in Ogg Vorbis format. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplayback.rst b/classes/class_audiostreamplayback.rst index 4c54f31bbe3..1867220ccdf 100644 --- a/classes/class_audiostreamplayback.rst +++ b/classes/class_audiostreamplayback.rst @@ -1,22 +1,332 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamPlayback.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamPlayback.xml. .. _class_AudioStreamPlayback: AudioStreamPlayback =================== -**Inherits:** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AudioStreamPlaybackResampled` +**Inherited By:** :ref:`AudioStreamPlaybackInteractive`, :ref:`AudioStreamPlaybackPlaylist`, :ref:`AudioStreamPlaybackPolyphonic`, :ref:`AudioStreamPlaybackResampled`, :ref:`AudioStreamPlaybackSynchronized` Meta class for playing back audio. +.. rst-class:: classref-introduction-group + Description ----------- -Can play, loop, pause a scroll through audio. See :ref:`AudioStream` and :ref:`AudioStreamOGGVorbis` for usage. +Can play, loop, pause a scroll through audio. See :ref:`AudioStream` and :ref:`AudioStreamOggVorbis` for usage. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Audio Generator Demo `__ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_get_loop_count`\ (\ ) |virtual| |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`_get_parameter`\ (\ name\: :ref:`StringName`\ ) |virtual| |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_get_playback_position`\ (\ ) |virtual| |required| |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_is_playing`\ (\ ) |virtual| |required| |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_mix`\ (\ buffer\: ``AudioFrame*``, rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) |virtual| |required| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_seek`\ (\ position\: :ref:`float`\ ) |virtual| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_set_parameter`\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) |virtual| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_start`\ (\ from_pos\: :ref:`float`\ ) |virtual| |required| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_stop`\ (\ ) |virtual| |required| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_tag_used_streams`\ (\ ) |virtual| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_loop_count`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playback_position`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioSamplePlayback` | :ref:`get_sample_playback`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`mix_audio`\ (\ rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seek`\ (\ time\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_sample_playback`\ (\ playback_sample\: :ref:`AudioSamplePlayback`\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`start`\ (\ from_pos\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamPlayback_private_method__get_loop_count: + +.. rst-class:: classref-method + +:ref:`int` **_get_loop_count**\ (\ ) |virtual| |const| :ref:`🔗` + +Overridable method. Should return how many times this audio stream has looped. Most built-in playbacks always return ``0``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__get_parameter: + +.. rst-class:: classref-method + +:ref:`Variant` **_get_parameter**\ (\ name\: :ref:`StringName`\ ) |virtual| |const| :ref:`🔗` + +Return the current value of a playback parameter by name (see :ref:`AudioStream._get_parameter_list()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__get_playback_position: + +.. rst-class:: classref-method + +:ref:`float` **_get_playback_position**\ (\ ) |virtual| |required| |const| :ref:`🔗` + +Overridable method. Should return the current progress along the audio stream, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__is_playing: + +.. rst-class:: classref-method + +:ref:`bool` **_is_playing**\ (\ ) |virtual| |required| |const| :ref:`🔗` + +Overridable method. Should return ``true`` if this playback is active and playing its audio stream. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__mix: + +.. rst-class:: classref-method + +:ref:`int` **_mix**\ (\ buffer\: ``AudioFrame*``, rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) |virtual| |required| :ref:`🔗` + +Override this method to customize how the audio stream is mixed. This method is called even if the playback is not active. + +\ **Note:** It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__seek: + +.. rst-class:: classref-method + +|void| **_seek**\ (\ position\: :ref:`float`\ ) |virtual| :ref:`🔗` + +Override this method to customize what happens when seeking this audio stream at the given ``position``, such as by calling :ref:`AudioStreamPlayer.seek()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__set_parameter: + +.. rst-class:: classref-method + +|void| **_set_parameter**\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) |virtual| :ref:`🔗` + +Set the current value of a playback parameter by name (see :ref:`AudioStream._get_parameter_list()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__start: + +.. rst-class:: classref-method + +|void| **_start**\ (\ from_pos\: :ref:`float`\ ) |virtual| |required| :ref:`🔗` + +Override this method to customize what happens when the playback starts at the given position, such as by calling :ref:`AudioStreamPlayer.play()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__stop: + +.. rst-class:: classref-method + +|void| **_stop**\ (\ ) |virtual| |required| :ref:`🔗` + +Override this method to customize what happens when the playback is stopped, such as by calling :ref:`AudioStreamPlayer.stop()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_private_method__tag_used_streams: + +.. rst-class:: classref-method + +|void| **_tag_used_streams**\ (\ ) |virtual| :ref:`🔗` + +Overridable method. Called whenever the audio stream is mixed if the playback is active and :ref:`AudioServer.set_enable_tagging_used_audio_streams()` has been set to ``true``. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_get_loop_count: + +.. rst-class:: classref-method + +:ref:`int` **get_loop_count**\ (\ ) |const| :ref:`🔗` + +Returns the number of times the stream has looped. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_get_playback_position: + +.. rst-class:: classref-method + +:ref:`float` **get_playback_position**\ (\ ) |const| :ref:`🔗` + +Returns the current position in the stream, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_get_sample_playback: + +.. rst-class:: classref-method + +:ref:`AudioSamplePlayback` **get_sample_playback**\ (\ ) |const| :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Returns the :ref:`AudioSamplePlayback` associated with this **AudioStreamPlayback** for playing back the audio sample of this stream. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_is_playing: + +.. rst-class:: classref-method + +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the stream is playing. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_mix_audio: + +.. rst-class:: classref-method + +:ref:`PackedVector2Array` **mix_audio**\ (\ rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) :ref:`🔗` + +Mixes up to ``frames`` of audio from the stream from the current position, at a rate of ``rate_scale``, advancing the stream. + +Returns a :ref:`PackedVector2Array` where each element holds the left and right channel volume levels of each frame. + +\ **Note:** Can return fewer frames than requested, make sure to use the size of the return value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_seek: + +.. rst-class:: classref-method + +|void| **seek**\ (\ time\: :ref:`float` = 0.0\ ) :ref:`🔗` + +Seeks the stream at the given ``time``, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_set_sample_playback: + +.. rst-class:: classref-method + +|void| **set_sample_playback**\ (\ playback_sample\: :ref:`AudioSamplePlayback`\ ) :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Associates :ref:`AudioSamplePlayback` to this **AudioStreamPlayback** for playing back the audio sample of this stream. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_start: + +.. rst-class:: classref-method + +|void| **start**\ (\ from_pos\: :ref:`float` = 0.0\ ) :ref:`🔗` + +Starts the stream from the given ``from_pos``, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_stop: + +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`🔗` + +Stops the stream. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaybackinteractive.rst b/classes/class_audiostreamplaybackinteractive.rst new file mode 100644 index 00000000000..c80a3e690b6 --- /dev/null +++ b/classes/class_audiostreamplaybackinteractive.rst @@ -0,0 +1,100 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/interactive_music/doc_classes/AudioStreamPlaybackInteractive.xml. + +.. _class_AudioStreamPlaybackInteractive: + +AudioStreamPlaybackInteractive +============================== + +**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` + +Playback component of :ref:`AudioStreamInteractive`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Playback component of :ref:`AudioStreamInteractive`. Contains functions to change the currently played clip. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_current_clip_index`\ (\ ) |const| | + +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`switch_to_clip`\ (\ clip_index\: :ref:`int`\ ) | + +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`switch_to_clip_by_name`\ (\ clip_name\: :ref:`StringName`\ ) | + +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamPlaybackInteractive_method_get_current_clip_index: + +.. rst-class:: classref-method + +:ref:`int` **get_current_clip_index**\ (\ ) |const| :ref:`🔗` + +Return the index of the currently playing clip. You can use this to get the name of the currently playing clip with :ref:`AudioStreamInteractive.get_clip_name()`. + +\ **Example:** Get the currently playing clip name from inside an :ref:`AudioStreamPlayer` node. + + +.. tabs:: + + .. code-tab:: gdscript + + var playing_clip_name = stream.get_clip_name(get_stream_playback().get_current_clip_index()) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackInteractive_method_switch_to_clip: + +.. rst-class:: classref-method + +|void| **switch_to_clip**\ (\ clip_index\: :ref:`int`\ ) :ref:`🔗` + +Switch to a clip (by index). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackInteractive_method_switch_to_clip_by_name: + +.. rst-class:: classref-method + +|void| **switch_to_clip_by_name**\ (\ clip_name\: :ref:`StringName`\ ) :ref:`🔗` + +Switch to a clip (by name). + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaybackoggvorbis.rst b/classes/class_audiostreamplaybackoggvorbis.rst new file mode 100644 index 00000000000..3990b7339d0 --- /dev/null +++ b/classes/class_audiostreamplaybackoggvorbis.rst @@ -0,0 +1,27 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/vorbis/doc_classes/AudioStreamPlaybackOggVorbis.xml. + +.. _class_AudioStreamPlaybackOggVorbis: + +AudioStreamPlaybackOggVorbis +============================ + +**Inherits:** :ref:`AudioStreamPlaybackResampled` **<** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` + +.. container:: contribute + + There is currently no description for this class. Please help us by `contributing one `__! + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaybackplaylist.rst b/classes/class_audiostreamplaybackplaylist.rst new file mode 100644 index 00000000000..dbc521cd265 --- /dev/null +++ b/classes/class_audiostreamplaybackplaylist.rst @@ -0,0 +1,25 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/interactive_music/doc_classes/AudioStreamPlaybackPlaylist.xml. + +.. _class_AudioStreamPlaybackPlaylist: + +AudioStreamPlaybackPlaylist +=========================== + +**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` + +Playback class used for :ref:`AudioStreamPlaylist`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaybackpolyphonic.rst b/classes/class_audiostreamplaybackpolyphonic.rst new file mode 100644 index 00000000000..6575a1a7727 --- /dev/null +++ b/classes/class_audiostreamplaybackpolyphonic.rst @@ -0,0 +1,140 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamPlaybackPolyphonic.xml. + +.. _class_AudioStreamPlaybackPolyphonic: + +AudioStreamPlaybackPolyphonic +============================= + +**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` + +Playback instance for :ref:`AudioStreamPolyphonic`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Playback instance for :ref:`AudioStreamPolyphonic`. After setting the ``stream`` property of :ref:`AudioStreamPlayer`, :ref:`AudioStreamPlayer2D`, or :ref:`AudioStreamPlayer3D`, the playback instance can be obtained by calling :ref:`AudioStreamPlayer.get_stream_playback()`, :ref:`AudioStreamPlayer2D.get_stream_playback()` or :ref:`AudioStreamPlayer3D.get_stream_playback()` methods. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_stream_playing`\ (\ stream\: :ref:`int`\ ) |const| | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`play_stream`\ (\ stream\: :ref:`AudioStream`, from_offset\: :ref:`float` = 0, volume_db\: :ref:`float` = 0, pitch_scale\: :ref:`float` = 1.0, playback_type\: :ref:`PlaybackType` = 0, bus\: :ref:`StringName` = &"Master"\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_stream_pitch_scale`\ (\ stream\: :ref:`int`, pitch_scale\: :ref:`float`\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_stream_volume`\ (\ stream\: :ref:`int`, volume_db\: :ref:`float`\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop_stream`\ (\ stream\: :ref:`int`\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_AudioStreamPlaybackPolyphonic_constant_INVALID_ID: + +.. rst-class:: classref-constant + +**INVALID_ID** = ``-1`` :ref:`🔗` + +Returned by :ref:`play_stream()` in case it could not allocate a stream for playback. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamPlaybackPolyphonic_method_is_stream_playing: + +.. rst-class:: classref-method + +:ref:`bool` **is_stream_playing**\ (\ stream\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the stream associated with the given integer ID is still playing. Check :ref:`play_stream()` for information on when this ID becomes invalid. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackPolyphonic_method_play_stream: + +.. rst-class:: classref-method + +:ref:`int` **play_stream**\ (\ stream\: :ref:`AudioStream`, from_offset\: :ref:`float` = 0, volume_db\: :ref:`float` = 0, pitch_scale\: :ref:`float` = 1.0, playback_type\: :ref:`PlaybackType` = 0, bus\: :ref:`StringName` = &"Master"\ ) :ref:`🔗` + +Play an :ref:`AudioStream` at a given offset, volume, pitch scale, playback type, and bus. Playback starts immediately. + +The return value is a unique integer ID that is associated to this playback stream and which can be used to control it. + +This ID becomes invalid when the stream ends (if it does not loop), when the **AudioStreamPlaybackPolyphonic** is stopped, or when :ref:`stop_stream()` is called. + +This function returns :ref:`INVALID_ID` if the amount of streams currently playing equals :ref:`AudioStreamPolyphonic.polyphony`. If you need a higher amount of maximum polyphony, raise this value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackPolyphonic_method_set_stream_pitch_scale: + +.. rst-class:: classref-method + +|void| **set_stream_pitch_scale**\ (\ stream\: :ref:`int`, pitch_scale\: :ref:`float`\ ) :ref:`🔗` + +Change the stream pitch scale. The ``stream`` argument is an integer ID returned by :ref:`play_stream()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackPolyphonic_method_set_stream_volume: + +.. rst-class:: classref-method + +|void| **set_stream_volume**\ (\ stream\: :ref:`int`, volume_db\: :ref:`float`\ ) :ref:`🔗` + +Change the stream volume (in db). The ``stream`` argument is an integer ID returned by :ref:`play_stream()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackPolyphonic_method_stop_stream: + +.. rst-class:: classref-method + +|void| **stop_stream**\ (\ stream\: :ref:`int`\ ) :ref:`🔗` + +Stop a stream. The ``stream`` argument is an integer ID returned by :ref:`play_stream()`, which becomes invalid after calling this function. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaybackresampled.rst b/classes/class_audiostreamplaybackresampled.rst index d09ff003ef8..9851179877f 100644 --- a/classes/class_audiostreamplaybackresampled.rst +++ b/classes/class_audiostreamplaybackresampled.rst @@ -1,17 +1,92 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamPlaybackResampled.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamPlaybackResampled.xml. .. _class_AudioStreamPlaybackResampled: AudioStreamPlaybackResampled ============================ -**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AudioStreamGeneratorPlayback` +**Inherited By:** :ref:`AudioStreamGeneratorPlayback`, :ref:`AudioStreamPlaybackOggVorbis` +.. container:: contribute + There is currently no description for this class. Please help us by `contributing one `__! +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_get_stream_sampling_rate`\ (\ ) |virtual| |required| |const| | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_mix_resampled`\ (\ dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| |required| | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`begin_resample`\ (\ ) | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamPlaybackResampled_private_method__get_stream_sampling_rate: + +.. rst-class:: classref-method + +:ref:`float` **_get_stream_sampling_rate**\ (\ ) |virtual| |required| |const| :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackResampled_private_method__mix_resampled: + +.. rst-class:: classref-method + +:ref:`int` **_mix_resampled**\ (\ dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| |required| :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackResampled_method_begin_resample: + +.. rst-class:: classref-method + +|void| **begin_resample**\ (\ ) :ref:`🔗` + +.. container:: contribute + + There is currently no description for this method. Please help us by `contributing one `__! + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaybacksynchronized.rst b/classes/class_audiostreamplaybacksynchronized.rst new file mode 100644 index 00000000000..fe251137df3 --- /dev/null +++ b/classes/class_audiostreamplaybacksynchronized.rst @@ -0,0 +1,27 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/interactive_music/doc_classes/AudioStreamPlaybackSynchronized.xml. + +.. _class_AudioStreamPlaybackSynchronized: + +AudioStreamPlaybackSynchronized +=============================== + +**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` + +.. container:: contribute + + There is currently no description for this class. Please help us by `contributing one `__! + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplayer.rst b/classes/class_audiostreamplayer.rst index f05a1b7c043..ed301a53230 100644 --- a/classes/class_audiostreamplayer.rst +++ b/classes/class_audiostreamplayer.rst @@ -1,8 +1,12 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamPlayer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. meta:: + :keywords: sound, music, song + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamPlayer.xml. .. _class_AudioStreamPlayer: @@ -11,245 +15,435 @@ AudioStreamPlayer **Inherits:** :ref:`Node` **<** :ref:`Object` -Plays back audio non-positionally. +A node for audio playback. + +.. rst-class:: classref-introduction-group Description ----------- -Plays an audio stream non-positionally. +The **AudioStreamPlayer** node plays an audio stream non-positionally. It is ideal for user interfaces, menus, or background music. + +To use this node, :ref:`stream` needs to be set to a valid :ref:`AudioStream` resource. Playing more than one sound at the same time is also supported, see :ref:`max_polyphony`. + +If you need to play audio at a specific position, use :ref:`AudioStreamPlayer2D` or :ref:`AudioStreamPlayer3D` instead. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/audio/audio_streams` +- :doc:`Audio streams <../tutorials/audio/audio_streams>` + +- `2D Dodge The Creeps Demo `__ + +- `Audio Device Changer Demo `__ + +- `Audio Generator Demo `__ + +- `Audio Microphone Record Demo `__ + +- `Audio Spectrum Visualizer Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`autoplay` | ``false`` | -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ -| :ref:`StringName` | :ref:`bus` | ``@"Master"`` | -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ -| :ref:`MixTarget` | :ref:`mix_target` | ``0`` | -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`pitch_scale` | ``1.0`` | -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`playing` | ``false`` | -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ -| :ref:`AudioStream` | :ref:`stream` | | -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`stream_paused` | ``false`` | -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`volume_db` | ``0.0`` | -+----------------------------------------------------+----------------------------------------------------------------------+---------------+ +.. table:: + :widths: auto + + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`autoplay` | ``false`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`StringName` | :ref:`bus` | ``&"Master"`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`int` | :ref:`max_polyphony` | ``1`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`MixTarget` | :ref:`mix_target` | ``0`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`pitch_scale` | ``1.0`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`PlaybackType` | :ref:`playback_type` | ``0`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`playing` | ``false`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`AudioStream` | :ref:`stream` | | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`stream_paused` | ``false`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_db` | ``0.0`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_linear` | | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_playback_position` **(** **)** | -+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| :ref:`AudioStreamPlayback` | :ref:`get_stream_playback` **(** **)** | -+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| void | :ref:`play` **(** :ref:`float` from_position=0.0 **)** | -+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| void | :ref:`seek` **(** :ref:`float` to_position **)** | -+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop` **(** **)** | -+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------------------+---------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playback_position`\ (\ ) | + +-------------------------------------------------------+---------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamPlayback` | :ref:`get_stream_playback`\ (\ ) | + +-------------------------------------------------------+---------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_stream_playback`\ (\ ) | + +-------------------------------------------------------+---------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play`\ (\ from_position\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+---------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seek`\ (\ to_position\: :ref:`float`\ ) | + +-------------------------------------------------------+---------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +-------------------------------------------------------+---------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_AudioStreamPlayer_signal_finished: -- **finished** **(** **)** +.. rst-class:: classref-signal -Emitted when the audio stops playing. +**finished**\ (\ ) :ref:`🔗` + +Emitted when a sound finishes playing without interruptions. This signal is *not* emitted when calling :ref:`stop()`, or when exiting the tree while sounds are playing. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_AudioStreamPlayer_MixTarget: +.. rst-class:: classref-enumeration + +enum **MixTarget**: :ref:`🔗` + .. _class_AudioStreamPlayer_constant_MIX_TARGET_STEREO: +.. rst-class:: classref-enumeration-constant + +:ref:`MixTarget` **MIX_TARGET_STEREO** = ``0`` + +The audio will be played only on the first channel. This is the default. + .. _class_AudioStreamPlayer_constant_MIX_TARGET_SURROUND: +.. rst-class:: classref-enumeration-constant + +:ref:`MixTarget` **MIX_TARGET_SURROUND** = ``1`` + +The audio will be played on all surround channels. + .. _class_AudioStreamPlayer_constant_MIX_TARGET_CENTER: -enum **MixTarget**: +.. rst-class:: classref-enumeration-constant -- **MIX_TARGET_STEREO** = **0** --- The audio will be played only on the first channel. +:ref:`MixTarget` **MIX_TARGET_CENTER** = ``2`` -- **MIX_TARGET_SURROUND** = **1** --- The audio will be played on all surround channels. +The audio will be played on the second channel, which is usually the center. -- **MIX_TARGET_CENTER** = **2** --- The audio will be played on the second channel, which is usually the center. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioStreamPlayer_property_autoplay: -- :ref:`bool` **autoplay** +.. rst-class:: classref-property + +:ref:`bool` **autoplay** = ``false`` :ref:`🔗` -+-----------+-----------------------+ -| *Default* | ``false`` | -+-----------+-----------------------+ -| *Setter* | set_autoplay(value) | -+-----------+-----------------------+ -| *Getter* | is_autoplay_enabled() | -+-----------+-----------------------+ +.. rst-class:: classref-property-setget -If ``true``, audio plays when added to scene tree. +- |void| **set_autoplay**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_autoplay_enabled**\ (\ ) + +If ``true``, this node calls :ref:`play()` when entering the tree. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_property_bus: -- :ref:`StringName` **bus** +.. rst-class:: classref-property + +:ref:`StringName` **bus** = ``&"Master"`` :ref:`🔗` -+-----------+----------------+ -| *Default* | ``@"Master"`` | -+-----------+----------------+ -| *Setter* | set_bus(value) | -+-----------+----------------+ -| *Getter* | get_bus() | -+-----------+----------------+ +.. rst-class:: classref-property-setget -Bus on which this audio is playing. +- |void| **set_bus**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_bus**\ (\ ) + +The target bus name. All sounds from this node will be playing on this bus. + +\ **Note:** At runtime, if no bus with the given name exists, all sounds will fall back on ``"Master"``. See also :ref:`AudioServer.get_bus_name()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer_property_max_polyphony: + +.. rst-class:: classref-property + +:ref:`int` **max_polyphony** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_max_polyphony**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_max_polyphony**\ (\ ) + +The maximum number of sounds this node can play at the same time. Calling :ref:`play()` after this value is reached will cut off the oldest sounds. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_property_mix_target: -- :ref:`MixTarget` **mix_target** +.. rst-class:: classref-property + +:ref:`MixTarget` **mix_target** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_mix_target(value) | -+-----------+-----------------------+ -| *Getter* | get_mix_target() | -+-----------+-----------------------+ +- |void| **set_mix_target**\ (\ value\: :ref:`MixTarget`\ ) +- :ref:`MixTarget` **get_mix_target**\ (\ ) -If the audio configuration has more than two speakers, this sets the target channels. See :ref:`MixTarget` constants. +The mix target channels. Has no effect when two speakers or less are detected (see :ref:`SpeakerMode`). + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_property_pitch_scale: -- :ref:`float` **pitch_scale** +.. rst-class:: classref-property + +:ref:`float` **pitch_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_pitch_scale(value) | -+-----------+------------------------+ -| *Getter* | get_pitch_scale() | -+-----------+------------------------+ +- |void| **set_pitch_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pitch_scale**\ (\ ) -Changes the pitch and the tempo of the audio. +The audio's pitch and tempo, as a multiplier of the :ref:`stream`'s sample rate. A value of ``2.0`` doubles the audio's pitch, while a value of ``0.5`` halves the pitch. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer_property_playback_type: + +.. rst-class:: classref-property + +:ref:`PlaybackType` **playback_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playback_type**\ (\ value\: :ref:`PlaybackType`\ ) +- :ref:`PlaybackType` **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_property_playing: -- :ref:`bool` **playing** +.. rst-class:: classref-property + +:ref:`bool` **playing** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_playing**\ (\ ) -+-----------+--------------+ -| *Default* | ``false`` | -+-----------+--------------+ -| *Getter* | is_playing() | -+-----------+--------------+ +If ``true``, this node is playing sounds. Setting this property has the same effect as :ref:`play()` and :ref:`stop()`. -If ``true``, audio is playing. +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_property_stream: -- :ref:`AudioStream` **stream** +.. rst-class:: classref-property + +:ref:`AudioStream` **stream** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stream**\ (\ value\: :ref:`AudioStream`\ ) +- :ref:`AudioStream` **get_stream**\ (\ ) -+----------+-------------------+ -| *Setter* | set_stream(value) | -+----------+-------------------+ -| *Getter* | get_stream() | -+----------+-------------------+ +The :ref:`AudioStream` resource to be played. Setting this property stops all currently playing sounds. If left empty, the **AudioStreamPlayer** does not work. -The :ref:`AudioStream` object to be played. +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_property_stream_paused: -- :ref:`bool` **stream_paused** +.. rst-class:: classref-property -+-----------+--------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------+ -| *Setter* | set_stream_paused(value) | -+-----------+--------------------------+ -| *Getter* | get_stream_paused() | -+-----------+--------------------------+ +:ref:`bool` **stream_paused** = ``false`` :ref:`🔗` -If ``true``, the playback is paused. You can resume it by setting ``stream_paused`` to ``false``. +.. rst-class:: classref-property-setget + +- |void| **set_stream_paused**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_stream_paused**\ (\ ) + +If ``true``, the sounds are paused. Setting :ref:`stream_paused` to ``false`` resumes all sounds. + +\ **Note:** This property is automatically changed when exiting or entering the tree, or this node is paused (see :ref:`Node.process_mode`). + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_property_volume_db: -- :ref:`float` **volume_db** +.. rst-class:: classref-property + +:ref:`float` **volume_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_db**\ (\ ) + +Volume of sound, in decibels. This is an offset of the :ref:`stream`'s volume. + +\ **Note:** To convert between decibel and linear energy (like most volume sliders do), use :ref:`volume_linear`, or :ref:`@GlobalScope.db_to_linear()` and :ref:`@GlobalScope.linear_to_db()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer_property_volume_linear: -+-----------+----------------------+ -| *Default* | ``0.0`` | -+-----------+----------------------+ -| *Setter* | set_volume_db(value) | -+-----------+----------------------+ -| *Getter* | get_volume_db() | -+-----------+----------------------+ +.. rst-class:: classref-property -Volume of sound, in dB. +:ref:`float` **volume_linear** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_linear**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_linear**\ (\ ) + +Volume of sound, as a linear value. + +\ **Note:** This member modifies :ref:`volume_db` for convenience. The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on :ref:`volume_db`. Setting this member is equivalent to setting :ref:`volume_db` to the result of :ref:`@GlobalScope.linear_to_db()` on a value. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AudioStreamPlayer_method_get_playback_position: -- :ref:`float` **get_playback_position** **(** **)** +.. rst-class:: classref-method + +:ref:`float` **get_playback_position**\ (\ ) :ref:`🔗` + +Returns the position in the :ref:`AudioStream` of the latest sound, in seconds. Returns ``0.0`` if no sounds are playing. -Returns the position in the :ref:`AudioStream` in seconds. +\ **Note:** The position is not always accurate, as the :ref:`AudioServer` does not mix audio every processed frame. To get more accurate results, add :ref:`AudioServer.get_time_since_last_mix()` to the returned position. + +\ **Note:** This method always returns ``0.0`` if the :ref:`stream` is an :ref:`AudioStreamInteractive`, since it can have multiple clips playing at once. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_method_get_stream_playback: -- :ref:`AudioStreamPlayback` **get_stream_playback** **(** **)** +.. rst-class:: classref-method + +:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) :ref:`🔗` -Returns the :ref:`AudioStreamPlayback` object associated with this ``AudioStreamPlayer``. +Returns the latest :ref:`AudioStreamPlayback` of this node, usually the most recently created by :ref:`play()`. If no sounds are playing, this method fails and returns an empty playback. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer_method_has_stream_playback: + +.. rst-class:: classref-method + +:ref:`bool` **has_stream_playback**\ (\ ) :ref:`🔗` + +Returns ``true`` if any sound is active, even if :ref:`stream_paused` is set to ``true``. See also :ref:`playing` and :ref:`get_stream_playback()`. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_method_play: -- void **play** **(** :ref:`float` from_position=0.0 **)** +.. rst-class:: classref-method + +|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) :ref:`🔗` + +Plays a sound from the beginning, or the given ``from_position`` in seconds. -Plays the audio from the given ``from_position``, in seconds. +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_method_seek: -- void **seek** **(** :ref:`float` to_position **)** +.. rst-class:: classref-method -Sets the position from which audio will be played, in seconds. +|void| **seek**\ (\ to_position\: :ref:`float`\ ) :ref:`🔗` + +Restarts all sounds to be played from the given ``to_position``, in seconds. Does nothing if no sounds are playing. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer_method_stop: -- void **stop** **(** **)** +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`🔗` -Stops the audio. +Stops all sounds from this node. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplayer2d.rst b/classes/class_audiostreamplayer2d.rst index 659f61a9d29..08b9b80e522 100644 --- a/classes/class_audiostreamplayer2d.rst +++ b/classes/class_audiostreamplayer2d.rst @@ -1,8 +1,12 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamPlayer2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. meta:: + :keywords: sound, sfx + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamPlayer2D.xml. .. _class_AudioStreamPlayer2D: @@ -11,262 +15,437 @@ AudioStreamPlayer2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Plays audio in 2D. +Plays positional sound in 2D space. + +.. rst-class:: classref-introduction-group Description ----------- -Plays audio that dampens with distance from screen center. +Plays audio that is attenuated with distance to the listener. + +By default, audio is heard from the screen center. This can be changed by adding an :ref:`AudioListener2D` node to the scene and enabling it by calling :ref:`AudioListener2D.make_current()` on it. + +See also :ref:`AudioStreamPlayer` to play a sound non-positionally. + +\ **Note:** Hiding an **AudioStreamPlayer2D** node does not disable its audio output. To temporarily disable an **AudioStreamPlayer2D**'s audio output, set :ref:`volume_db` to a very low value like ``-100`` (which isn't audible to human hearing). + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/audio/audio_streams` +- :doc:`Audio streams <../tutorials/audio/audio_streams>` + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`int` | :ref:`area_mask` | ``1`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`attenuation` | ``1.0`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`autoplay` | ``false`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`StringName` | :ref:`bus` | ``@"Master"`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`max_distance` | ``2000.0`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`pitch_scale` | ``1.0`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`playing` | ``false`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`AudioStream` | :ref:`stream` | | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`stream_paused` | ``false`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`volume_db` | ``0.0`` | -+---------------------------------------+------------------------------------------------------------------------+---------------+ +.. table:: + :widths: auto + + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`int` | :ref:`area_mask` | ``1`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`attenuation` | ``1.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`autoplay` | ``false`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`StringName` | :ref:`bus` | ``&"Master"`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`max_distance` | ``2000.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`int` | :ref:`max_polyphony` | ``1`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`panning_strength` | ``1.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`pitch_scale` | ``1.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`PlaybackType` | :ref:`playback_type` | ``0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`playing` | ``false`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`AudioStream` | :ref:`stream` | | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`stream_paused` | ``false`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_db` | ``0.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_linear` | | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_playback_position` **(** **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| :ref:`AudioStreamPlayback` | :ref:`get_stream_playback` **(** **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| void | :ref:`play` **(** :ref:`float` from_position=0.0 **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| void | :ref:`seek` **(** :ref:`float` to_position **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop` **(** **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playback_position`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamPlayback` | :ref:`get_stream_playback`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_stream_playback`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play`\ (\ from_position\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seek`\ (\ to_position\: :ref:`float`\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_AudioStreamPlayer2D_signal_finished: -- **finished** **(** **)** +.. rst-class:: classref-signal + +**finished**\ (\ ) :ref:`🔗` Emitted when the audio stops playing. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Property Descriptions --------------------- .. _class_AudioStreamPlayer2D_property_area_mask: -- :ref:`int` **area_mask** +.. rst-class:: classref-property + +:ref:`int` **area_mask** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``1`` | -+-----------+----------------------+ -| *Setter* | set_area_mask(value) | -+-----------+----------------------+ -| *Getter* | get_area_mask() | -+-----------+----------------------+ +- |void| **set_area_mask**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_area_mask**\ (\ ) -Areas in which this sound plays. +Determines which :ref:`Area2D` layers affect the sound for reverb and audio bus effects. Areas can be used to redirect :ref:`AudioStream`\ s so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer2D_property_attenuation: -- :ref:`float` **attenuation** +.. rst-class:: classref-property + +:ref:`float` **attenuation** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_attenuation(value) | -+-----------+------------------------+ -| *Getter* | get_attenuation() | -+-----------+------------------------+ +- |void| **set_attenuation**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_attenuation**\ (\ ) -Dampens audio over distance with this as an exponent. +The volume is attenuated over distance with this as an exponent. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer2D_property_autoplay: -- :ref:`bool` **autoplay** +.. rst-class:: classref-property + +:ref:`bool` **autoplay** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------+ -| *Default* | ``false`` | -+-----------+-----------------------+ -| *Setter* | set_autoplay(value) | -+-----------+-----------------------+ -| *Getter* | is_autoplay_enabled() | -+-----------+-----------------------+ +- |void| **set_autoplay**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_autoplay_enabled**\ (\ ) If ``true``, audio plays when added to scene tree. +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer2D_property_bus: -- :ref:`StringName` **bus** +.. rst-class:: classref-property + +:ref:`StringName` **bus** = ``&"Master"`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------+ -| *Default* | ``@"Master"`` | -+-----------+----------------+ -| *Setter* | set_bus(value) | -+-----------+----------------+ -| *Getter* | get_bus() | -+-----------+----------------+ +- |void| **set_bus**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_bus**\ (\ ) Bus on which this audio is playing. +\ **Note:** When setting this property, keep in mind that no validation is performed to see if the given name matches an existing bus. This is because audio bus layouts might be loaded after this property is set. If this given name can't be resolved at runtime, it will fall back to ``"Master"``. + +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer2D_property_max_distance: -- :ref:`float` **max_distance** +.. rst-class:: classref-property + +:ref:`float` **max_distance** = ``2000.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``2000.0`` | -+-----------+-------------------------+ -| *Setter* | set_max_distance(value) | -+-----------+-------------------------+ -| *Getter* | get_max_distance() | -+-----------+-------------------------+ +- |void| **set_max_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_max_distance**\ (\ ) Maximum distance from which audio is still hearable. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer2D_property_max_polyphony: + +.. rst-class:: classref-property + +:ref:`int` **max_polyphony** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_max_polyphony**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_max_polyphony**\ (\ ) + +The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer2D_property_panning_strength: + +.. rst-class:: classref-property + +:ref:`float` **panning_strength** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_panning_strength**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_panning_strength**\ (\ ) + +Scales the panning strength for this node by multiplying the base :ref:`ProjectSettings.audio/general/2d_panning_strength` with this factor. Higher values will pan audio from left to right more dramatically than lower values. + +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer2D_property_pitch_scale: -- :ref:`float` **pitch_scale** +.. rst-class:: classref-property + +:ref:`float` **pitch_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pitch_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pitch_scale**\ (\ ) -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_pitch_scale(value) | -+-----------+------------------------+ -| *Getter* | get_pitch_scale() | -+-----------+------------------------+ +The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate. -Changes the pitch and the tempo of the audio. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer2D_property_playback_type: + +.. rst-class:: classref-property + +:ref:`PlaybackType` **playback_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playback_type**\ (\ value\: :ref:`PlaybackType`\ ) +- :ref:`PlaybackType` **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer2D_property_playing: -- :ref:`bool` **playing** +.. rst-class:: classref-property + +:ref:`bool` **playing** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_playing**\ (\ ) -+-----------+--------------+ -| *Default* | ``false`` | -+-----------+--------------+ -| *Getter* | is_playing() | -+-----------+--------------+ +If ``true``, audio is playing or is queued to be played (see :ref:`play()`). -If ``true``, audio is playing. +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer2D_property_stream: -- :ref:`AudioStream` **stream** +.. rst-class:: classref-property -+----------+-------------------+ -| *Setter* | set_stream(value) | -+----------+-------------------+ -| *Getter* | get_stream() | -+----------+-------------------+ +:ref:`AudioStream` **stream** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stream**\ (\ value\: :ref:`AudioStream`\ ) +- :ref:`AudioStream` **get_stream**\ (\ ) The :ref:`AudioStream` object to be played. +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer2D_property_stream_paused: -- :ref:`bool` **stream_paused** +.. rst-class:: classref-property + +:ref:`bool` **stream_paused** = ``false`` :ref:`🔗` -+-----------+--------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------+ -| *Setter* | set_stream_paused(value) | -+-----------+--------------------------+ -| *Getter* | get_stream_paused() | -+-----------+--------------------------+ +.. rst-class:: classref-property-setget -If ``true``, the playback is paused. You can resume it by setting ``stream_paused`` to ``false``. +- |void| **set_stream_paused**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_stream_paused**\ (\ ) + +If ``true``, the playback is paused. You can resume it by setting :ref:`stream_paused` to ``false``. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer2D_property_volume_db: -- :ref:`float` **volume_db** +.. rst-class:: classref-property + +:ref:`float` **volume_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_db**\ (\ ) + +Base volume before attenuation, in decibels. + +.. rst-class:: classref-item-separator + +---- -+-----------+----------------------+ -| *Default* | ``0.0`` | -+-----------+----------------------+ -| *Setter* | set_volume_db(value) | -+-----------+----------------------+ -| *Getter* | get_volume_db() | -+-----------+----------------------+ +.. _class_AudioStreamPlayer2D_property_volume_linear: -Base volume without dampening. +.. rst-class:: classref-property + +:ref:`float` **volume_linear** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_linear**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_linear**\ (\ ) + +Base volume before attenuation, as a linear value. + +\ **Note:** This member modifies :ref:`volume_db` for convenience. The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on :ref:`volume_db`. Setting this member is equivalent to setting :ref:`volume_db` to the result of :ref:`@GlobalScope.linear_to_db()` on a value. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AudioStreamPlayer2D_method_get_playback_position: -- :ref:`float` **get_playback_position** **(** **)** +.. rst-class:: classref-method + +:ref:`float` **get_playback_position**\ (\ ) :ref:`🔗` Returns the position in the :ref:`AudioStream`. +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer2D_method_get_stream_playback: -- :ref:`AudioStreamPlayback` **get_stream_playback** **(** **)** +.. rst-class:: classref-method + +:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) :ref:`🔗` + +Returns the :ref:`AudioStreamPlayback` object associated with this **AudioStreamPlayer2D**. -Returns the :ref:`AudioStreamPlayback` object associated with this ``AudioStreamPlayer2D``. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer2D_method_has_stream_playback: + +.. rst-class:: classref-method + +:ref:`bool` **has_stream_playback**\ (\ ) :ref:`🔗` + +Returns whether the :ref:`AudioStreamPlayer` can return the :ref:`AudioStreamPlayback` object or not. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer2D_method_play: -- void **play** **(** :ref:`float` from_position=0.0 **)** +.. rst-class:: classref-method + +|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) :ref:`🔗` + +Queues the audio to play on the next physics frame, from the given position ``from_position``, in seconds. -Plays the audio from the given position ``from_position``, in seconds. +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer2D_method_seek: -- void **seek** **(** :ref:`float` to_position **)** +.. rst-class:: classref-method + +|void| **seek**\ (\ to_position\: :ref:`float`\ ) :ref:`🔗` Sets the position from which audio will be played, in seconds. +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer2D_method_stop: -- void **stop** **(** **)** +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`🔗` Stops the audio. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplayer3d.rst b/classes/class_audiostreamplayer3d.rst index adac006cbf7..eef1a42c4fe 100644 --- a/classes/class_audiostreamplayer3d.rst +++ b/classes/class_audiostreamplayer3d.rst @@ -1,489 +1,690 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamPlayer3D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. meta:: + :keywords: sound, sfx + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamPlayer3D.xml. .. _class_AudioStreamPlayer3D: AudioStreamPlayer3D =================== -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` +**Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +Plays positional sound in 3D space. -Plays 3D sound in 3D space. +.. rst-class:: classref-introduction-group Description ----------- -Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space. +Plays audio with positional sound effects, based on the relative position of the audio listener. Positional effects include distance attenuation, directionality, and the Doppler effect. For greater realism, a low-pass filter is applied to distant sounds. This can be disabled by setting :ref:`attenuation_filter_cutoff_hz` to ``20500``. + +By default, audio is heard from the camera position. This can be changed by adding an :ref:`AudioListener3D` node to the scene and enabling it by calling :ref:`AudioListener3D.make_current()` on it. + +See also :ref:`AudioStreamPlayer` to play a sound non-positionally. + +\ **Note:** Hiding an **AudioStreamPlayer3D** node does not disable its audio output. To temporarily disable an **AudioStreamPlayer3D**'s audio output, set :ref:`volume_db` to a very low value like ``-100`` (which isn't audible to human hearing). + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/audio/audio_streams` +- :doc:`Audio streams <../tutorials/audio/audio_streams>` + +.. rst-class:: classref-reftable-group Properties ---------- -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`int` | :ref:`area_mask` | ``1`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`attenuation_filter_cutoff_hz` | ``5000.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`attenuation_filter_db` | ``-24.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`AttenuationModel` | :ref:`attenuation_model` | ``0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`autoplay` | ``false`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`StringName` | :ref:`bus` | ``@"Master"`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`DopplerTracking` | :ref:`doppler_tracking` | ``0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`emission_angle_degrees` | ``45.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`emission_angle_enabled` | ``false`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`emission_angle_filter_attenuation_db` | ``-12.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`max_db` | ``3.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`max_distance` | ``0.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`OutOfRangeMode` | :ref:`out_of_range_mode` | ``0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`pitch_scale` | ``1.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`playing` | ``false`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`AudioStream` | :ref:`stream` | | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`bool` | :ref:`stream_paused` | ``false`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`unit_db` | ``0.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`unit_size` | ``1.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ +.. table:: + :widths: auto + + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`int` | :ref:`area_mask` | ``1`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`attenuation_filter_cutoff_hz` | ``5000.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`attenuation_filter_db` | ``-24.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`AttenuationModel` | :ref:`attenuation_model` | ``0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`autoplay` | ``false`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`StringName` | :ref:`bus` | ``&"Master"`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`DopplerTracking` | :ref:`doppler_tracking` | ``0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`emission_angle_degrees` | ``45.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`emission_angle_enabled` | ``false`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`emission_angle_filter_attenuation_db` | ``-12.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`max_db` | ``3.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`max_distance` | ``0.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`int` | :ref:`max_polyphony` | ``1`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`panning_strength` | ``1.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`pitch_scale` | ``1.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`PlaybackType` | :ref:`playback_type` | ``0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`playing` | ``false`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`AudioStream` | :ref:`stream` | | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`stream_paused` | ``false`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`unit_size` | ``10.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_db` | ``0.0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_linear` | | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_playback_position` **(** **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| :ref:`AudioStreamPlayback` | :ref:`get_stream_playback` **(** **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| void | :ref:`play` **(** :ref:`float` from_position=0.0 **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| void | :ref:`seek` **(** :ref:`float` to_position **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop` **(** **)** | -+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playback_position`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamPlayback` | :ref:`get_stream_playback`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_stream_playback`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play`\ (\ from_position\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seek`\ (\ to_position\: :ref:`float`\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_AudioStreamPlayer3D_signal_finished: -- **finished** **(** **)** +.. rst-class:: classref-signal + +**finished**\ (\ ) :ref:`🔗` Emitted when the audio stops playing. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Enumerations ------------ .. _enum_AudioStreamPlayer3D_AttenuationModel: +.. rst-class:: classref-enumeration + +enum **AttenuationModel**: :ref:`🔗` + .. _class_AudioStreamPlayer3D_constant_ATTENUATION_INVERSE_DISTANCE: -.. _class_AudioStreamPlayer3D_constant_ATTENUATION_INVERSE_SQUARE_DISTANCE: +.. rst-class:: classref-enumeration-constant -.. _class_AudioStreamPlayer3D_constant_ATTENUATION_LOGARITHMIC: +:ref:`AttenuationModel` **ATTENUATION_INVERSE_DISTANCE** = ``0`` -.. _class_AudioStreamPlayer3D_constant_ATTENUATION_DISABLED: +Attenuation of loudness according to linear distance. -enum **AttenuationModel**: +.. _class_AudioStreamPlayer3D_constant_ATTENUATION_INVERSE_SQUARE_DISTANCE: -- **ATTENUATION_INVERSE_DISTANCE** = **0** --- Linear dampening of loudness according to distance. +.. rst-class:: classref-enumeration-constant -- **ATTENUATION_INVERSE_SQUARE_DISTANCE** = **1** --- Squared dampening of loudness according to distance. +:ref:`AttenuationModel` **ATTENUATION_INVERSE_SQUARE_DISTANCE** = ``1`` -- **ATTENUATION_LOGARITHMIC** = **2** --- Logarithmic dampening of loudness according to distance. +Attenuation of loudness according to squared distance. -- **ATTENUATION_DISABLED** = **3** --- No dampening of loudness according to distance. +.. _class_AudioStreamPlayer3D_constant_ATTENUATION_LOGARITHMIC: ----- +.. rst-class:: classref-enumeration-constant -.. _enum_AudioStreamPlayer3D_OutOfRangeMode: +:ref:`AttenuationModel` **ATTENUATION_LOGARITHMIC** = ``2`` -.. _class_AudioStreamPlayer3D_constant_OUT_OF_RANGE_MIX: +Attenuation of loudness according to logarithmic distance. -.. _class_AudioStreamPlayer3D_constant_OUT_OF_RANGE_PAUSE: +.. _class_AudioStreamPlayer3D_constant_ATTENUATION_DISABLED: -enum **OutOfRangeMode**: +.. rst-class:: classref-enumeration-constant -- **OUT_OF_RANGE_MIX** = **0** --- Mix this audio in, even when it's out of range. +:ref:`AttenuationModel` **ATTENUATION_DISABLED** = ``3`` -- **OUT_OF_RANGE_PAUSE** = **1** --- Pause this audio when it gets out of range. +No attenuation of loudness according to distance. The sound will still be heard positionally, unlike an :ref:`AudioStreamPlayer`. :ref:`ATTENUATION_DISABLED` can be combined with a :ref:`max_distance` value greater than ``0.0`` to achieve linear attenuation clamped to a sphere of a defined size. + +.. rst-class:: classref-item-separator ---- .. _enum_AudioStreamPlayer3D_DopplerTracking: +.. rst-class:: classref-enumeration + +enum **DopplerTracking**: :ref:`🔗` + .. _class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_DISABLED: +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_DISABLED** = ``0`` + +Disables doppler tracking. + .. _class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_IDLE_STEP: +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_IDLE_STEP** = ``1`` + +Executes doppler tracking during process frames (see :ref:`Node.NOTIFICATION_INTERNAL_PROCESS`). + .. _class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_PHYSICS_STEP: -enum **DopplerTracking**: +.. rst-class:: classref-enumeration-constant -- **DOPPLER_TRACKING_DISABLED** = **0** --- Disables doppler tracking. +:ref:`DopplerTracking` **DOPPLER_TRACKING_PHYSICS_STEP** = ``2`` -- **DOPPLER_TRACKING_IDLE_STEP** = **1** --- Executes doppler tracking in idle step. +Executes doppler tracking during physics frames (see :ref:`Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS`). -- **DOPPLER_TRACKING_PHYSICS_STEP** = **2** --- Executes doppler tracking in physics step. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_AudioStreamPlayer3D_property_area_mask: -- :ref:`int` **area_mask** +.. rst-class:: classref-property + +:ref:`int` **area_mask** = ``1`` :ref:`🔗` -+-----------+----------------------+ -| *Default* | ``1`` | -+-----------+----------------------+ -| *Setter* | set_area_mask(value) | -+-----------+----------------------+ -| *Getter* | get_area_mask() | -+-----------+----------------------+ +.. rst-class:: classref-property-setget -Areas in which this sound plays. +- |void| **set_area_mask**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_area_mask**\ (\ ) + +Determines which :ref:`Area3D` layers affect the sound for reverb and audio bus effects. Areas can be used to redirect :ref:`AudioStream`\ s so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz: -- :ref:`float` **attenuation_filter_cutoff_hz** +.. rst-class:: classref-property + +:ref:`float` **attenuation_filter_cutoff_hz** = ``5000.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_attenuation_filter_cutoff_hz**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_attenuation_filter_cutoff_hz**\ (\ ) -+-----------+-----------------------------------------+ -| *Default* | ``5000.0`` | -+-----------+-----------------------------------------+ -| *Setter* | set_attenuation_filter_cutoff_hz(value) | -+-----------+-----------------------------------------+ -| *Getter* | get_attenuation_filter_cutoff_hz() | -+-----------+-----------------------------------------+ +The cutoff frequency of the attenuation low-pass filter, in Hz. A sound above this frequency is attenuated more than a sound below this frequency. To disable this effect, set this to ``20500`` as this frequency is above the human hearing limit. -Dampens audio above this frequency, in Hz. +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_attenuation_filter_db: -- :ref:`float` **attenuation_filter_db** +.. rst-class:: classref-property -+-----------+----------------------------------+ -| *Default* | ``-24.0`` | -+-----------+----------------------------------+ -| *Setter* | set_attenuation_filter_db(value) | -+-----------+----------------------------------+ -| *Getter* | get_attenuation_filter_db() | -+-----------+----------------------------------+ +:ref:`float` **attenuation_filter_db** = ``-24.0`` :ref:`🔗` -Amount how much the filter affects the loudness, in dB. +.. rst-class:: classref-property-setget + +- |void| **set_attenuation_filter_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_attenuation_filter_db**\ (\ ) + +Amount how much the filter affects the loudness, in decibels. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_attenuation_model: -- :ref:`AttenuationModel` **attenuation_model** +.. rst-class:: classref-property + +:ref:`AttenuationModel` **attenuation_model** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------------+ -| *Default* | ``0`` | -+-----------+------------------------------+ -| *Setter* | set_attenuation_model(value) | -+-----------+------------------------------+ -| *Getter* | get_attenuation_model() | -+-----------+------------------------------+ +- |void| **set_attenuation_model**\ (\ value\: :ref:`AttenuationModel`\ ) +- :ref:`AttenuationModel` **get_attenuation_model**\ (\ ) Decides if audio should get quieter with distance linearly, quadratically, logarithmically, or not be affected by distance, effectively disabling attenuation. +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer3D_property_autoplay: -- :ref:`bool` **autoplay** +.. rst-class:: classref-property + +:ref:`bool` **autoplay** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------+ -| *Default* | ``false`` | -+-----------+-----------------------+ -| *Setter* | set_autoplay(value) | -+-----------+-----------------------+ -| *Getter* | is_autoplay_enabled() | -+-----------+-----------------------+ +- |void| **set_autoplay**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_autoplay_enabled**\ (\ ) -If ``true``, audio plays when added to scene tree. +If ``true``, audio plays when the AudioStreamPlayer3D node is added to scene tree. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_bus: -- :ref:`StringName` **bus** +.. rst-class:: classref-property + +:ref:`StringName` **bus** = ``&"Master"`` :ref:`🔗` -+-----------+----------------+ -| *Default* | ``@"Master"`` | -+-----------+----------------+ -| *Setter* | set_bus(value) | -+-----------+----------------+ -| *Getter* | get_bus() | -+-----------+----------------+ +.. rst-class:: classref-property-setget -Bus on which this audio is playing. +- |void| **set_bus**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_bus**\ (\ ) + +The bus on which this audio is playing. + +\ **Note:** When setting this property, keep in mind that no validation is performed to see if the given name matches an existing bus. This is because audio bus layouts might be loaded after this property is set. If this given name can't be resolved at runtime, it will fall back to ``"Master"``. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_doppler_tracking: -- :ref:`DopplerTracking` **doppler_tracking** +.. rst-class:: classref-property + +:ref:`DopplerTracking` **doppler_tracking** = ``0`` :ref:`🔗` -+-----------+-----------------------------+ -| *Default* | ``0`` | -+-----------+-----------------------------+ -| *Setter* | set_doppler_tracking(value) | -+-----------+-----------------------------+ -| *Getter* | get_doppler_tracking() | -+-----------+-----------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_doppler_tracking**\ (\ value\: :ref:`DopplerTracking`\ ) +- :ref:`DopplerTracking` **get_doppler_tracking**\ (\ ) Decides in which step the Doppler effect should be calculated. +\ **Note:** If :ref:`doppler_tracking` is not :ref:`DOPPLER_TRACKING_DISABLED` but the current :ref:`Camera3D`/:ref:`AudioListener3D` has doppler tracking disabled, the Doppler effect will be heard but will not take the movement of the current listener into account. If accurate Doppler effect is desired, doppler tracking should be enabled on both the **AudioStreamPlayer3D** and the current :ref:`Camera3D`/:ref:`AudioListener3D`. + +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer3D_property_emission_angle_degrees: -- :ref:`float` **emission_angle_degrees** +.. rst-class:: classref-property + +:ref:`float` **emission_angle_degrees** = ``45.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------------+ -| *Default* | ``45.0`` | -+-----------+---------------------------+ -| *Setter* | set_emission_angle(value) | -+-----------+---------------------------+ -| *Getter* | get_emission_angle() | -+-----------+---------------------------+ +- |void| **set_emission_angle**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_emission_angle**\ (\ ) -The angle in which the audio reaches cameras undampened. +The angle in which the audio reaches a listener unattenuated. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_emission_angle_enabled: -- :ref:`bool` **emission_angle_enabled** +.. rst-class:: classref-property + +:ref:`bool` **emission_angle_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_emission_angle_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_emission_angle_enabled**\ (\ ) -+-----------+-----------------------------------+ -| *Default* | ``false`` | -+-----------+-----------------------------------+ -| *Setter* | set_emission_angle_enabled(value) | -+-----------+-----------------------------------+ -| *Getter* | is_emission_angle_enabled() | -+-----------+-----------------------------------+ +If ``true``, the audio should be attenuated according to the direction of the sound. -If ``true``, the audio should be dampened according to the direction of the sound. +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_emission_angle_filter_attenuation_db: -- :ref:`float` **emission_angle_filter_attenuation_db** +.. rst-class:: classref-property -+-----------+-------------------------------------------------+ -| *Default* | ``-12.0`` | -+-----------+-------------------------------------------------+ -| *Setter* | set_emission_angle_filter_attenuation_db(value) | -+-----------+-------------------------------------------------+ -| *Getter* | get_emission_angle_filter_attenuation_db() | -+-----------+-------------------------------------------------+ +:ref:`float` **emission_angle_filter_attenuation_db** = ``-12.0`` :ref:`🔗` -Dampens audio if camera is outside of :ref:`emission_angle_degrees` and :ref:`emission_angle_enabled` is set by this factor, in dB. +.. rst-class:: classref-property-setget + +- |void| **set_emission_angle_filter_attenuation_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_emission_angle_filter_attenuation_db**\ (\ ) + +Attenuation factor used if listener is outside of :ref:`emission_angle_degrees` and :ref:`emission_angle_enabled` is set, in decibels. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_max_db: -- :ref:`float` **max_db** +.. rst-class:: classref-property + +:ref:`float` **max_db** = ``3.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------+ -| *Default* | ``3.0`` | -+-----------+-------------------+ -| *Setter* | set_max_db(value) | -+-----------+-------------------+ -| *Getter* | get_max_db() | -+-----------+-------------------+ +- |void| **set_max_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_max_db**\ (\ ) -Sets the absolute maximum of the soundlevel, in dB. +Sets the absolute maximum of the sound level, in decibels. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_max_distance: -- :ref:`float` **max_distance** +.. rst-class:: classref-property + +:ref:`float` **max_distance** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_max_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_max_distance**\ (\ ) -+-----------+-------------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------------+ -| *Setter* | set_max_distance(value) | -+-----------+-------------------------+ -| *Getter* | get_max_distance() | -+-----------+-------------------------+ +The distance past which the sound can no longer be heard at all. Only has an effect if set to a value greater than ``0.0``. :ref:`max_distance` works in tandem with :ref:`unit_size`. However, unlike :ref:`unit_size` whose behavior depends on the :ref:`attenuation_model`, :ref:`max_distance` always works in a linear fashion. This can be used to prevent the **AudioStreamPlayer3D** from requiring audio mixing when the listener is far away, which saves CPU resources. -Sets the distance from which the :ref:`out_of_range_mode` takes effect. Has no effect if set to 0. +.. rst-class:: classref-item-separator ---- -.. _class_AudioStreamPlayer3D_property_out_of_range_mode: +.. _class_AudioStreamPlayer3D_property_max_polyphony: -- :ref:`OutOfRangeMode` **out_of_range_mode** +.. rst-class:: classref-property -+-----------+------------------------------+ -| *Default* | ``0`` | -+-----------+------------------------------+ -| *Setter* | set_out_of_range_mode(value) | -+-----------+------------------------------+ -| *Getter* | get_out_of_range_mode() | -+-----------+------------------------------+ +:ref:`int` **max_polyphony** = ``1`` :ref:`🔗` -Decides if audio should pause when source is outside of :ref:`max_distance` range. +.. rst-class:: classref-property-setget + +- |void| **set_max_polyphony**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_max_polyphony**\ (\ ) + +The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer3D_property_panning_strength: + +.. rst-class:: classref-property + +:ref:`float` **panning_strength** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_panning_strength**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_panning_strength**\ (\ ) + +Scales the panning strength for this node by multiplying the base :ref:`ProjectSettings.audio/general/3d_panning_strength` by this factor. If the product is ``0.0`` then stereo panning is disabled and the volume is the same for all channels. If the product is ``1.0`` then one of the channels will be muted when the sound is located exactly to the left (or right) of the listener. + +Two speaker stereo arrangements implement the `WebAudio standard for StereoPannerNode Panning `__ where the volume is cosine of half the azimuth angle to the ear. + +For other speaker arrangements such as the 5.1 and 7.1 the SPCAP (Speaker-Placement Correction Amplitude) algorithm is implemented. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_pitch_scale: -- :ref:`float` **pitch_scale** +.. rst-class:: classref-property + +:ref:`float` **pitch_scale** = ``1.0`` :ref:`🔗` -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_pitch_scale(value) | -+-----------+------------------------+ -| *Getter* | get_pitch_scale() | -+-----------+------------------------+ +.. rst-class:: classref-property-setget -Changes the pitch and the tempo of the audio. +- |void| **set_pitch_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pitch_scale**\ (\ ) + +The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer3D_property_playback_type: + +.. rst-class:: classref-property + +:ref:`PlaybackType` **playback_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playback_type**\ (\ value\: :ref:`PlaybackType`\ ) +- :ref:`PlaybackType` **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_playing: -- :ref:`bool` **playing** +.. rst-class:: classref-property + +:ref:`bool` **playing** = ``false`` :ref:`🔗` -+-----------+--------------+ -| *Default* | ``false`` | -+-----------+--------------+ -| *Getter* | is_playing() | -+-----------+--------------+ +.. rst-class:: classref-property-setget -If ``true``, audio is playing. +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_playing**\ (\ ) + +If ``true``, audio is playing or is queued to be played (see :ref:`play()`). + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_stream: -- :ref:`AudioStream` **stream** +.. rst-class:: classref-property + +:ref:`AudioStream` **stream** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stream**\ (\ value\: :ref:`AudioStream`\ ) +- :ref:`AudioStream` **get_stream**\ (\ ) -+----------+-------------------+ -| *Setter* | set_stream(value) | -+----------+-------------------+ -| *Getter* | get_stream() | -+----------+-------------------+ +The :ref:`AudioStream` resource to be played. -The :ref:`AudioStream` object to be played. +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_property_stream_paused: -- :ref:`bool` **stream_paused** +.. rst-class:: classref-property -+-----------+--------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------+ -| *Setter* | set_stream_paused(value) | -+-----------+--------------------------+ -| *Getter* | get_stream_paused() | -+-----------+--------------------------+ +:ref:`bool` **stream_paused** = ``false`` :ref:`🔗` -If ``true``, the playback is paused. You can resume it by setting ``stream_paused`` to ``false``. +.. rst-class:: classref-property-setget + +- |void| **set_stream_paused**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_stream_paused**\ (\ ) + +If ``true``, the playback is paused. You can resume it by setting :ref:`stream_paused` to ``false``. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioStreamPlayer3D_property_unit_db: +.. _class_AudioStreamPlayer3D_property_unit_size: -- :ref:`float` **unit_db** +.. rst-class:: classref-property -+-----------+--------------------+ -| *Default* | ``0.0`` | -+-----------+--------------------+ -| *Setter* | set_unit_db(value) | -+-----------+--------------------+ -| *Getter* | get_unit_db() | -+-----------+--------------------+ +:ref:`float` **unit_size** = ``10.0`` :ref:`🔗` -Base sound level unaffected by dampening, in dB. +.. rst-class:: classref-property-setget + +- |void| **set_unit_size**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_unit_size**\ (\ ) + +The factor for the attenuation effect. Higher values make the sound audible over a larger distance. + +.. rst-class:: classref-item-separator ---- -.. _class_AudioStreamPlayer3D_property_unit_size: +.. _class_AudioStreamPlayer3D_property_volume_db: + +.. rst-class:: classref-property + +:ref:`float` **volume_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_db**\ (\ ) + +The base sound level before attenuation, in decibels. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer3D_property_volume_linear: + +.. rst-class:: classref-property + +:ref:`float` **volume_linear** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_linear**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_linear**\ (\ ) + +The base sound level before attenuation, as a linear value. -- :ref:`float` **unit_size** +\ **Note:** This member modifies :ref:`volume_db` for convenience. The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on :ref:`volume_db`. Setting this member is equivalent to setting :ref:`volume_db` to the result of :ref:`@GlobalScope.linear_to_db()` on a value. -+-----------+----------------------+ -| *Default* | ``1.0`` | -+-----------+----------------------+ -| *Setter* | set_unit_size(value) | -+-----------+----------------------+ -| *Getter* | get_unit_size() | -+-----------+----------------------+ +.. rst-class:: classref-section-separator -Factor for the attenuation effect. +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_AudioStreamPlayer3D_method_get_playback_position: -- :ref:`float` **get_playback_position** **(** **)** +.. rst-class:: classref-method + +:ref:`float` **get_playback_position**\ (\ ) :ref:`🔗` Returns the position in the :ref:`AudioStream`. +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer3D_method_get_stream_playback: -- :ref:`AudioStreamPlayback` **get_stream_playback** **(** **)** +.. rst-class:: classref-method + +:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) :ref:`🔗` + +Returns the :ref:`AudioStreamPlayback` object associated with this **AudioStreamPlayer3D**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer3D_method_has_stream_playback: + +.. rst-class:: classref-method + +:ref:`bool` **has_stream_playback**\ (\ ) :ref:`🔗` -Returns the :ref:`AudioStreamPlayback` object associated with this ``AudioStreamPlayer3D``. +Returns whether the :ref:`AudioStreamPlayer` can return the :ref:`AudioStreamPlayback` object or not. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_method_play: -- void **play** **(** :ref:`float` from_position=0.0 **)** +.. rst-class:: classref-method + +|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) :ref:`🔗` -Plays the audio from the given position ``from_position``, in seconds. +Queues the audio to play on the next physics frame, from the given position ``from_position``, in seconds. + +.. rst-class:: classref-item-separator ---- .. _class_AudioStreamPlayer3D_method_seek: -- void **seek** **(** :ref:`float` to_position **)** +.. rst-class:: classref-method + +|void| **seek**\ (\ to_position\: :ref:`float`\ ) :ref:`🔗` Sets the position from which audio will be played, in seconds. +.. rst-class:: classref-item-separator + ---- .. _class_AudioStreamPlayer3D_method_stop: -- void **stop** **(** **)** +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`🔗` Stops the audio. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaylist.rst b/classes/class_audiostreamplaylist.rst new file mode 100644 index 00000000000..35766913c82 --- /dev/null +++ b/classes/class_audiostreamplaylist.rst @@ -0,0 +1,190 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/interactive_music/doc_classes/AudioStreamPlaylist.xml. + +.. _class_AudioStreamPlaylist: + +AudioStreamPlaylist +=================== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +:ref:`AudioStream` that includes sub-streams and plays them back like a playlist. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+----------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`fade_time` | ``0.3`` | + +---------------------------+----------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`loop` | ``true`` | + +---------------------------+----------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`shuffle` | ``false`` | + +---------------------------+----------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`stream_count` | ``0`` | + +---------------------------+----------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_bpm`\ (\ ) |const| | + +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStream` | :ref:`get_list_stream`\ (\ stream_index\: :ref:`int`\ ) |const| | + +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_list_stream`\ (\ stream_index\: :ref:`int`, audio_stream\: :ref:`AudioStream`\ ) | + +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_AudioStreamPlaylist_constant_MAX_STREAMS: + +.. rst-class:: classref-constant + +**MAX_STREAMS** = ``64`` :ref:`🔗` + +Maximum amount of streams supported in the playlist. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamPlaylist_property_fade_time: + +.. rst-class:: classref-property + +:ref:`float` **fade_time** = ``0.3`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_fade_time**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_fade_time**\ (\ ) + +Fade time used when a stream ends, when going to the next one. Streams are expected to have an extra bit of audio after the end to help with fading. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_property_loop: + +.. rst-class:: classref-property + +:ref:`bool` **loop** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **has_loop**\ (\ ) + +If ``true``, the playlist will loop, otherwise the playlist will end when the last stream is finished. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_property_shuffle: + +.. rst-class:: classref-property + +:ref:`bool` **shuffle** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_shuffle**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_shuffle**\ (\ ) + +If ``true``, the playlist will shuffle each time playback starts and each time it loops. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_property_stream_count: + +.. rst-class:: classref-property + +:ref:`int` **stream_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stream_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_stream_count**\ (\ ) + +Amount of streams in the playlist. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamPlaylist_method_get_bpm: + +.. rst-class:: classref-method + +:ref:`float` **get_bpm**\ (\ ) |const| :ref:`🔗` + +Returns the BPM of the playlist, which can vary depending on the clip being played. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_method_get_list_stream: + +.. rst-class:: classref-method + +:ref:`AudioStream` **get_list_stream**\ (\ stream_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the stream at playback position index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_method_set_list_stream: + +.. rst-class:: classref-method + +|void| **set_list_stream**\ (\ stream_index\: :ref:`int`, audio_stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +Sets the stream at playback position index. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreampolyphonic.rst b/classes/class_audiostreampolyphonic.rst new file mode 100644 index 00000000000..47ff2136ae8 --- /dev/null +++ b/classes/class_audiostreampolyphonic.rst @@ -0,0 +1,68 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamPolyphonic.xml. + +.. _class_AudioStreamPolyphonic: + +AudioStreamPolyphonic +===================== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +AudioStream that lets the user play custom streams at any time from code, simultaneously using a single player. + +.. rst-class:: classref-introduction-group + +Description +----------- + +AudioStream that lets the user play custom streams at any time from code, simultaneously using a single player. + +Playback control is done via the :ref:`AudioStreamPlaybackPolyphonic` instance set inside the player, which can be obtained via :ref:`AudioStreamPlayer.get_stream_playback()`, :ref:`AudioStreamPlayer2D.get_stream_playback()` or :ref:`AudioStreamPlayer3D.get_stream_playback()` methods. Obtaining the playback instance is only valid after the ``stream`` property is set as an **AudioStreamPolyphonic** in those players. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------+------------------------------------------------------------------+--------+ + | :ref:`int` | :ref:`polyphony` | ``32`` | + +-----------------------+------------------------------------------------------------------+--------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamPolyphonic_property_polyphony: + +.. rst-class:: classref-property + +:ref:`int` **polyphony** = ``32`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_polyphony**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_polyphony**\ (\ ) + +Maximum amount of simultaneous streams that can be played. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamrandomizer.rst b/classes/class_audiostreamrandomizer.rst new file mode 100644 index 00000000000..613c7ad5c84 --- /dev/null +++ b/classes/class_audiostreamrandomizer.rst @@ -0,0 +1,298 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamRandomizer.xml. + +.. _class_AudioStreamRandomizer: + +AudioStreamRandomizer +===================== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Wraps a pool of audio streams with pitch and volume shifting. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Picks a random AudioStream from the pool, depending on the playback mode, and applies random pitch shifting and volume shifting during playback. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +--------------------------------------------------------------+----------------------------------------------------------------------------------------------+---------+ + | :ref:`PlaybackMode` | :ref:`playback_mode` | ``0`` | + +--------------------------------------------------------------+----------------------------------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`random_pitch` | ``1.0`` | + +--------------------------------------------------------------+----------------------------------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`random_pitch_semitones` | ``0.0`` | + +--------------------------------------------------------------+----------------------------------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`random_volume_offset_db` | ``0.0`` | + +--------------------------------------------------------------+----------------------------------------------------------------------------------------------+---------+ + | :ref:`int` | :ref:`streams_count` | ``0`` | + +--------------------------------------------------------------+----------------------------------------------------------------------------------------------+---------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_stream`\ (\ index\: :ref:`int`, stream\: :ref:`AudioStream`, weight\: :ref:`float` = 1.0\ ) | + +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStream` | :ref:`get_stream`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_stream_probability_weight`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`move_stream`\ (\ index_from\: :ref:`int`, index_to\: :ref:`int`\ ) | + +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_stream`\ (\ index\: :ref:`int`\ ) | + +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_stream`\ (\ index\: :ref:`int`, stream\: :ref:`AudioStream`\ ) | + +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_stream_probability_weight`\ (\ index\: :ref:`int`, weight\: :ref:`float`\ ) | + +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AudioStreamRandomizer_PlaybackMode: + +.. rst-class:: classref-enumeration + +enum **PlaybackMode**: :ref:`🔗` + +.. _class_AudioStreamRandomizer_constant_PLAYBACK_RANDOM_NO_REPEATS: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackMode` **PLAYBACK_RANDOM_NO_REPEATS** = ``0`` + +Pick a stream at random according to the probability weights chosen for each stream, but avoid playing the same stream twice in a row whenever possible. If only 1 sound is present in the pool, the same sound will always play, effectively allowing repeats to occur. + +.. _class_AudioStreamRandomizer_constant_PLAYBACK_RANDOM: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackMode` **PLAYBACK_RANDOM** = ``1`` + +Pick a stream at random according to the probability weights chosen for each stream. If only 1 sound is present in the pool, the same sound will always play. + +.. _class_AudioStreamRandomizer_constant_PLAYBACK_SEQUENTIAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackMode` **PLAYBACK_SEQUENTIAL** = ``2`` + +Play streams in the order they appear in the stream pool. If only 1 sound is present in the pool, the same sound will always play. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamRandomizer_property_playback_mode: + +.. rst-class:: classref-property + +:ref:`PlaybackMode` **playback_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playback_mode**\ (\ value\: :ref:`PlaybackMode`\ ) +- :ref:`PlaybackMode` **get_playback_mode**\ (\ ) + +Controls how this AudioStreamRandomizer picks which AudioStream to play next. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_property_random_pitch: + +.. rst-class:: classref-property + +:ref:`float` **random_pitch** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_random_pitch**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_random_pitch**\ (\ ) + +The largest possible frequency multiplier of the random pitch variation. A value of ``1.0`` means no variation. + +\ **Note:** Setting this property also sets :ref:`random_pitch_semitones`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_property_random_pitch_semitones: + +.. rst-class:: classref-property + +:ref:`float` **random_pitch_semitones** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_random_pitch_semitones**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_random_pitch_semitones**\ (\ ) + +The largest possible distance, in semitones, of the random pitch variation. A value of ``0.0`` means no variation. + +\ **Note:** Setting this property also sets :ref:`random_pitch`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_property_random_volume_offset_db: + +.. rst-class:: classref-property + +:ref:`float` **random_volume_offset_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_random_volume_offset_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_random_volume_offset_db**\ (\ ) + +The intensity of random volume variation. A value of 0 means no variation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_property_streams_count: + +.. rst-class:: classref-property + +:ref:`int` **streams_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_streams_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_streams_count**\ (\ ) + +The number of streams in the stream pool. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamRandomizer_method_add_stream: + +.. rst-class:: classref-method + +|void| **add_stream**\ (\ index\: :ref:`int`, stream\: :ref:`AudioStream`, weight\: :ref:`float` = 1.0\ ) :ref:`🔗` + +Insert a stream at the specified index. If the index is less than zero, the insertion occurs at the end of the underlying pool. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_method_get_stream: + +.. rst-class:: classref-method + +:ref:`AudioStream` **get_stream**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the stream at the specified index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_method_get_stream_probability_weight: + +.. rst-class:: classref-method + +:ref:`float` **get_stream_probability_weight**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the probability weight associated with the stream at the given index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_method_move_stream: + +.. rst-class:: classref-method + +|void| **move_stream**\ (\ index_from\: :ref:`int`, index_to\: :ref:`int`\ ) :ref:`🔗` + +Move a stream from one index to another. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_method_remove_stream: + +.. rst-class:: classref-method + +|void| **remove_stream**\ (\ index\: :ref:`int`\ ) :ref:`🔗` + +Remove the stream at the specified index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_method_set_stream: + +.. rst-class:: classref-method + +|void| **set_stream**\ (\ index\: :ref:`int`, stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +Set the AudioStream at the specified index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamRandomizer_method_set_stream_probability_weight: + +.. rst-class:: classref-method + +|void| **set_stream_probability_weight**\ (\ index\: :ref:`int`, weight\: :ref:`float`\ ) :ref:`🔗` + +Set the probability weight of the stream at the specified index. The higher this value, the more likely that the randomizer will choose this stream during random playback modes. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamrandompitch.rst b/classes/class_audiostreamrandompitch.rst deleted file mode 100644 index e3f9b913793..00000000000 --- a/classes/class_audiostreamrandompitch.rst +++ /dev/null @@ -1,60 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamRandomPitch.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_AudioStreamRandomPitch: - -AudioStreamRandomPitch -====================== - -**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` - -Plays audio with random pitch shifting. - -Description ------------ - -Randomly varies pitch on each start. - -Properties ----------- - -+---------------------------------------+-------------------------------------------------------------------------+---------+ -| :ref:`AudioStream` | :ref:`audio_stream` | | -+---------------------------------------+-------------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`random_pitch` | ``1.1`` | -+---------------------------------------+-------------------------------------------------------------------------+---------+ - -Property Descriptions ---------------------- - -.. _class_AudioStreamRandomPitch_property_audio_stream: - -- :ref:`AudioStream` **audio_stream** - -+----------+-------------------------+ -| *Setter* | set_audio_stream(value) | -+----------+-------------------------+ -| *Getter* | get_audio_stream() | -+----------+-------------------------+ - -The current :ref:`AudioStream`. - ----- - -.. _class_AudioStreamRandomPitch_property_random_pitch: - -- :ref:`float` **random_pitch** - -+-----------+-------------------------+ -| *Default* | ``1.1`` | -+-----------+-------------------------+ -| *Setter* | set_random_pitch(value) | -+-----------+-------------------------+ -| *Getter* | get_random_pitch() | -+-----------+-------------------------+ - -The intensity of random pitch variation. - diff --git a/classes/class_audiostreamsample.rst b/classes/class_audiostreamsample.rst deleted file mode 100644 index d6e00bf4243..00000000000 --- a/classes/class_audiostreamsample.rst +++ /dev/null @@ -1,215 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the AudioStreamSample.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_AudioStreamSample: - -AudioStreamSample -================= - -**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` - -Stores audio data loaded from WAV files. - -Description ------------ - -AudioStreamSample stores sound samples loaded from WAV files. To play the stored sound, use an :ref:`AudioStreamPlayer` (for non-positional audio) or :ref:`AudioStreamPlayer2D`/:ref:`AudioStreamPlayer3D` (for positional audio). The sound can be looped. - -This class can also be used to store dynamically-generated PCM audio data. - -Properties ----------- - -+--------------------------------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`PackedByteArray` | :ref:`data` | ``PackedByteArray( )`` | -+--------------------------------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`Format` | :ref:`format` | ``0`` | -+--------------------------------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`loop_begin` | ``0`` | -+--------------------------------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`loop_end` | ``0`` | -+--------------------------------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`LoopMode` | :ref:`loop_mode` | ``0`` | -+--------------------------------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`mix_rate` | ``44100`` | -+--------------------------------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`stereo` | ``false`` | -+--------------------------------------------------+----------------------------------------------------------------+-------------------------+ - -Methods -------- - -+---------------------------------------+-------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`save_to_wav` **(** :ref:`String` path **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------+ - -Enumerations ------------- - -.. _enum_AudioStreamSample_Format: - -.. _class_AudioStreamSample_constant_FORMAT_8_BITS: - -.. _class_AudioStreamSample_constant_FORMAT_16_BITS: - -.. _class_AudioStreamSample_constant_FORMAT_IMA_ADPCM: - -enum **Format**: - -- **FORMAT_8_BITS** = **0** --- 8-bit audio codec. - -- **FORMAT_16_BITS** = **1** --- 16-bit audio codec. - -- **FORMAT_IMA_ADPCM** = **2** --- Audio is compressed using IMA ADPCM. - ----- - -.. _enum_AudioStreamSample_LoopMode: - -.. _class_AudioStreamSample_constant_LOOP_DISABLED: - -.. _class_AudioStreamSample_constant_LOOP_FORWARD: - -.. _class_AudioStreamSample_constant_LOOP_PING_PONG: - -.. _class_AudioStreamSample_constant_LOOP_BACKWARD: - -enum **LoopMode**: - -- **LOOP_DISABLED** = **0** --- Audio does not loop. - -- **LOOP_FORWARD** = **1** --- Audio loops the data between :ref:`loop_begin` and :ref:`loop_end` playing forward only. - -- **LOOP_PING_PONG** = **2** --- Audio loops the data between :ref:`loop_begin` and :ref:`loop_end` playing back and forth. - -- **LOOP_BACKWARD** = **3** --- Audio loops the data between :ref:`loop_begin` and :ref:`loop_end` playing backward only. - -Property Descriptions ---------------------- - -.. _class_AudioStreamSample_property_data: - -- :ref:`PackedByteArray` **data** - -+-----------+-------------------------+ -| *Default* | ``PackedByteArray( )`` | -+-----------+-------------------------+ -| *Setter* | set_data(value) | -+-----------+-------------------------+ -| *Getter* | get_data() | -+-----------+-------------------------+ - -Contains the audio data in bytes. - -**Note:** This property expects signed PCM8 data. To convert unsigned PCM8 to signed PCM8, subtract 128 from each byte. - ----- - -.. _class_AudioStreamSample_property_format: - -- :ref:`Format` **format** - -+-----------+-------------------+ -| *Default* | ``0`` | -+-----------+-------------------+ -| *Setter* | set_format(value) | -+-----------+-------------------+ -| *Getter* | get_format() | -+-----------+-------------------+ - -Audio format. See :ref:`Format` constants for values. - ----- - -.. _class_AudioStreamSample_property_loop_begin: - -- :ref:`int` **loop_begin** - -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_loop_begin(value) | -+-----------+-----------------------+ -| *Getter* | get_loop_begin() | -+-----------+-----------------------+ - -Loop start in bytes. - ----- - -.. _class_AudioStreamSample_property_loop_end: - -- :ref:`int` **loop_end** - -+-----------+---------------------+ -| *Default* | ``0`` | -+-----------+---------------------+ -| *Setter* | set_loop_end(value) | -+-----------+---------------------+ -| *Getter* | get_loop_end() | -+-----------+---------------------+ - -Loop end in bytes. - ----- - -.. _class_AudioStreamSample_property_loop_mode: - -- :ref:`LoopMode` **loop_mode** - -+-----------+----------------------+ -| *Default* | ``0`` | -+-----------+----------------------+ -| *Setter* | set_loop_mode(value) | -+-----------+----------------------+ -| *Getter* | get_loop_mode() | -+-----------+----------------------+ - -Loop mode. See :ref:`LoopMode` constants for values. - ----- - -.. _class_AudioStreamSample_property_mix_rate: - -- :ref:`int` **mix_rate** - -+-----------+---------------------+ -| *Default* | ``44100`` | -+-----------+---------------------+ -| *Setter* | set_mix_rate(value) | -+-----------+---------------------+ -| *Getter* | get_mix_rate() | -+-----------+---------------------+ - -The sample rate for mixing this audio. - ----- - -.. _class_AudioStreamSample_property_stereo: - -- :ref:`bool` **stereo** - -+-----------+-------------------+ -| *Default* | ``false`` | -+-----------+-------------------+ -| *Setter* | set_stereo(value) | -+-----------+-------------------+ -| *Getter* | is_stereo() | -+-----------+-------------------+ - -If ``true``, audio is stereo. - -Method Descriptions -------------------- - -.. _class_AudioStreamSample_method_save_to_wav: - -- :ref:`Error` **save_to_wav** **(** :ref:`String` path **)** - -Saves the AudioStreamSample as a WAV file to ``path``. Samples with IMA ADPCM format can't be saved. - -**Note:** A ``.wav`` extension is automatically appended to ``path`` if it is missing. - diff --git a/classes/class_audiostreamsynchronized.rst b/classes/class_audiostreamsynchronized.rst new file mode 100644 index 00000000000..f23f12b9553 --- /dev/null +++ b/classes/class_audiostreamsynchronized.rst @@ -0,0 +1,154 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/modules/interactive_music/doc_classes/AudioStreamSynchronized.xml. + +.. _class_AudioStreamSynchronized: + +AudioStreamSynchronized +======================= + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Stream that can be fitted with sub-streams, which will be played in-sync. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This is a stream that can be fitted with sub-streams, which will be played in-sync. The streams begin at exactly the same time when play is pressed, and will end when the last of them ends. If one of the sub-streams loops, then playback will continue. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------+--------------------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`stream_count` | ``0`` | + +-----------------------+--------------------------------------------------------------------------+-------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStream` | :ref:`get_sync_stream`\ (\ stream_index\: :ref:`int`\ ) |const| | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_sync_stream_volume`\ (\ stream_index\: :ref:`int`\ ) |const| | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_sync_stream`\ (\ stream_index\: :ref:`int`, audio_stream\: :ref:`AudioStream`\ ) | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_sync_stream_volume`\ (\ stream_index\: :ref:`int`, volume_db\: :ref:`float`\ ) | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_AudioStreamSynchronized_constant_MAX_STREAMS: + +.. rst-class:: classref-constant + +**MAX_STREAMS** = ``32`` :ref:`🔗` + +Maximum amount of streams that can be synchronized. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamSynchronized_property_stream_count: + +.. rst-class:: classref-property + +:ref:`int` **stream_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stream_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_stream_count**\ (\ ) + +Set the total amount of streams that will be played back synchronized. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamSynchronized_method_get_sync_stream: + +.. rst-class:: classref-method + +:ref:`AudioStream` **get_sync_stream**\ (\ stream_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Get one of the synchronized streams, by index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamSynchronized_method_get_sync_stream_volume: + +.. rst-class:: classref-method + +:ref:`float` **get_sync_stream_volume**\ (\ stream_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Get the volume of one of the synchronized streams, by index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamSynchronized_method_set_sync_stream: + +.. rst-class:: classref-method + +|void| **set_sync_stream**\ (\ stream_index\: :ref:`int`, audio_stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +Set one of the synchronized streams, by index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamSynchronized_method_set_sync_stream_volume: + +.. rst-class:: classref-method + +|void| **set_sync_stream_volume**\ (\ stream_index\: :ref:`int`, volume_db\: :ref:`float`\ ) :ref:`🔗` + +Set the volume of one of the synchronized streams, by index. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamwav.rst b/classes/class_audiostreamwav.rst new file mode 100644 index 00000000000..ee54b00a1fc --- /dev/null +++ b/classes/class_audiostreamwav.rst @@ -0,0 +1,393 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamWAV.xml. + +.. _class_AudioStreamWAV: + +AudioStreamWAV +============== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Stores audio data loaded from WAV files. + +.. rst-class:: classref-introduction-group + +Description +----------- + +AudioStreamWAV stores sound samples loaded from WAV files. To play the stored sound, use an :ref:`AudioStreamPlayer` (for non-positional audio) or :ref:`AudioStreamPlayer2D`/:ref:`AudioStreamPlayer3D` (for positional audio). The sound can be looped. + +This class can also be used to store dynamically-generated PCM audio data. See also :ref:`AudioStreamGenerator` for procedural audio generation. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Runtime file loading and saving <../tutorials/io/runtime_file_loading_and_saving>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`PackedByteArray` | :ref:`data` | ``PackedByteArray()`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`Format` | :ref:`format` | ``0`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`loop_begin` | ``0`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`loop_end` | ``0`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`LoopMode` | :ref:`loop_mode` | ``0`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`mix_rate` | ``44100`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`stereo` | ``false`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`Dictionary` | :ref:`tags` | ``{}`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamWAV` | :ref:`load_from_buffer`\ (\ stream_data\: :ref:`PackedByteArray`, options\: :ref:`Dictionary` = {}\ ) |static| | + +---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamWAV` | :ref:`load_from_file`\ (\ path\: :ref:`String`, options\: :ref:`Dictionary` = {}\ ) |static| | + +---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`save_to_wav`\ (\ path\: :ref:`String`\ ) | + +---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AudioStreamWAV_Format: + +.. rst-class:: classref-enumeration + +enum **Format**: :ref:`🔗` + +.. _class_AudioStreamWAV_constant_FORMAT_8_BITS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Format` **FORMAT_8_BITS** = ``0`` + +8-bit PCM audio codec. + +.. _class_AudioStreamWAV_constant_FORMAT_16_BITS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Format` **FORMAT_16_BITS** = ``1`` + +16-bit PCM audio codec. + +.. _class_AudioStreamWAV_constant_FORMAT_IMA_ADPCM: + +.. rst-class:: classref-enumeration-constant + +:ref:`Format` **FORMAT_IMA_ADPCM** = ``2`` + +Audio is lossily compressed as IMA ADPCM. + +.. _class_AudioStreamWAV_constant_FORMAT_QOA: + +.. rst-class:: classref-enumeration-constant + +:ref:`Format` **FORMAT_QOA** = ``3`` + +Audio is lossily compressed as `Quite OK Audio `__. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioStreamWAV_LoopMode: + +.. rst-class:: classref-enumeration + +enum **LoopMode**: :ref:`🔗` + +.. _class_AudioStreamWAV_constant_LOOP_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopMode` **LOOP_DISABLED** = ``0`` + +Audio does not loop. + +.. _class_AudioStreamWAV_constant_LOOP_FORWARD: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopMode` **LOOP_FORWARD** = ``1`` + +Audio loops the data between :ref:`loop_begin` and :ref:`loop_end`, playing forward only. + +.. _class_AudioStreamWAV_constant_LOOP_PINGPONG: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopMode` **LOOP_PINGPONG** = ``2`` + +Audio loops the data between :ref:`loop_begin` and :ref:`loop_end`, playing back and forth. + +.. _class_AudioStreamWAV_constant_LOOP_BACKWARD: + +.. rst-class:: classref-enumeration-constant + +:ref:`LoopMode` **LOOP_BACKWARD** = ``3`` + +Audio loops the data between :ref:`loop_begin` and :ref:`loop_end`, playing backward only. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamWAV_property_data: + +.. rst-class:: classref-property + +:ref:`PackedByteArray` **data** = ``PackedByteArray()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_data**\ (\ value\: :ref:`PackedByteArray`\ ) +- :ref:`PackedByteArray` **get_data**\ (\ ) + +Contains the audio data in bytes. + +\ **Note:** If :ref:`format` is set to :ref:`FORMAT_8_BITS`, this property expects signed 8-bit PCM data. To convert from unsigned 8-bit PCM, subtract 128 from each byte. + +\ **Note:** If :ref:`format` is set to :ref:`FORMAT_QOA`, this property expects data from a full QOA file. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedByteArray` for more details. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_property_format: + +.. rst-class:: classref-property + +:ref:`Format` **format** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_format**\ (\ value\: :ref:`Format`\ ) +- :ref:`Format` **get_format**\ (\ ) + +Audio format. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_property_loop_begin: + +.. rst-class:: classref-property + +:ref:`int` **loop_begin** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop_begin**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_loop_begin**\ (\ ) + +The loop start point (in number of samples, relative to the beginning of the stream). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_property_loop_end: + +.. rst-class:: classref-property + +:ref:`int` **loop_end** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop_end**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_loop_end**\ (\ ) + +The loop end point (in number of samples, relative to the beginning of the stream). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_property_loop_mode: + +.. rst-class:: classref-property + +:ref:`LoopMode` **loop_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode`\ ) +- :ref:`LoopMode` **get_loop_mode**\ (\ ) + +The loop mode. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_property_mix_rate: + +.. rst-class:: classref-property + +:ref:`int` **mix_rate** = ``44100`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mix_rate**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_mix_rate**\ (\ ) + +The sample rate for mixing this audio. Higher values require more storage space, but result in better quality. + +In games, common sample rates in use are ``11025``, ``16000``, ``22050``, ``32000``, ``44100``, and ``48000``. + +According to the `Nyquist-Shannon sampling theorem `__, there is no quality difference to human hearing when going past 40,000 Hz (since most humans can only hear up to ~20,000 Hz, often less). If you are using lower-pitched sounds such as voices, lower sample rates such as ``32000`` or ``22050`` may be usable with no loss in quality. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_property_stereo: + +.. rst-class:: classref-property + +:ref:`bool` **stereo** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stereo**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_stereo**\ (\ ) + +If ``true``, audio is stereo. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_property_tags: + +.. rst-class:: classref-property + +:ref:`Dictionary` **tags** = ``{}`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_tags**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_tags**\ (\ ) + +Contains user-defined tags if found in the WAV data. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date`` (``date`` does not have a standard date format). + +\ **Note:** No tag is *guaranteed* to be present in every file, so make sure to account for the keys not always existing. + +\ **Note:** Only WAV files using a ``LIST`` chunk with an identifier of ``INFO`` to encode the tags are currently supported. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamWAV_method_load_from_buffer: + +.. rst-class:: classref-method + +:ref:`AudioStreamWAV` **load_from_buffer**\ (\ stream_data\: :ref:`PackedByteArray`, options\: :ref:`Dictionary` = {}\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamWAV** instance from the given buffer. The buffer must contain WAV data. + +The keys and values of ``options`` match the properties of :ref:`ResourceImporterWAV`. The usage of ``options`` is identical to :ref:`load_from_file()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_method_load_from_file: + +.. rst-class:: classref-method + +:ref:`AudioStreamWAV` **load_from_file**\ (\ path\: :ref:`String`, options\: :ref:`Dictionary` = {}\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamWAV** instance from the given file path. The file must be in WAV format. + +The keys and values of ``options`` match the properties of :ref:`ResourceImporterWAV`. + +\ **Example:** Load the first file dropped as a WAV and play it: + +:: + + @onready var audio_player = $AudioStreamPlayer + + func _ready(): + get_window().files_dropped.connect(_on_files_dropped) + + func _on_files_dropped(files): + if files[0].get_extension() == "wav": + audio_player.stream = AudioStreamWAV.load_from_file(files[0], { + "force/max_rate": true, + "force/max_rate_hz": 11025 + }) + audio_player.play() + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_method_save_to_wav: + +.. rst-class:: classref-method + +:ref:`Error` **save_to_wav**\ (\ path\: :ref:`String`\ ) :ref:`🔗` + +Saves the AudioStreamWAV as a WAV file to ``path``. Samples with IMA ADPCM or Quite OK Audio formats can't be saved. + +\ **Note:** A ``.wav`` extension is automatically appended to ``path`` if it is missing. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_backbuffercopy.rst b/classes/class_backbuffercopy.rst index ea9d728c5bc..79a9ef70ace 100644 --- a/classes/class_backbuffercopy.rst +++ b/classes/class_backbuffercopy.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BackBufferCopy.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BackBufferCopy.xml. .. _class_BackBufferCopy: @@ -11,71 +12,122 @@ BackBufferCopy **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Copies a region of the screen (or the whole screen) to a buffer so it can be accessed in your shader scripts through the ``texture(SCREEN_TEXTURE, ...)`` function. +A node that copies a region of the screen to a buffer for access in shader code. + +.. rst-class:: classref-introduction-group Description ----------- -Node for back-buffering the currently-displayed screen. The region defined in the BackBufferCopy node is bufferized with the content of the screen it covers, or the entire screen according to the copy mode set. Use the ``texture(SCREEN_TEXTURE, ...)`` function in your shader scripts to access the buffer. +Node for back-buffering the currently-displayed screen. The region defined in the **BackBufferCopy** node is buffered with the content of the screen it covers, or the entire screen according to the :ref:`copy_mode`. It can be accessed in shader scripts using the screen texture (i.e. a uniform sampler with ``hint_screen_texture``). + +\ **Note:** Since this node inherits from :ref:`Node2D` (and not :ref:`Control`), anchors and margins won't apply to child :ref:`Control`-derived nodes. This can be problematic when resizing the window. To avoid this, add :ref:`Control`-derived nodes as *siblings* to the **BackBufferCopy** node instead of adding them as children. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Screen-reading shaders <../tutorials/shaders/screen-reading_shaders>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------+-----------------------------------------------------------+-----------------------------------+ -| :ref:`CopyMode` | :ref:`copy_mode` | ``1`` | -+-----------------------------------------------+-----------------------------------------------------------+-----------------------------------+ -| :ref:`Rect2` | :ref:`rect` | ``Rect2( -100, -100, 200, 200 )`` | -+-----------------------------------------------+-----------------------------------------------------------+-----------------------------------+ +.. table:: + :widths: auto + + +-----------------------------------------------+-----------------------------------------------------------+---------------------------------+ + | :ref:`CopyMode` | :ref:`copy_mode` | ``1`` | + +-----------------------------------------------+-----------------------------------------------------------+---------------------------------+ + | :ref:`Rect2` | :ref:`rect` | ``Rect2(-100, -100, 200, 200)`` | + +-----------------------------------------------+-----------------------------------------------------------+---------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_BackBufferCopy_CopyMode: +.. rst-class:: classref-enumeration + +enum **CopyMode**: :ref:`🔗` + .. _class_BackBufferCopy_constant_COPY_MODE_DISABLED: +.. rst-class:: classref-enumeration-constant + +:ref:`CopyMode` **COPY_MODE_DISABLED** = ``0`` + +Disables the buffering mode. This means the **BackBufferCopy** node will directly use the portion of screen it covers. + .. _class_BackBufferCopy_constant_COPY_MODE_RECT: +.. rst-class:: classref-enumeration-constant + +:ref:`CopyMode` **COPY_MODE_RECT** = ``1`` + +**BackBufferCopy** buffers a rectangular region. + .. _class_BackBufferCopy_constant_COPY_MODE_VIEWPORT: -enum **CopyMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`CopyMode` **COPY_MODE_VIEWPORT** = ``2`` -- **COPY_MODE_DISABLED** = **0** --- Disables the buffering mode. This means the BackBufferCopy node will directly use the portion of screen it covers. +**BackBufferCopy** buffers the entire screen. -- **COPY_MODE_RECT** = **1** --- BackBufferCopy buffers a rectangular region. +.. rst-class:: classref-section-separator -- **COPY_MODE_VIEWPORT** = **2** --- BackBufferCopy buffers the entire screen. +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_BackBufferCopy_property_copy_mode: -- :ref:`CopyMode` **copy_mode** +.. rst-class:: classref-property + +:ref:`CopyMode` **copy_mode** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------+ -| *Default* | ``1`` | -+-----------+----------------------+ -| *Setter* | set_copy_mode(value) | -+-----------+----------------------+ -| *Getter* | get_copy_mode() | -+-----------+----------------------+ +- |void| **set_copy_mode**\ (\ value\: :ref:`CopyMode`\ ) +- :ref:`CopyMode` **get_copy_mode**\ (\ ) -Buffer mode. See :ref:`CopyMode` constants. +Buffer mode. + +.. rst-class:: classref-item-separator ---- .. _class_BackBufferCopy_property_rect: -- :ref:`Rect2` **rect** +.. rst-class:: classref-property + +:ref:`Rect2` **rect** = ``Rect2(-100, -100, 200, 200)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------------------+ -| *Default* | ``Rect2( -100, -100, 200, 200 )`` | -+-----------+-----------------------------------+ -| *Setter* | set_rect(value) | -+-----------+-----------------------------------+ -| *Getter* | get_rect() | -+-----------+-----------------------------------+ +- |void| **set_rect**\ (\ value\: :ref:`Rect2`\ ) +- :ref:`Rect2` **get_rect**\ (\ ) -The area covered by the BackBufferCopy. Only used if :ref:`copy_mode` is :ref:`COPY_MODE_RECT`. +The area covered by the **BackBufferCopy**. Only used if :ref:`copy_mode` is :ref:`COPY_MODE_RECT`. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_basebutton.rst b/classes/class_basebutton.rst index 3729fd81b4b..d9e40d63ac8 100644 --- a/classes/class_basebutton.rst +++ b/classes/class_basebutton.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BaseButton.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BaseButton.xml. .. _class_BaseButton: @@ -13,316 +14,463 @@ BaseButton **Inherited By:** :ref:`Button`, :ref:`LinkButton`, :ref:`TextureButton` -Base class for different kinds of buttons. +Abstract base class for GUI buttons. + +.. rst-class:: classref-introduction-group Description ----------- -BaseButton is the abstract base class for buttons, so it shouldn't be used directly (it doesn't display anything). Other types of buttons inherit from it. +**BaseButton** is an abstract base class for GUI buttons. It doesn't display anything by itself. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`ActionMode` | :ref:`action_mode` | ``1`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`int` | :ref:`button_mask` | ``1`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`bool` | :ref:`disabled` | ``false`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`FocusMode` | :ref:`enabled_focus_mode` | ``2`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`FocusMode` | focus_mode | **O:** ``2`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`ButtonGroup` | :ref:`group` | | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`bool` | :ref:`keep_pressed_outside` | ``false`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`bool` | :ref:`pressed` | ``false`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`ShortCut` | :ref:`shortcut` | | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`bool` | :ref:`shortcut_in_tooltip` | ``true`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ -| :ref:`bool` | :ref:`toggle_mode` | ``false`` | -+-----------------------------------------------+-----------------------------------------------------------------------------+--------------+ +.. table:: + :widths: auto + + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`ActionMode` | :ref:`action_mode` | ``1`` | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`ButtonGroup` | :ref:`button_group` | | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |bitfield|\[:ref:`MouseButtonMask`\] | :ref:`button_mask` | ``1`` | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`bool` | :ref:`button_pressed` | ``false`` | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`bool` | :ref:`disabled` | ``false`` | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`FocusMode` | focus_mode | ``2`` (overrides :ref:`Control`) | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`bool` | :ref:`keep_pressed_outside` | ``false`` | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`Shortcut` | :ref:`shortcut` | | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`bool` | :ref:`shortcut_feedback` | ``true`` | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`bool` | :ref:`shortcut_in_tooltip` | ``true`` | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + | :ref:`bool` | :ref:`toggle_mode` | ``false`` | + +-------------------------------------------------------------------------+-----------------------------------------------------------------------------+---------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------+ -| void | :ref:`_pressed` **(** **)** virtual | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------+ -| void | :ref:`_toggled` **(** :ref:`bool` button_pressed **)** virtual | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------+ -| :ref:`DrawMode` | :ref:`get_draw_mode` **(** **)** const | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_hovered` **(** **)** const | -+-------------------------------------------+--------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_pressed`\ (\ ) |virtual| | + +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_toggled`\ (\ toggled_on\: :ref:`bool`\ ) |virtual| | + +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + | :ref:`DrawMode` | :ref:`get_draw_mode`\ (\ ) |const| | + +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_hovered`\ (\ ) |const| | + +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_pressed_no_signal`\ (\ pressed\: :ref:`bool`\ ) | + +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_BaseButton_signal_button_down: -- **button_down** **(** **)** +.. rst-class:: classref-signal + +**button_down**\ (\ ) :ref:`🔗` Emitted when the button starts being held down. +.. rst-class:: classref-item-separator + ---- .. _class_BaseButton_signal_button_up: -- **button_up** **(** **)** +.. rst-class:: classref-signal + +**button_up**\ (\ ) :ref:`🔗` Emitted when the button stops being held down. +.. rst-class:: classref-item-separator + ---- .. _class_BaseButton_signal_pressed: -- **pressed** **(** **)** +.. rst-class:: classref-signal + +**pressed**\ (\ ) :ref:`🔗` Emitted when the button is toggled or pressed. This is on :ref:`button_down` if :ref:`action_mode` is :ref:`ACTION_MODE_BUTTON_PRESS` and on :ref:`button_up` otherwise. +If you need to know the button's pressed state (and :ref:`toggle_mode` is active), use :ref:`toggled` instead. + +.. rst-class:: classref-item-separator + ---- .. _class_BaseButton_signal_toggled: -- **toggled** **(** :ref:`bool` button_pressed **)** +.. rst-class:: classref-signal -Emitted when the button was just toggled between pressed and normal states (only if :ref:`toggle_mode` is active). The new state is contained in the ``button_pressed`` argument. +**toggled**\ (\ toggled_on\: :ref:`bool`\ ) :ref:`🔗` + +Emitted when the button was just toggled between pressed and normal states (only if :ref:`toggle_mode` is active). The new state is contained in the ``toggled_on`` argument. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_BaseButton_DrawMode: +.. rst-class:: classref-enumeration + +enum **DrawMode**: :ref:`🔗` + .. _class_BaseButton_constant_DRAW_NORMAL: +.. rst-class:: classref-enumeration-constant + +:ref:`DrawMode` **DRAW_NORMAL** = ``0`` + +The normal state (i.e. not pressed, not hovered, not toggled and enabled) of buttons. + .. _class_BaseButton_constant_DRAW_PRESSED: +.. rst-class:: classref-enumeration-constant + +:ref:`DrawMode` **DRAW_PRESSED** = ``1`` + +The state of buttons are pressed. + .. _class_BaseButton_constant_DRAW_HOVER: +.. rst-class:: classref-enumeration-constant + +:ref:`DrawMode` **DRAW_HOVER** = ``2`` + +The state of buttons are hovered. + .. _class_BaseButton_constant_DRAW_DISABLED: -.. _class_BaseButton_constant_DRAW_HOVER_PRESSED: +.. rst-class:: classref-enumeration-constant -enum **DrawMode**: +:ref:`DrawMode` **DRAW_DISABLED** = ``3`` -- **DRAW_NORMAL** = **0** --- The normal state (i.e. not pressed, not hovered, not toggled and enabled) of buttons. +The state of buttons are disabled. -- **DRAW_PRESSED** = **1** --- The state of buttons are pressed. +.. _class_BaseButton_constant_DRAW_HOVER_PRESSED: + +.. rst-class:: classref-enumeration-constant -- **DRAW_HOVER** = **2** --- The state of buttons are hovered. +:ref:`DrawMode` **DRAW_HOVER_PRESSED** = ``4`` -- **DRAW_DISABLED** = **3** --- The state of buttons are disabled. +The state of buttons are both hovered and pressed. -- **DRAW_HOVER_PRESSED** = **4** --- The state of buttons are both hovered and pressed. +.. rst-class:: classref-item-separator ---- .. _enum_BaseButton_ActionMode: +.. rst-class:: classref-enumeration + +enum **ActionMode**: :ref:`🔗` + .. _class_BaseButton_constant_ACTION_MODE_BUTTON_PRESS: +.. rst-class:: classref-enumeration-constant + +:ref:`ActionMode` **ACTION_MODE_BUTTON_PRESS** = ``0`` + +Require just a press to consider the button clicked. + .. _class_BaseButton_constant_ACTION_MODE_BUTTON_RELEASE: -enum **ActionMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`ActionMode` **ACTION_MODE_BUTTON_RELEASE** = ``1`` + +Require a press and a subsequent release before considering the button clicked. -- **ACTION_MODE_BUTTON_PRESS** = **0** --- Require just a press to consider the button clicked. +.. rst-class:: classref-section-separator -- **ACTION_MODE_BUTTON_RELEASE** = **1** --- Require a press and a subsequent release before considering the button clicked. +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_BaseButton_property_action_mode: -- :ref:`ActionMode` **action_mode** +.. rst-class:: classref-property + +:ref:`ActionMode` **action_mode** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``1`` | -+-----------+------------------------+ -| *Setter* | set_action_mode(value) | -+-----------+------------------------+ -| *Getter* | get_action_mode() | -+-----------+------------------------+ +- |void| **set_action_mode**\ (\ value\: :ref:`ActionMode`\ ) +- :ref:`ActionMode` **get_action_mode**\ (\ ) -Determines when the button is considered clicked, one of the :ref:`ActionMode` constants. +Determines when the button is considered clicked. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseButton_property_button_mask: +.. _class_BaseButton_property_button_group: -- :ref:`int` **button_mask** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``1`` | -+-----------+------------------------+ -| *Setter* | set_button_mask(value) | -+-----------+------------------------+ -| *Getter* | get_button_mask() | -+-----------+------------------------+ +:ref:`ButtonGroup` **button_group** :ref:`🔗` -Binary mask to choose which mouse buttons this button will respond to. +.. rst-class:: classref-property-setget -To allow both left-click and right-click, use ``BUTTON_MASK_LEFT | BUTTON_MASK_RIGHT``. +- |void| **set_button_group**\ (\ value\: :ref:`ButtonGroup`\ ) +- :ref:`ButtonGroup` **get_button_group**\ (\ ) + +The :ref:`ButtonGroup` associated with the button. Not to be confused with node groups. + +\ **Note:** The button will be configured as a radio button if a :ref:`ButtonGroup` is assigned to it. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseButton_property_disabled: +.. _class_BaseButton_property_button_mask: -- :ref:`bool` **disabled** +.. rst-class:: classref-property -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_disabled(value) | -+-----------+---------------------+ -| *Getter* | is_disabled() | -+-----------+---------------------+ +|bitfield|\[:ref:`MouseButtonMask`\] **button_mask** = ``1`` :ref:`🔗` -If ``true``, the button is in disabled state and can't be clicked or toggled. +.. rst-class:: classref-property-setget + +- |void| **set_button_mask**\ (\ value\: |bitfield|\[:ref:`MouseButtonMask`\]\ ) +- |bitfield|\[:ref:`MouseButtonMask`\] **get_button_mask**\ (\ ) + +Binary mask to choose which mouse buttons this button will respond to. + +To allow both left-click and right-click, use ``MOUSE_BUTTON_MASK_LEFT | MOUSE_BUTTON_MASK_RIGHT``. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseButton_property_enabled_focus_mode: +.. _class_BaseButton_property_button_pressed: + +.. rst-class:: classref-property + +:ref:`bool` **button_pressed** = ``false`` :ref:`🔗` -- :ref:`FocusMode` **enabled_focus_mode** +.. rst-class:: classref-property-setget -+-----------+-------------------------------+ -| *Default* | ``2`` | -+-----------+-------------------------------+ -| *Setter* | set_enabled_focus_mode(value) | -+-----------+-------------------------------+ -| *Getter* | get_enabled_focus_mode() | -+-----------+-------------------------------+ +- |void| **set_pressed**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_pressed**\ (\ ) -Focus access mode to use when switching between enabled/disabled (see :ref:`Control.focus_mode` and :ref:`disabled`). +If ``true``, the button's state is pressed. Means the button is pressed down or toggled (if :ref:`toggle_mode` is active). Only works if :ref:`toggle_mode` is ``true``. + +\ **Note:** Changing the value of :ref:`button_pressed` will result in :ref:`toggled` to be emitted. If you want to change the pressed state without emitting that signal, use :ref:`set_pressed_no_signal()`. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseButton_property_group: +.. _class_BaseButton_property_disabled: + +.. rst-class:: classref-property + +:ref:`bool` **disabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`ButtonGroup` **group** +- |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_disabled**\ (\ ) -+----------+-------------------------+ -| *Setter* | set_button_group(value) | -+----------+-------------------------+ -| *Getter* | get_button_group() | -+----------+-------------------------+ +If ``true``, the button is in disabled state and can't be clicked or toggled. + +\ **Note:** If the button is disabled while held down, :ref:`button_up` will be emitted. -:ref:`ButtonGroup` associated to the button. +.. rst-class:: classref-item-separator ---- .. _class_BaseButton_property_keep_pressed_outside: -- :ref:`bool` **keep_pressed_outside** +.. rst-class:: classref-property + +:ref:`bool` **keep_pressed_outside** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------------+ -| *Setter* | set_keep_pressed_outside(value) | -+-----------+---------------------------------+ -| *Getter* | is_keep_pressed_outside() | -+-----------+---------------------------------+ +- |void| **set_keep_pressed_outside**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_keep_pressed_outside**\ (\ ) If ``true``, the button stays pressed when moving the cursor outside the button while pressing it. +\ **Note:** This property only affects the button's visual appearance. Signals will be emitted at the same moment regardless of this property's value. + +.. rst-class:: classref-item-separator + ---- -.. _class_BaseButton_property_pressed: +.. _class_BaseButton_property_shortcut: -- :ref:`bool` **pressed** +.. rst-class:: classref-property -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_pressed(value) | -+-----------+--------------------+ -| *Getter* | is_pressed() | -+-----------+--------------------+ +:ref:`Shortcut` **shortcut** :ref:`🔗` -If ``true``, the button's state is pressed. Means the button is pressed down or toggled (if :ref:`toggle_mode` is active). +.. rst-class:: classref-property-setget + +- |void| **set_shortcut**\ (\ value\: :ref:`Shortcut`\ ) +- :ref:`Shortcut` **get_shortcut**\ (\ ) + +:ref:`Shortcut` associated to the button. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseButton_property_shortcut: +.. _class_BaseButton_property_shortcut_feedback: + +.. rst-class:: classref-property + +:ref:`bool` **shortcut_feedback** = ``true`` :ref:`🔗` -- :ref:`ShortCut` **shortcut** +.. rst-class:: classref-property-setget -+----------+---------------------+ -| *Setter* | set_shortcut(value) | -+----------+---------------------+ -| *Getter* | get_shortcut() | -+----------+---------------------+ +- |void| **set_shortcut_feedback**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_shortcut_feedback**\ (\ ) -:ref:`ShortCut` associated to the button. +If ``true``, the button will highlight for a short amount of time when its shortcut is activated. If ``false`` and :ref:`toggle_mode` is ``false``, the shortcut will activate without any visual feedback. + +.. rst-class:: classref-item-separator ---- .. _class_BaseButton_property_shortcut_in_tooltip: -- :ref:`bool` **shortcut_in_tooltip** +.. rst-class:: classref-property + +:ref:`bool` **shortcut_in_tooltip** = ``true`` :ref:`🔗` -+-----------+----------------------------------+ -| *Default* | ``true`` | -+-----------+----------------------------------+ -| *Setter* | set_shortcut_in_tooltip(value) | -+-----------+----------------------------------+ -| *Getter* | is_shortcut_in_tooltip_enabled() | -+-----------+----------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_shortcut_in_tooltip**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_shortcut_in_tooltip_enabled**\ (\ ) If ``true``, the button will add information about its shortcut in the tooltip. +\ **Note:** This property does nothing when the tooltip control is customized using :ref:`Control._make_custom_tooltip()`. + +.. rst-class:: classref-item-separator + ---- .. _class_BaseButton_property_toggle_mode: -- :ref:`bool` **toggle_mode** +.. rst-class:: classref-property + +:ref:`bool` **toggle_mode** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``false`` | -+-----------+------------------------+ -| *Setter* | set_toggle_mode(value) | -+-----------+------------------------+ -| *Getter* | is_toggle_mode() | -+-----------+------------------------+ +- |void| **set_toggle_mode**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_toggle_mode**\ (\ ) If ``true``, the button is in toggle mode. Makes the button flip state between pressed and unpressed each time its area is clicked. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- -.. _class_BaseButton_method__pressed: +.. _class_BaseButton_private_method__pressed: + +.. rst-class:: classref-method + +|void| **_pressed**\ (\ ) |virtual| :ref:`🔗` -- void **_pressed** **(** **)** virtual +Called when the button is pressed. If you need to know the button's pressed state (and :ref:`toggle_mode` is active), use :ref:`_toggled()` instead. -Called when the button is pressed. +.. rst-class:: classref-item-separator ---- -.. _class_BaseButton_method__toggled: +.. _class_BaseButton_private_method__toggled: -- void **_toggled** **(** :ref:`bool` button_pressed **)** virtual +.. rst-class:: classref-method + +|void| **_toggled**\ (\ toggled_on\: :ref:`bool`\ ) |virtual| :ref:`🔗` Called when the button is toggled (only if :ref:`toggle_mode` is active). +.. rst-class:: classref-item-separator + ---- .. _class_BaseButton_method_get_draw_mode: -- :ref:`DrawMode` **get_draw_mode** **(** **)** const +.. rst-class:: classref-method + +:ref:`DrawMode` **get_draw_mode**\ (\ ) |const| :ref:`🔗` Returns the visual state used to draw the button. This is useful mainly when implementing your own draw code by either overriding _draw() or connecting to "draw" signal. The visual state of the button is defined by the :ref:`DrawMode` enum. +.. rst-class:: classref-item-separator + ---- .. _class_BaseButton_method_is_hovered: -- :ref:`bool` **is_hovered** **(** **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_hovered**\ (\ ) |const| :ref:`🔗` Returns ``true`` if the mouse has entered the button and has not left it yet. +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseButton_method_set_pressed_no_signal: + +.. rst-class:: classref-method + +|void| **set_pressed_no_signal**\ (\ pressed\: :ref:`bool`\ ) :ref:`🔗` + +Changes the :ref:`button_pressed` state of the button, without emitting :ref:`toggled`. Use when you just want to change the state of the button without sending the pressed event (e.g. when initializing scene). Only works if :ref:`toggle_mode` is ``true``. + +\ **Note:** This method doesn't unpress other buttons in :ref:`button_group`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_basematerial3d.rst b/classes/class_basematerial3d.rst index 4f47e22f2a1..1a5f2b1c249 100644 --- a/classes/class_basematerial3d.rst +++ b/classes/class_basematerial3d.rst @@ -1,2326 +1,4013 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BaseMaterial3D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BaseMaterial3D.xml. .. _class_BaseMaterial3D: BaseMaterial3D ============== -**Inherits:** :ref:`Material` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Material` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` **Inherited By:** :ref:`ORMMaterial3D`, :ref:`StandardMaterial3D` -Default 3D rendering material. +Abstract base class for defining the 3D rendering properties of meshes. + +.. rst-class:: classref-introduction-group Description ----------- -This provides a default material with a wide variety of rendering features and properties without the need to write shader code. See the tutorial below for details. +This class serves as a default material with a wide variety of rendering features and properties without the need to write shader code. See the tutorial below for details. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/3d/standard_material_3d` +- :doc:`Standard Material 3D and ORM Material 3D <../tutorials/3d/standard_material_3d>` + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`albedo_color` | ``Color( 1, 1, 1, 1 )`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`albedo_tex_force_srgb` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`albedo_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`alpha_scissor_threshold` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`anisotropy` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`anisotropy_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`anisotropy_flowmap` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`ao_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`ao_light_affect` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`ao_on_uv2` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`ao_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`TextureChannel` | :ref:`ao_texture_channel` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`billboard_keep_scale` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`BillboardMode` | :ref:`billboard_mode` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`BlendMode` | :ref:`blend_mode` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`clearcoat` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`clearcoat_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`clearcoat_gloss` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`clearcoat_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`CullMode` | :ref:`cull_mode` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`DepthDrawMode` | :ref:`depth_draw_mode` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`detail_albedo` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`BlendMode` | :ref:`detail_blend_mode` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`detail_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`detail_mask` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`detail_normal` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`DetailUV` | :ref:`detail_uv_layer` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`DiffuseMode` | :ref:`diffuse_mode` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`disable_ambient_light` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`disable_receive_shadows` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`distance_fade_max_distance` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`distance_fade_min_distance` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`DistanceFadeMode` | :ref:`distance_fade_mode` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`emission` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`emission_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`emission_energy` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`emission_on_uv2` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`EmissionOperator` | :ref:`emission_operator` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`emission_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`fixed_size` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`grow` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`grow_amount` | ``0.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`heightmap_deep_parallax` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`heightmap_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`heightmap_flip_binormal` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`heightmap_flip_tangent` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`heightmap_flip_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`heightmap_max_layers` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`heightmap_min_layers` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`heightmap_scale` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`heightmap_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`metallic` | ``0.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`metallic_specular` | ``0.5`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`metallic_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`TextureChannel` | :ref:`metallic_texture_channel` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`no_depth_test` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`normal_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`normal_scale` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`normal_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`orm_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`particles_anim_h_frames` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`particles_anim_loop` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`particles_anim_v_frames` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`point_size` | ``1.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`proximity_fade_distance` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`proximity_fade_enable` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`refraction_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`refraction_scale` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`refraction_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`TextureChannel` | :ref:`refraction_texture_channel` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`rim` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`rim_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`rim_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`rim_tint` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`roughness` | ``1.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`roughness_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`TextureChannel` | :ref:`roughness_texture_channel` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`ShadingMode` | :ref:`shading_mode` | ``1`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`shadow_to_opacity` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`SpecularMode` | :ref:`specular_mode` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`subsurf_scatter_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`subsurf_scatter_strength` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`subsurf_scatter_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`TextureFilter` | :ref:`texture_filter` | ``3`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`texture_repeat` | ``true`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`transmission` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`transmission_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Texture2D` | :ref:`transmission_texture` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Transparency` | :ref:`transparency` | ``0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`use_point_size` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Vector3` | :ref:`uv1_offset` | ``Vector3( 0, 0, 0 )`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Vector3` | :ref:`uv1_scale` | ``Vector3( 1, 1, 1 )`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`uv1_triplanar` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`uv1_triplanar_sharpness` | ``1.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`uv1_world_triplanar` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Vector3` | :ref:`uv2_offset` | ``Vector3( 0, 0, 0 )`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`Vector3` | :ref:`uv2_scale` | ``Vector3( 1, 1, 1 )`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`uv2_triplanar` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`uv2_triplanar_sharpness` | ``1.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`uv2_world_triplanar` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`vertex_color_is_srgb` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`vertex_color_use_as_albedo` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`albedo_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`albedo_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`albedo_texture_force_srgb` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`albedo_texture_msdf` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`alpha_antialiasing_edge` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`AlphaAntiAliasing` | :ref:`alpha_antialiasing_mode` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`alpha_hash_scale` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`alpha_scissor_threshold` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`anisotropy` | ``0.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`anisotropy_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`anisotropy_flowmap` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`ao_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`ao_light_affect` | ``0.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`ao_on_uv2` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`ao_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`TextureChannel` | :ref:`ao_texture_channel` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`backlight` | ``Color(0, 0, 0, 1)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`backlight_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`backlight_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`bent_normal_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`bent_normal_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`billboard_keep_scale` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`BillboardMode` | :ref:`billboard_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`BlendMode` | :ref:`blend_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`clearcoat` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`clearcoat_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`clearcoat_roughness` | ``0.5`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`clearcoat_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`CullMode` | :ref:`cull_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`DepthDrawMode` | :ref:`depth_draw_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`DepthTest` | :ref:`depth_test` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`detail_albedo` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`BlendMode` | :ref:`detail_blend_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`detail_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`detail_mask` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`detail_normal` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`DetailUV` | :ref:`detail_uv_layer` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`DiffuseMode` | :ref:`diffuse_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disable_ambient_light` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disable_fog` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disable_receive_shadows` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disable_specular_occlusion` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`distance_fade_max_distance` | ``10.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`distance_fade_min_distance` | ``0.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`DistanceFadeMode` | :ref:`distance_fade_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`emission` | ``Color(0, 0, 0, 1)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`emission_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`emission_energy_multiplier` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`emission_intensity` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`emission_on_uv2` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`EmissionOperator` | :ref:`emission_operator` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`emission_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`fixed_size` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`fov_override` | ``75.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`grow` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`grow_amount` | ``0.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`heightmap_deep_parallax` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`heightmap_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`heightmap_flip_binormal` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`heightmap_flip_tangent` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`heightmap_flip_texture` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`heightmap_max_layers` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`heightmap_min_layers` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`heightmap_scale` | ``5.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`heightmap_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`metallic` | ``0.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`metallic_specular` | ``0.5`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`metallic_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`TextureChannel` | :ref:`metallic_texture_channel` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`msdf_outline_size` | ``0.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`msdf_pixel_range` | ``4.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`no_depth_test` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`normal_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`normal_scale` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`normal_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`orm_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`particles_anim_h_frames` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`particles_anim_loop` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`particles_anim_v_frames` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`point_size` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`proximity_fade_distance` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`proximity_fade_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`refraction_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`refraction_scale` | ``0.05`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`refraction_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`TextureChannel` | :ref:`refraction_texture_channel` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`rim` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`rim_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`rim_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`rim_tint` | ``0.5`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`roughness` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`roughness_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`TextureChannel` | :ref:`roughness_texture_channel` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`ShadingMode` | :ref:`shading_mode` | ``1`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`shadow_to_opacity` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`SpecularMode` | :ref:`specular_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`stencil_color` | ``Color(0, 0, 0, 1)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`StencilCompare` | :ref:`stencil_compare` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`stencil_flags` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`StencilMode` | :ref:`stencil_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`stencil_outline_thickness` | ``0.01`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`stencil_reference` | ``1`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`subsurf_scatter_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`subsurf_scatter_skin_mode` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`subsurf_scatter_strength` | ``0.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`subsurf_scatter_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`subsurf_scatter_transmittance_boost` | ``0.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`subsurf_scatter_transmittance_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`subsurf_scatter_transmittance_depth` | ``0.1`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`subsurf_scatter_transmittance_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`subsurf_scatter_transmittance_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`TextureFilter` | :ref:`texture_filter` | ``3`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`texture_repeat` | ``true`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Transparency` | :ref:`transparency` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`use_fov_override` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`use_particle_trails` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`use_point_size` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`use_z_clip_scale` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector3` | :ref:`uv1_offset` | ``Vector3(0, 0, 0)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector3` | :ref:`uv1_scale` | ``Vector3(1, 1, 1)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`uv1_triplanar` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`uv1_triplanar_sharpness` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`uv1_world_triplanar` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector3` | :ref:`uv2_offset` | ``Vector3(0, 0, 0)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Vector3` | :ref:`uv2_scale` | ``Vector3(1, 1, 1)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`uv2_triplanar` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`uv2_triplanar_sharpness` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`uv2_world_triplanar` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`vertex_color_is_srgb` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`vertex_color_use_as_albedo` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`z_clip_scale` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_feature` **(** :ref:`Feature` feature **)** const | -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_flag` **(** :ref:`Flags` flag **)** const | -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Texture2D` | :ref:`get_texture` **(** :ref:`TextureParam` param **)** const | -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_feature` **(** :ref:`Feature` feature, :ref:`bool` enable **)** | -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_flag` **(** :ref:`Flags` flag, :ref:`bool` enable **)** | -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_texture` **(** :ref:`TextureParam` param, :ref:`Texture2D` texture **)** | -+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_feature`\ (\ feature\: :ref:`Feature`\ ) |const| | + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_flag`\ (\ flag\: :ref:`Flags`\ ) |const| | + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`get_texture`\ (\ param\: :ref:`TextureParam`\ ) |const| | + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_feature`\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) | + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_flag`\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) | + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_texture`\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) | + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_BaseMaterial3D_TextureParam: +.. rst-class:: classref-enumeration + +enum **TextureParam**: :ref:`🔗` + .. _class_BaseMaterial3D_constant_TEXTURE_ALBEDO: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_ALBEDO** = ``0`` + +Texture specifying per-pixel color. + .. _class_BaseMaterial3D_constant_TEXTURE_METALLIC: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_METALLIC** = ``1`` + +Texture specifying per-pixel metallic value. + .. _class_BaseMaterial3D_constant_TEXTURE_ROUGHNESS: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_ROUGHNESS** = ``2`` + +Texture specifying per-pixel roughness value. + .. _class_BaseMaterial3D_constant_TEXTURE_EMISSION: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_EMISSION** = ``3`` + +Texture specifying per-pixel emission color. + .. _class_BaseMaterial3D_constant_TEXTURE_NORMAL: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_NORMAL** = ``4`` + +Texture specifying per-pixel normal vector. + +.. _class_BaseMaterial3D_constant_TEXTURE_BENT_NORMAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_BENT_NORMAL** = ``18`` + +Texture specifying per-pixel bent normal vector. + .. _class_BaseMaterial3D_constant_TEXTURE_RIM: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_RIM** = ``5`` + +Texture specifying per-pixel rim value. + .. _class_BaseMaterial3D_constant_TEXTURE_CLEARCOAT: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_CLEARCOAT** = ``6`` + +Texture specifying per-pixel clearcoat value. + .. _class_BaseMaterial3D_constant_TEXTURE_FLOWMAP: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_FLOWMAP** = ``7`` + +Texture specifying per-pixel flowmap direction for use with :ref:`anisotropy`. + .. _class_BaseMaterial3D_constant_TEXTURE_AMBIENT_OCCLUSION: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_AMBIENT_OCCLUSION** = ``8`` + +Texture specifying per-pixel ambient occlusion value. + .. _class_BaseMaterial3D_constant_TEXTURE_HEIGHTMAP: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_HEIGHTMAP** = ``9`` + +Texture specifying per-pixel height. + .. _class_BaseMaterial3D_constant_TEXTURE_SUBSURFACE_SCATTERING: -.. _class_BaseMaterial3D_constant_TEXTURE_TRANSMISSION: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_SUBSURFACE_SCATTERING** = ``10`` + +Texture specifying per-pixel subsurface scattering. + +.. _class_BaseMaterial3D_constant_TEXTURE_SUBSURFACE_TRANSMITTANCE: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_SUBSURFACE_TRANSMITTANCE** = ``11`` + +Texture specifying per-pixel transmittance for subsurface scattering. + +.. _class_BaseMaterial3D_constant_TEXTURE_BACKLIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_BACKLIGHT** = ``12`` + +Texture specifying per-pixel backlight color. .. _class_BaseMaterial3D_constant_TEXTURE_REFRACTION: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_REFRACTION** = ``13`` + +Texture specifying per-pixel refraction strength. + .. _class_BaseMaterial3D_constant_TEXTURE_DETAIL_MASK: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_DETAIL_MASK** = ``14`` + +Texture specifying per-pixel detail mask blending value. + .. _class_BaseMaterial3D_constant_TEXTURE_DETAIL_ALBEDO: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_DETAIL_ALBEDO** = ``15`` + +Texture specifying per-pixel detail color. + .. _class_BaseMaterial3D_constant_TEXTURE_DETAIL_NORMAL: -.. _class_BaseMaterial3D_constant_TEXTURE_ORM: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_DETAIL_NORMAL** = ``16`` + +Texture specifying per-pixel detail normal. + +.. _class_BaseMaterial3D_constant_TEXTURE_ORM: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_ORM** = ``17`` + +Texture holding ambient occlusion, roughness, and metallic. + +.. _class_BaseMaterial3D_constant_TEXTURE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_MAX** = ``19`` + +Represents the size of the :ref:`TextureParam` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_TextureFilter: + +.. rst-class:: classref-enumeration + +enum **TextureFilter**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_NEAREST** = ``0`` + +The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). + +.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_LINEAR** = ``1`` + +The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). + +.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = ``2`` + +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. + +.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = ``3`` + +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look smooth from up close, and smooth from a distance. + +.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = ``4`` + +The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. + +.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = ``5`` + +The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. + +.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_MAX** = ``6`` + +Represents the size of the :ref:`TextureFilter` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_DetailUV: + +.. rst-class:: classref-enumeration + +enum **DetailUV**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_DETAIL_UV_1: + +.. rst-class:: classref-enumeration-constant + +:ref:`DetailUV` **DETAIL_UV_1** = ``0`` + +Use ``UV`` with the detail texture. + +.. _class_BaseMaterial3D_constant_DETAIL_UV_2: + +.. rst-class:: classref-enumeration-constant + +:ref:`DetailUV` **DETAIL_UV_2** = ``1`` + +Use ``UV2`` with the detail texture. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_Transparency: + +.. rst-class:: classref-enumeration + +enum **Transparency**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_TRANSPARENCY_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`Transparency` **TRANSPARENCY_DISABLED** = ``0`` + +The material will not use transparency. This is the fastest to render. + +.. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA: + +.. rst-class:: classref-enumeration-constant + +:ref:`Transparency` **TRANSPARENCY_ALPHA** = ``1`` + +The material will use the texture's alpha values for transparency. This is the slowest to render, and disables shadow casting. + +.. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA_SCISSOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Transparency` **TRANSPARENCY_ALPHA_SCISSOR** = ``2`` + +The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. + +.. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA_HASH: + +.. rst-class:: classref-enumeration-constant + +:ref:`Transparency` **TRANSPARENCY_ALPHA_HASH** = ``3`` + +The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. Alpha hashing is suited for hair rendering. + +.. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA_DEPTH_PRE_PASS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Transparency` **TRANSPARENCY_ALPHA_DEPTH_PRE_PASS** = ``4`` + +The material will use the texture's alpha value for transparency, but will discard fragments with an alpha of less than 0.99 during the depth prepass and fragments with an alpha less than 0.1 during the shadow pass. This also supports casting shadows. + +.. _class_BaseMaterial3D_constant_TRANSPARENCY_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`Transparency` **TRANSPARENCY_MAX** = ``5`` + +Represents the size of the :ref:`Transparency` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_ShadingMode: + +.. rst-class:: classref-enumeration + +enum **ShadingMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_SHADING_MODE_UNSHADED: + +.. rst-class:: classref-enumeration-constant + +:ref:`ShadingMode` **SHADING_MODE_UNSHADED** = ``0`` + +The object will not receive shadows. This is the fastest to render, but it disables all interactions with lights. + +.. _class_BaseMaterial3D_constant_SHADING_MODE_PER_PIXEL: + +.. rst-class:: classref-enumeration-constant + +:ref:`ShadingMode` **SHADING_MODE_PER_PIXEL** = ``1`` + +The object will be shaded per pixel. Useful for realistic shading effects. + +.. _class_BaseMaterial3D_constant_SHADING_MODE_PER_VERTEX: + +.. rst-class:: classref-enumeration-constant + +:ref:`ShadingMode` **SHADING_MODE_PER_VERTEX** = ``2`` + +The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. + +.. _class_BaseMaterial3D_constant_SHADING_MODE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`ShadingMode` **SHADING_MODE_MAX** = ``3`` + +Represents the size of the :ref:`ShadingMode` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_Feature: + +.. rst-class:: classref-enumeration + +enum **Feature**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_FEATURE_EMISSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_EMISSION** = ``0`` + +Constant for setting :ref:`emission_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_NORMAL_MAPPING: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_NORMAL_MAPPING** = ``1`` + +Constant for setting :ref:`normal_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_RIM: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_RIM** = ``2`` + +Constant for setting :ref:`rim_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_CLEARCOAT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_CLEARCOAT** = ``3`` + +Constant for setting :ref:`clearcoat_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_ANISOTROPY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_ANISOTROPY** = ``4`` + +Constant for setting :ref:`anisotropy_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_AMBIENT_OCCLUSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_AMBIENT_OCCLUSION** = ``5`` + +Constant for setting :ref:`ao_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_HEIGHT_MAPPING: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_HEIGHT_MAPPING** = ``6`` + +Constant for setting :ref:`heightmap_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_SUBSURFACE_SCATTERING: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_SUBSURFACE_SCATTERING** = ``7`` + +Constant for setting :ref:`subsurf_scatter_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_SUBSURFACE_TRANSMITTANCE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_SUBSURFACE_TRANSMITTANCE** = ``8`` + +Constant for setting :ref:`subsurf_scatter_transmittance_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_BACKLIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_BACKLIGHT** = ``9`` + +Constant for setting :ref:`backlight_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_REFRACTION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_REFRACTION** = ``10`` + +Constant for setting :ref:`refraction_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_DETAIL: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_DETAIL** = ``11`` + +Constant for setting :ref:`detail_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_BENT_NORMAL_MAPPING: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_BENT_NORMAL_MAPPING** = ``12`` + +Constant for setting :ref:`bent_normal_enabled`. + +.. _class_BaseMaterial3D_constant_FEATURE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_MAX** = ``13`` + +Represents the size of the :ref:`Feature` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_BlendMode: + +.. rst-class:: classref-enumeration + +enum **BlendMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_BLEND_MODE_MIX: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_MIX** = ``0`` + +Default blend mode. The color of the object is blended over the background based on the object's alpha value. + +.. _class_BaseMaterial3D_constant_BLEND_MODE_ADD: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_ADD** = ``1`` + +The color of the object is added to the background. + +.. _class_BaseMaterial3D_constant_BLEND_MODE_SUB: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_SUB** = ``2`` + +The color of the object is subtracted from the background. + +.. _class_BaseMaterial3D_constant_BLEND_MODE_MUL: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_MUL** = ``3`` + +The color of the object is multiplied by the background. + +.. _class_BaseMaterial3D_constant_BLEND_MODE_PREMULT_ALPHA: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_PREMULT_ALPHA** = ``4`` + +The color of the object is added to the background and the alpha channel is used to mask out the background. This is effectively a hybrid of the blend mix and add modes, useful for effects like fire where you want the flame to add but the smoke to mix. By default, this works with unshaded materials using premultiplied textures. For shaded materials, use the ``PREMUL_ALPHA_FACTOR`` built-in so that lighting can be modulated as well. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_AlphaAntiAliasing: + +.. rst-class:: classref-enumeration + +enum **AlphaAntiAliasing**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_ALPHA_ANTIALIASING_OFF: + +.. rst-class:: classref-enumeration-constant + +:ref:`AlphaAntiAliasing` **ALPHA_ANTIALIASING_OFF** = ``0`` + +Disables Alpha AntiAliasing for the material. + +.. _class_BaseMaterial3D_constant_ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE: + +.. rst-class:: classref-enumeration-constant + +:ref:`AlphaAntiAliasing` **ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE** = ``1`` + +Enables AlphaToCoverage. Alpha values in the material are passed to the AntiAliasing sample mask. + +.. _class_BaseMaterial3D_constant_ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE_AND_TO_ONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`AlphaAntiAliasing` **ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE_AND_TO_ONE** = ``2`` + +Enables AlphaToCoverage and forces all non-zero alpha values to ``1``. Alpha values in the material are passed to the AntiAliasing sample mask. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_DepthDrawMode: + +.. rst-class:: classref-enumeration + +enum **DepthDrawMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_DEPTH_DRAW_OPAQUE_ONLY: + +.. rst-class:: classref-enumeration-constant + +:ref:`DepthDrawMode` **DEPTH_DRAW_OPAQUE_ONLY** = ``0`` + +Default depth draw mode. Depth is drawn only for opaque objects during the opaque prepass (if any) and during the opaque pass. + +.. _class_BaseMaterial3D_constant_DEPTH_DRAW_ALWAYS: + +.. rst-class:: classref-enumeration-constant + +:ref:`DepthDrawMode` **DEPTH_DRAW_ALWAYS** = ``1`` + +Objects will write to depth during the opaque and the transparent passes. Transparent objects that are close to the camera may obscure other transparent objects behind them. + +\ **Note:** This does not influence whether transparent objects are included in the depth prepass or not. For that, see :ref:`Transparency`. + +.. _class_BaseMaterial3D_constant_DEPTH_DRAW_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`DepthDrawMode` **DEPTH_DRAW_DISABLED** = ``2`` + +Objects will not write their depth to the depth buffer, even during the depth prepass (if enabled). + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_DepthTest: + +.. rst-class:: classref-enumeration + +enum **DepthTest**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_DEPTH_TEST_DEFAULT: + +.. rst-class:: classref-enumeration-constant + +:ref:`DepthTest` **DEPTH_TEST_DEFAULT** = ``0`` + +Depth test will discard the pixel if it is behind other pixels. + +.. _class_BaseMaterial3D_constant_DEPTH_TEST_INVERTED: + +.. rst-class:: classref-enumeration-constant + +:ref:`DepthTest` **DEPTH_TEST_INVERTED** = ``1`` + +Depth test will discard the pixel if it is in front of other pixels. Useful for stencil effects. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_CullMode: + +.. rst-class:: classref-enumeration + +enum **CullMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_CULL_BACK: + +.. rst-class:: classref-enumeration-constant + +:ref:`CullMode` **CULL_BACK** = ``0`` + +Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes, this means that only the exterior of the mesh will be visible. + +.. _class_BaseMaterial3D_constant_CULL_FRONT: + +.. rst-class:: classref-enumeration-constant + +:ref:`CullMode` **CULL_FRONT** = ``1`` + +Front face triangles will be culled when facing the camera. This results in only the back side of triangles being drawn. For closed-surface meshes, this means that the interior of the mesh will be drawn instead of the exterior. + +.. _class_BaseMaterial3D_constant_CULL_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`CullMode` **CULL_DISABLED** = ``2`` + +No face culling is performed; both the front face and back face will be visible. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_Flags: + +.. rst-class:: classref-enumeration + +enum **Flags**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_FLAG_DISABLE_DEPTH_TEST: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_DISABLE_DEPTH_TEST** = ``0`` + +Disables the depth test, so this object is drawn on top of all others drawn before it. This puts the object in the transparent draw pass where it is sorted based on distance to camera. Objects drawn after it in the draw order may cover it. This also disables writing to depth. + +.. _class_BaseMaterial3D_constant_FLAG_ALBEDO_FROM_VERTEX_COLOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_ALBEDO_FROM_VERTEX_COLOR** = ``1`` + +Set ``ALBEDO`` to the per-vertex color specified in the mesh. + +.. _class_BaseMaterial3D_constant_FLAG_SRGB_VERTEX_COLOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_SRGB_VERTEX_COLOR** = ``2`` + +Vertex colors are considered to be stored in nonlinear sRGB encoding and are converted to linear encoding during rendering. See also :ref:`vertex_color_is_srgb`. + +\ **Note:** Only effective when using the Forward+ and Mobile rendering methods. + +.. _class_BaseMaterial3D_constant_FLAG_USE_POINT_SIZE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_USE_POINT_SIZE** = ``3`` + +Uses point size to alter the size of primitive points. Also changes the albedo texture lookup to use ``POINT_COORD`` instead of ``UV``. + +.. _class_BaseMaterial3D_constant_FLAG_FIXED_SIZE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_FIXED_SIZE** = ``4`` + +Object is scaled by depth so that it always appears the same size on screen. + +.. _class_BaseMaterial3D_constant_FLAG_BILLBOARD_KEEP_SCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_BILLBOARD_KEEP_SCALE** = ``5`` + +Shader will keep the scale set for the mesh. Otherwise the scale is lost when billboarding. Only applies when :ref:`billboard_mode` is :ref:`BILLBOARD_ENABLED`. + +.. _class_BaseMaterial3D_constant_FLAG_UV1_USE_TRIPLANAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_UV1_USE_TRIPLANAR** = ``6`` + +Use triplanar texture lookup for all texture lookups that would normally use ``UV``. + +.. _class_BaseMaterial3D_constant_FLAG_UV2_USE_TRIPLANAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_UV2_USE_TRIPLANAR** = ``7`` + +Use triplanar texture lookup for all texture lookups that would normally use ``UV2``. + +.. _class_BaseMaterial3D_constant_FLAG_UV1_USE_WORLD_TRIPLANAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_UV1_USE_WORLD_TRIPLANAR** = ``8`` + +Use triplanar texture lookup for all texture lookups that would normally use ``UV``. + +.. _class_BaseMaterial3D_constant_FLAG_UV2_USE_WORLD_TRIPLANAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_UV2_USE_WORLD_TRIPLANAR** = ``9`` + +Use triplanar texture lookup for all texture lookups that would normally use ``UV2``. + +.. _class_BaseMaterial3D_constant_FLAG_AO_ON_UV2: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_AO_ON_UV2** = ``10`` + +Use ``UV2`` coordinates to look up from the :ref:`ao_texture`. + +.. _class_BaseMaterial3D_constant_FLAG_EMISSION_ON_UV2: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_EMISSION_ON_UV2** = ``11`` + +Use ``UV2`` coordinates to look up from the :ref:`emission_texture`. + +.. _class_BaseMaterial3D_constant_FLAG_ALBEDO_TEXTURE_FORCE_SRGB: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_ALBEDO_TEXTURE_FORCE_SRGB** = ``12`` + +Forces the shader to convert albedo from nonlinear sRGB encoding to linear encoding. See also :ref:`albedo_texture_force_srgb`. + +.. _class_BaseMaterial3D_constant_FLAG_DONT_RECEIVE_SHADOWS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_DONT_RECEIVE_SHADOWS** = ``13`` + +Disables receiving shadows from other objects. + +.. _class_BaseMaterial3D_constant_FLAG_DISABLE_AMBIENT_LIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_DISABLE_AMBIENT_LIGHT** = ``14`` + +Disables receiving ambient light. + +.. _class_BaseMaterial3D_constant_FLAG_USE_SHADOW_TO_OPACITY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_USE_SHADOW_TO_OPACITY** = ``15`` + +Enables the shadow to opacity feature. + +.. _class_BaseMaterial3D_constant_FLAG_USE_TEXTURE_REPEAT: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_USE_TEXTURE_REPEAT** = ``16`` + +Enables the texture to repeat when UV coordinates are outside the 0-1 range. If using one of the linear filtering modes, this can result in artifacts at the edges of a texture when the sampler filters across the edges of the texture. + +.. _class_BaseMaterial3D_constant_FLAG_INVERT_HEIGHTMAP: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_INVERT_HEIGHTMAP** = ``17`` + +Invert values read from a depth texture to convert them to height values (heightmap). + +.. _class_BaseMaterial3D_constant_FLAG_SUBSURFACE_MODE_SKIN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_SUBSURFACE_MODE_SKIN** = ``18`` + +Enables the skin mode for subsurface scattering which is used to improve the look of subsurface scattering when used for human skin. + +.. _class_BaseMaterial3D_constant_FLAG_PARTICLE_TRAILS_MODE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_PARTICLE_TRAILS_MODE** = ``19`` + +Enables parts of the shader required for :ref:`GPUParticles3D` trails to function. This also requires using a mesh with appropriate skinning, such as :ref:`RibbonTrailMesh` or :ref:`TubeTrailMesh`. Enabling this feature outside of materials used in :ref:`GPUParticles3D` meshes will break material rendering. + +.. _class_BaseMaterial3D_constant_FLAG_ALBEDO_TEXTURE_MSDF: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_ALBEDO_TEXTURE_MSDF** = ``20`` + +Enables multichannel signed distance field rendering shader. + +.. _class_BaseMaterial3D_constant_FLAG_DISABLE_FOG: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_DISABLE_FOG** = ``21`` + +Disables receiving depth-based or volumetric fog. + +.. _class_BaseMaterial3D_constant_FLAG_DISABLE_SPECULAR_OCCLUSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_DISABLE_SPECULAR_OCCLUSION** = ``22`` + +Disables specular occlusion. + +.. _class_BaseMaterial3D_constant_FLAG_USE_Z_CLIP_SCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_USE_Z_CLIP_SCALE** = ``23`` + +Enables using :ref:`z_clip_scale`. + +.. _class_BaseMaterial3D_constant_FLAG_USE_FOV_OVERRIDE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_USE_FOV_OVERRIDE** = ``24`` + +Enables using :ref:`fov_override`. + +.. _class_BaseMaterial3D_constant_FLAG_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_MAX** = ``25`` + +Represents the size of the :ref:`Flags` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_DiffuseMode: + +.. rst-class:: classref-enumeration + +enum **DiffuseMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_DIFFUSE_BURLEY: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiffuseMode` **DIFFUSE_BURLEY** = ``0`` + +Default diffuse scattering algorithm. + +.. _class_BaseMaterial3D_constant_DIFFUSE_LAMBERT: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiffuseMode` **DIFFUSE_LAMBERT** = ``1`` + +Diffuse scattering ignores roughness. + +.. _class_BaseMaterial3D_constant_DIFFUSE_LAMBERT_WRAP: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiffuseMode` **DIFFUSE_LAMBERT_WRAP** = ``2`` + +Extends Lambert to cover more than 90 degrees when roughness increases. + +.. _class_BaseMaterial3D_constant_DIFFUSE_TOON: + +.. rst-class:: classref-enumeration-constant + +:ref:`DiffuseMode` **DIFFUSE_TOON** = ``3`` + +Uses a hard cut for lighting, with smoothing affected by roughness. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_SpecularMode: + +.. rst-class:: classref-enumeration + +enum **SpecularMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_SPECULAR_SCHLICK_GGX: + +.. rst-class:: classref-enumeration-constant + +:ref:`SpecularMode` **SPECULAR_SCHLICK_GGX** = ``0`` + +Default specular blob. + +\ **Note:** Forward+ uses multiscattering for more accurate reflections, although the impact of multiscattering is more noticeable on rough metallic surfaces than on smooth, non-metallic surfaces. + +\ **Note:** Mobile and Compatibility don't perform multiscattering for performance reasons. Instead, they perform single scattering, which means rough metallic surfaces may look slightly darker than intended. + +.. _class_BaseMaterial3D_constant_SPECULAR_TOON: + +.. rst-class:: classref-enumeration-constant + +:ref:`SpecularMode` **SPECULAR_TOON** = ``1`` + +Toon blob which changes size based on roughness. + +.. _class_BaseMaterial3D_constant_SPECULAR_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`SpecularMode` **SPECULAR_DISABLED** = ``2`` + +No specular blob. This is slightly faster to render than other specular modes. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_BillboardMode: + +.. rst-class:: classref-enumeration + +enum **BillboardMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_BILLBOARD_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`BillboardMode` **BILLBOARD_DISABLED** = ``0`` + +Billboard mode is disabled. + +.. _class_BaseMaterial3D_constant_BILLBOARD_ENABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`BillboardMode` **BILLBOARD_ENABLED** = ``1`` + +The object's Z axis will always face the camera. + +.. _class_BaseMaterial3D_constant_BILLBOARD_FIXED_Y: + +.. rst-class:: classref-enumeration-constant + +:ref:`BillboardMode` **BILLBOARD_FIXED_Y** = ``2`` + +The object's X axis will always face the camera. + +.. _class_BaseMaterial3D_constant_BILLBOARD_PARTICLES: + +.. rst-class:: classref-enumeration-constant + +:ref:`BillboardMode` **BILLBOARD_PARTICLES** = ``3`` + +Used for particle systems when assigned to :ref:`GPUParticles3D` and :ref:`CPUParticles3D` nodes (flipbook animation). Enables ``particles_anim_*`` properties. + +The :ref:`ParticleProcessMaterial.anim_speed_min` or :ref:`CPUParticles3D.anim_speed_min` should also be set to a value bigger than zero for the animation to play. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_TextureChannel: + +.. rst-class:: classref-enumeration + +enum **TextureChannel**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_RED: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureChannel` **TEXTURE_CHANNEL_RED** = ``0`` + +Used to read from the red channel of a texture. + +.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_GREEN: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureChannel` **TEXTURE_CHANNEL_GREEN** = ``1`` + +Used to read from the green channel of a texture. + +.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_BLUE: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureChannel` **TEXTURE_CHANNEL_BLUE** = ``2`` + +Used to read from the blue channel of a texture. + +.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_ALPHA: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureChannel` **TEXTURE_CHANNEL_ALPHA** = ``3`` + +Used to read from the alpha channel of a texture. + +.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_GRAYSCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureChannel` **TEXTURE_CHANNEL_GRAYSCALE** = ``4`` + +Used to read from the linear (non-perceptual) average of the red, green and blue channels of a texture. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_EmissionOperator: + +.. rst-class:: classref-enumeration + +enum **EmissionOperator**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_EMISSION_OP_ADD: + +.. rst-class:: classref-enumeration-constant + +:ref:`EmissionOperator` **EMISSION_OP_ADD** = ``0`` + +Adds the emission color to the color from the emission texture. + +.. _class_BaseMaterial3D_constant_EMISSION_OP_MULTIPLY: + +.. rst-class:: classref-enumeration-constant + +:ref:`EmissionOperator` **EMISSION_OP_MULTIPLY** = ``1`` + +Multiplies the emission color by the color from the emission texture. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_DistanceFadeMode: + +.. rst-class:: classref-enumeration + +enum **DistanceFadeMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_DISTANCE_FADE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`DistanceFadeMode` **DISTANCE_FADE_DISABLED** = ``0`` + +Do not use distance fade. + +.. _class_BaseMaterial3D_constant_DISTANCE_FADE_PIXEL_ALPHA: + +.. rst-class:: classref-enumeration-constant + +:ref:`DistanceFadeMode` **DISTANCE_FADE_PIXEL_ALPHA** = ``1`` + +Smoothly fades the object out based on each pixel's distance from the camera using the alpha channel. + +.. _class_BaseMaterial3D_constant_DISTANCE_FADE_PIXEL_DITHER: + +.. rst-class:: classref-enumeration-constant + +:ref:`DistanceFadeMode` **DISTANCE_FADE_PIXEL_DITHER** = ``2`` + +Smoothly fades the object out based on each pixel's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA`. + +.. _class_BaseMaterial3D_constant_DISTANCE_FADE_OBJECT_DITHER: + +.. rst-class:: classref-enumeration-constant + +:ref:`DistanceFadeMode` **DISTANCE_FADE_OBJECT_DITHER** = ``3`` + +Smoothly fades the object out based on the object's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA` and :ref:`DISTANCE_FADE_PIXEL_DITHER`. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_StencilMode: + +.. rst-class:: classref-enumeration + +enum **StencilMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_STENCIL_MODE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilMode` **STENCIL_MODE_DISABLED** = ``0`` + +Disables stencil operations. + +.. _class_BaseMaterial3D_constant_STENCIL_MODE_OUTLINE: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilMode` **STENCIL_MODE_OUTLINE** = ``1`` + +Stencil preset which applies an outline to the object. + +\ **Note:** Requires a :ref:`Material.next_pass` material which will be automatically applied. Any manual changes made to :ref:`Material.next_pass` will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a :ref:`Material.next_pass` material on a material that uses stencil presets, use :ref:`GeometryInstance3D.material_overlay` instead. + +.. _class_BaseMaterial3D_constant_STENCIL_MODE_XRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilMode` **STENCIL_MODE_XRAY** = ``2`` + +Stencil preset which shows a silhouette of the object behind walls. + +\ **Note:** Requires a :ref:`Material.next_pass` material which will be automatically applied. Any manual changes made to :ref:`Material.next_pass` will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a :ref:`Material.next_pass` material on a material that uses stencil presets, use :ref:`GeometryInstance3D.material_overlay` instead. + +.. _class_BaseMaterial3D_constant_STENCIL_MODE_CUSTOM: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilMode` **STENCIL_MODE_CUSTOM** = ``3`` + +Enables stencil operations without a preset. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_StencilFlags: + +.. rst-class:: classref-enumeration + +enum **StencilFlags**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_STENCIL_FLAG_READ: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilFlags` **STENCIL_FLAG_READ** = ``1`` + +The material will only be rendered where it passes a stencil comparison with existing stencil buffer values. See :ref:`StencilCompare`. + +.. _class_BaseMaterial3D_constant_STENCIL_FLAG_WRITE: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilFlags` **STENCIL_FLAG_WRITE** = ``2`` + +The material will write the reference value to the stencil buffer where it passes the depth test. + +.. _class_BaseMaterial3D_constant_STENCIL_FLAG_WRITE_DEPTH_FAIL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilFlags` **STENCIL_FLAG_WRITE_DEPTH_FAIL** = ``4`` + +The material will write the reference value to the stencil buffer where it fails the depth test. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_StencilCompare: + +.. rst-class:: classref-enumeration + +enum **StencilCompare**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_ALWAYS: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_ALWAYS** = ``0`` + +Always passes the stencil test. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_LESS: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_LESS** = ``1`` + +Passes the stencil test when the reference value is less than the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_EQUAL** = ``2`` + +Passes the stencil test when the reference value is equal to the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_LESS_OR_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_LESS_OR_EQUAL** = ``3`` + +Passes the stencil test when the reference value is less than or equal to the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_GREATER: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_GREATER** = ``4`` + +Passes the stencil test when the reference value is greater than the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_NOT_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_NOT_EQUAL** = ``5`` + +Passes the stencil test when the reference value is not equal to the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_GREATER_OR_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_GREATER_OR_EQUAL** = ``6`` + +Passes the stencil test when the reference value is greater than or equal to the existing stencil value. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_BaseMaterial3D_property_albedo_color: + +.. rst-class:: classref-property + +:ref:`Color` **albedo_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_albedo**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_albedo**\ (\ ) + +The material's base color. + +\ **Note:** If :ref:`detail_enabled` is ``true`` and a :ref:`detail_albedo` texture is specified, :ref:`albedo_color` will *not* modulate the detail texture. This can be used to color partial areas of a material by not specifying an albedo texture and using a transparent :ref:`detail_albedo` texture instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_albedo_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **albedo_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture to multiply by :ref:`albedo_color`. Used for basic texturing of objects. + +If the texture appears unexpectedly too dark or too bright, check :ref:`albedo_texture_force_srgb`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_albedo_texture_force_srgb: + +.. rst-class:: classref-property + +:ref:`bool` **albedo_texture_force_srgb** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +If ``true``, forces a conversion of the :ref:`albedo_texture` from nonlinear sRGB encoding to linear encoding. See also :ref:`vertex_color_is_srgb`. + +This should only be enabled when needed (typically when using a :ref:`ViewportTexture` as :ref:`albedo_texture`). If :ref:`albedo_texture_force_srgb` is ``true`` when it shouldn't be, the texture will appear to be too dark. If :ref:`albedo_texture_force_srgb` is ``false`` when it shouldn't be, the texture will appear to be too bright. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_albedo_texture_msdf: + +.. rst-class:: classref-property + +:ref:`bool` **albedo_texture_msdf** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +Enables multichannel signed distance field rendering shader. Use :ref:`msdf_pixel_range` and :ref:`msdf_outline_size` to configure MSDF parameters. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_alpha_antialiasing_edge: + +.. rst-class:: classref-property + +:ref:`float` **alpha_antialiasing_edge** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_alpha_antialiasing_edge**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_alpha_antialiasing_edge**\ (\ ) + +Threshold at which antialiasing will be applied on the alpha channel. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_alpha_antialiasing_mode: + +.. rst-class:: classref-property + +:ref:`AlphaAntiAliasing` **alpha_antialiasing_mode** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_alpha_antialiasing**\ (\ value\: :ref:`AlphaAntiAliasing`\ ) +- :ref:`AlphaAntiAliasing` **get_alpha_antialiasing**\ (\ ) + +The type of alpha antialiasing to apply. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_alpha_hash_scale: + +.. rst-class:: classref-property + +:ref:`float` **alpha_hash_scale** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_alpha_hash_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_alpha_hash_scale**\ (\ ) + +The hashing scale for Alpha Hash. Recommended values between ``0`` and ``2``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_alpha_scissor_threshold: + +.. rst-class:: classref-property + +:ref:`float` **alpha_scissor_threshold** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_alpha_scissor_threshold**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_alpha_scissor_threshold**\ (\ ) + +Threshold at which the alpha scissor will discard values. Higher values will result in more pixels being discarded. If the material becomes too opaque at a distance, try increasing :ref:`alpha_scissor_threshold`. If the material disappears at a distance, try decreasing :ref:`alpha_scissor_threshold`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_anisotropy: + +.. rst-class:: classref-property + +:ref:`float` **anisotropy** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_anisotropy**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_anisotropy**\ (\ ) + +The strength of the anisotropy effect. This is multiplied by :ref:`anisotropy_flowmap`'s alpha channel if a texture is defined there and the texture contains an alpha channel. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_anisotropy_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **anisotropy_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| + +If ``true``, anisotropy is enabled. Anisotropy changes the shape of the specular blob and aligns it to tangent space. This is useful for brushed aluminum and hair reflections. + +\ **Note:** Mesh tangents are needed for anisotropy to work. If the mesh does not contain tangents, the anisotropy effect will appear broken. + +\ **Note:** Material anisotropy should not to be confused with anisotropic texture filtering, which can be enabled by setting :ref:`texture_filter` to :ref:`TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_anisotropy_flowmap: + +.. rst-class:: classref-property + +:ref:`Texture2D` **anisotropy_flowmap** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture that offsets the tangent map for anisotropy calculations and optionally controls the anisotropy effect (if an alpha channel is present). The flowmap texture is expected to be a derivative map, with the red channel representing distortion on the X axis and green channel representing distortion on the Y axis. Values below 0.5 will result in negative distortion, whereas values above 0.5 will result in positive distortion. + +If present, the texture's alpha channel will be used to multiply the strength of the :ref:`anisotropy` effect. Fully opaque pixels will keep the anisotropy effect's original strength while fully transparent pixels will disable the anisotropy effect entirely. The flowmap texture's blue channel is ignored. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_ao_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **ao_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| + +If ``true``, ambient occlusion is enabled. Ambient occlusion darkens areas based on the :ref:`ao_texture`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_ao_light_affect: + +.. rst-class:: classref-property + +:ref:`float` **ao_light_affect** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_ao_light_affect**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_ao_light_affect**\ (\ ) + +Amount that ambient occlusion affects lighting from lights. If ``0``, ambient occlusion only affects ambient light. If ``1``, ambient occlusion affects lights just as much as it affects ambient light. This can be used to impact the strength of the ambient occlusion effect, but typically looks unrealistic. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_ao_on_uv2: + +.. rst-class:: classref-property + +:ref:`bool` **ao_on_uv2** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +If ``true``, use ``UV2`` coordinates to look up from the :ref:`ao_texture`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_ao_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **ao_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture that defines the amount of ambient occlusion for a given point on the object. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_ao_texture_channel: + +.. rst-class:: classref-property + +:ref:`TextureChannel` **ao_texture_channel** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_ao_texture_channel**\ (\ value\: :ref:`TextureChannel`\ ) +- :ref:`TextureChannel` **get_ao_texture_channel**\ (\ ) + +Specifies the channel of the :ref:`ao_texture` in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_backlight: + +.. rst-class:: classref-property + +:ref:`Color` **backlight** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_backlight**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_backlight**\ (\ ) + +The color used by the backlight effect. Represents the light passing through an object. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_backlight_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **backlight_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| + +If ``true``, the backlight effect is enabled. See also :ref:`subsurf_scatter_transmittance_enabled`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_backlight_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **backlight_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture used to control the backlight effect per-pixel. Added to :ref:`backlight`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_bent_normal_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **bent_normal_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| + +If ``true``, the bent normal map is enabled. This allows for more accurate indirect lighting and specular occlusion. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_bent_normal_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **bent_normal_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture that specifies the average direction of incoming ambient light at a given pixel. The :ref:`bent_normal_texture` only uses the red and green channels; the blue and alpha channels are ignored. The normal read from :ref:`bent_normal_texture` is oriented around the surface normal provided by the :ref:`Mesh`. + +\ **Note:** A bent normal map is different from a regular normal map. When baking a bent normal map make sure to use **a cosine distribution** for the bent normal map to work correctly. + +\ **Note:** The mesh must have both normals and tangents defined in its vertex data. Otherwise, the shading produced by the bent normal map will not look correct. If creating geometry with :ref:`SurfaceTool`, you can use :ref:`SurfaceTool.generate_normals()` and :ref:`SurfaceTool.generate_tangents()` to automatically generate normals and tangents respectively. + +\ **Note:** Godot expects the bent normal map to use X+, Y+, and Z+ coordinates. See `this page `__ for a comparison of normal map coordinates expected by popular engines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_billboard_keep_scale: + +.. rst-class:: classref-property + +:ref:`bool` **billboard_keep_scale** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +If ``true``, the shader will keep the scale set for the mesh. Otherwise, the scale is lost when billboarding. Only applies when :ref:`billboard_mode` is not :ref:`BILLBOARD_DISABLED`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_billboard_mode: + +.. rst-class:: classref-property + +:ref:`BillboardMode` **billboard_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_billboard_mode**\ (\ value\: :ref:`BillboardMode`\ ) +- :ref:`BillboardMode` **get_billboard_mode**\ (\ ) + +Controls how the object faces the camera. + +\ **Note:** Billboard mode is not suitable for VR because the left-right vector of the camera is not horizontal when the screen is attached to your head instead of on the table. See `GitHub issue #41567 `__ for details. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_blend_mode: + +.. rst-class:: classref-property + +:ref:`BlendMode` **blend_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_blend_mode**\ (\ value\: :ref:`BlendMode`\ ) +- :ref:`BlendMode` **get_blend_mode**\ (\ ) + +The material's blend mode. + +\ **Note:** Values other than ``Mix`` force the object into the transparent pipeline. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_clearcoat: + +.. rst-class:: classref-property + +:ref:`float` **clearcoat** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_clearcoat**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_clearcoat**\ (\ ) + +Sets the strength of the clearcoat effect. Setting to ``0`` looks the same as disabling the clearcoat effect. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_clearcoat_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **clearcoat_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| + +If ``true``, clearcoat rendering is enabled. Adds a secondary transparent pass to the lighting calculation resulting in an added specular blob. This makes materials appear as if they have a clear layer on them that can be either glossy or rough. + +\ **Note:** Clearcoat rendering is not visible if the material's :ref:`shading_mode` is :ref:`SHADING_MODE_UNSHADED`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_clearcoat_roughness: + +.. rst-class:: classref-property + +:ref:`float` **clearcoat_roughness** = ``0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_clearcoat_roughness**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_clearcoat_roughness**\ (\ ) + +Sets the roughness of the clearcoat pass. A higher value results in a rougher clearcoat while a lower value results in a smoother clearcoat. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_clearcoat_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **clearcoat_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture that defines the strength of the clearcoat effect and the glossiness of the clearcoat. Strength is specified in the red channel while glossiness is specified in the green channel. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_cull_mode: + +.. rst-class:: classref-property + +:ref:`CullMode` **cull_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_cull_mode**\ (\ value\: :ref:`CullMode`\ ) +- :ref:`CullMode` **get_cull_mode**\ (\ ) + +Determines which side of the triangle to cull depending on whether the triangle faces towards or away from the camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_depth_draw_mode: + +.. rst-class:: classref-property + +:ref:`DepthDrawMode` **depth_draw_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_depth_draw_mode**\ (\ value\: :ref:`DepthDrawMode`\ ) +- :ref:`DepthDrawMode` **get_depth_draw_mode**\ (\ ) + +Determines when depth rendering takes place. See also :ref:`transparency`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_depth_test: + +.. rst-class:: classref-property + +:ref:`DepthTest` **depth_test** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_depth_test**\ (\ value\: :ref:`DepthTest`\ ) +- :ref:`DepthTest` **get_depth_test**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +Determines which comparison operator is used when testing depth. See :ref:`DepthTest`. + +\ **Note:** Changing :ref:`depth_test` to a non-default value only has a visible effect when used on a transparent material, or a material that has :ref:`depth_draw_mode` set to :ref:`DEPTH_DRAW_DISABLED`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_detail_albedo: + +.. rst-class:: classref-property + +:ref:`Texture2D` **detail_albedo** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture that specifies the color of the detail overlay. :ref:`detail_albedo`'s alpha channel is used as a mask, even when the material is opaque. To use a dedicated texture as a mask, see :ref:`detail_mask`. + +\ **Note:** :ref:`detail_albedo` is *not* modulated by :ref:`albedo_color`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_detail_blend_mode: + +.. rst-class:: classref-property + +:ref:`BlendMode` **detail_blend_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_detail_blend_mode**\ (\ value\: :ref:`BlendMode`\ ) +- :ref:`BlendMode` **get_detail_blend_mode**\ (\ ) + +Specifies how the :ref:`detail_albedo` should blend with the current ``ALBEDO``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_detail_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **detail_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| + +If ``true``, enables the detail overlay. Detail is a second texture that gets mixed over the surface of the object based on :ref:`detail_mask` and :ref:`detail_albedo`'s alpha channel. This can be used to add variation to objects, or to blend between two different albedo/normal textures. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_detail_mask: + +.. rst-class:: classref-property + +:ref:`Texture2D` **detail_mask** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture used to specify how the detail textures get blended with the base textures. :ref:`detail_mask` can be used together with :ref:`detail_albedo`'s alpha channel (if any). + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_detail_normal: + +.. rst-class:: classref-property + +:ref:`Texture2D` **detail_normal** :ref:`🔗` + +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_TEXTURE_MAX: +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -enum **TextureParam**: +Texture that specifies the per-pixel normal of the detail overlay. The :ref:`detail_normal` texture only uses the red and green channels; the blue and alpha channels are ignored. The normal read from :ref:`detail_normal` is oriented around the surface normal provided by the :ref:`Mesh`. -- **TEXTURE_ALBEDO** = **0** --- Texture specifying per-pixel color. +\ **Note:** Godot expects the normal map to use X+, Y+, and Z+ coordinates. See `this page `__ for a comparison of normal map coordinates expected by popular engines. -- **TEXTURE_METALLIC** = **1** --- Texture specifying per-pixel metallic value. +.. rst-class:: classref-item-separator -- **TEXTURE_ROUGHNESS** = **2** --- Texture specifying per-pixel roughness value. +---- -- **TEXTURE_EMISSION** = **3** --- Texture specifying per-pixel emission color. +.. _class_BaseMaterial3D_property_detail_uv_layer: -- **TEXTURE_NORMAL** = **4** --- Texture specifying per-pixel normal vector. +.. rst-class:: classref-property -- **TEXTURE_RIM** = **5** --- Texture specifying per-pixel rim value. +:ref:`DetailUV` **detail_uv_layer** = ``0`` :ref:`🔗` -- **TEXTURE_CLEARCOAT** = **6** --- Texture specifying per-pixel clearcoat value. +.. rst-class:: classref-property-setget -- **TEXTURE_FLOWMAP** = **7** --- Texture specifying per-pixel flowmap direction for use with :ref:`anisotropy`. +- |void| **set_detail_uv**\ (\ value\: :ref:`DetailUV`\ ) +- :ref:`DetailUV` **get_detail_uv**\ (\ ) -- **TEXTURE_AMBIENT_OCCLUSION** = **8** --- Texture specifying per-pixel ambient occlusion value. +Specifies whether to use ``UV`` or ``UV2`` for the detail layer. -- **TEXTURE_HEIGHTMAP** = **9** --- Texture specifying per-pixel height. +.. rst-class:: classref-item-separator -- **TEXTURE_SUBSURFACE_SCATTERING** = **10** --- Texture specifying per-pixel subsurface scattering. +---- -- **TEXTURE_TRANSMISSION** = **11** --- Texture specifying per-pixel transmission color. +.. _class_BaseMaterial3D_property_diffuse_mode: -- **TEXTURE_REFRACTION** = **12** --- Texture specifying per-pixel refraction strength. +.. rst-class:: classref-property -- **TEXTURE_DETAIL_MASK** = **13** --- Texture specifying per-pixel detail mask blending value. +:ref:`DiffuseMode` **diffuse_mode** = ``0`` :ref:`🔗` -- **TEXTURE_DETAIL_ALBEDO** = **14** --- Texture specifying per-pixel detail color. +.. rst-class:: classref-property-setget -- **TEXTURE_DETAIL_NORMAL** = **15** --- Texture specifying per-pixel detail normal. +- |void| **set_diffuse_mode**\ (\ value\: :ref:`DiffuseMode`\ ) +- :ref:`DiffuseMode` **get_diffuse_mode**\ (\ ) -- **TEXTURE_ORM** = **16** +The algorithm used for diffuse light scattering. -- **TEXTURE_MAX** = **17** --- Represents the size of the :ref:`TextureParam` enum. +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_TextureFilter: - -.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST: +.. _class_BaseMaterial3D_property_disable_ambient_light: -.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS: +:ref:`bool` **disable_ambient_light** = ``false`` :ref:`🔗` -.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC: +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC: +If ``true``, the object receives no ambient light. -.. _class_BaseMaterial3D_constant_TEXTURE_FILTER_MAX: +.. rst-class:: classref-item-separator -enum **TextureFilter**: +---- -- **TEXTURE_FILTER_NEAREST** = **0** --- The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. +.. _class_BaseMaterial3D_property_disable_fog: -- **TEXTURE_FILTER_LINEAR** = **1** --- The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. +.. rst-class:: classref-property -- **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = **2** +:ref:`bool` **disable_fog** = ``false`` :ref:`🔗` -- **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = **3** +.. rst-class:: classref-property-setget -- **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = **4** +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -- **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = **5** +If ``true``, the object will not be affected by fog (neither volumetric nor depth fog). This is useful for unshaded or transparent materials (e.g. particles), which without this setting will be affected even if fully transparent. -- **TEXTURE_FILTER_MAX** = **6** --- Represents the size of the :ref:`TextureFilter` enum. +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_DetailUV: +.. _class_BaseMaterial3D_property_disable_receive_shadows: -.. _class_BaseMaterial3D_constant_DETAIL_UV_1: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_DETAIL_UV_2: +:ref:`bool` **disable_receive_shadows** = ``false`` :ref:`🔗` -enum **DetailUV**: +.. rst-class:: classref-property-setget -- **DETAIL_UV_1** = **0** --- Use ``UV`` with the detail texture. +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +If ``true``, the object receives no shadow that would otherwise be cast onto it. -- **DETAIL_UV_2** = **1** --- Use ``UV2`` with the detail texture. +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_Transparency: +.. _class_BaseMaterial3D_property_disable_specular_occlusion: -.. _class_BaseMaterial3D_constant_TRANSPARENCY_DISABLED: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA: +:ref:`bool` **disable_specular_occlusion** = ``false`` :ref:`🔗` -.. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA_SCISSOR: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_TRANSPARENCY_ALPHA_DEPTH_PRE_PASS: +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -.. _class_BaseMaterial3D_constant_TRANSPARENCY_MAX: +If ``true``, disables specular occlusion even if :ref:`ProjectSettings.rendering/reflections/specular_occlusion/enabled` is ``false``. + +.. rst-class:: classref-item-separator + +---- -enum **Transparency**: +.. _class_BaseMaterial3D_property_distance_fade_max_distance: -- **TRANSPARENCY_DISABLED** = **0** --- The material will not use transparency. +.. rst-class:: classref-property -- **TRANSPARENCY_ALPHA** = **1** --- The material will use the texture's alpha values for transparency. +:ref:`float` **distance_fade_max_distance** = ``10.0`` :ref:`🔗` -- **TRANSPARENCY_ALPHA_SCISSOR** = **2** +.. rst-class:: classref-property-setget -- **TRANSPARENCY_ALPHA_DEPTH_PRE_PASS** = **3** +- |void| **set_distance_fade_max_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_distance_fade_max_distance**\ (\ ) -- **TRANSPARENCY_MAX** = **4** --- Represents the size of the :ref:`Transparency` enum. +Distance at which the object appears fully opaque. ----- +\ **Note:** If :ref:`distance_fade_max_distance` is less than :ref:`distance_fade_min_distance`, the behavior will be reversed. The object will start to fade away at :ref:`distance_fade_max_distance` and will fully disappear once it reaches :ref:`distance_fade_min_distance`. -.. _enum_BaseMaterial3D_ShadingMode: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_SHADING_MODE_UNSHADED: +---- -.. _class_BaseMaterial3D_constant_SHADING_MODE_PER_PIXEL: +.. _class_BaseMaterial3D_property_distance_fade_min_distance: -.. _class_BaseMaterial3D_constant_SHADING_MODE_PER_VERTEX: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_SHADING_MODE_MAX: +:ref:`float` **distance_fade_min_distance** = ``0.0`` :ref:`🔗` -enum **ShadingMode**: +.. rst-class:: classref-property-setget -- **SHADING_MODE_UNSHADED** = **0** --- The object will not receive shadows. +- |void| **set_distance_fade_min_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_distance_fade_min_distance**\ (\ ) -- **SHADING_MODE_PER_PIXEL** = **1** --- The object will be shaded per pixel. Useful for realistic shading effect. +Distance at which the object starts to become visible. If the object is less than this distance away, it will be invisible. -- **SHADING_MODE_PER_VERTEX** = **2** --- The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. +\ **Note:** If :ref:`distance_fade_min_distance` is greater than :ref:`distance_fade_max_distance`, the behavior will be reversed. The object will start to fade away at :ref:`distance_fade_max_distance` and will fully disappear once it reaches :ref:`distance_fade_min_distance`. -- **SHADING_MODE_MAX** = **3** --- Represents the size of the :ref:`ShadingMode` enum. +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_Feature: +.. _class_BaseMaterial3D_property_distance_fade_mode: -.. _class_BaseMaterial3D_constant_FEATURE_EMISSION: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_FEATURE_NORMAL_MAPPING: +:ref:`DistanceFadeMode` **distance_fade_mode** = ``0`` :ref:`🔗` -.. _class_BaseMaterial3D_constant_FEATURE_RIM: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_FEATURE_CLEARCOAT: +- |void| **set_distance_fade**\ (\ value\: :ref:`DistanceFadeMode`\ ) +- :ref:`DistanceFadeMode` **get_distance_fade**\ (\ ) -.. _class_BaseMaterial3D_constant_FEATURE_ANISOTROPY: +Specifies which type of fade to use. Can be any of the :ref:`DistanceFadeMode`\ s. -.. _class_BaseMaterial3D_constant_FEATURE_AMBIENT_OCCLUSION: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_FEATURE_HEIGHT_MAPPING: +---- -.. _class_BaseMaterial3D_constant_FEATURE_SUBSURACE_SCATTERING: +.. _class_BaseMaterial3D_property_emission: -.. _class_BaseMaterial3D_constant_FEATURE_TRANSMISSION: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_FEATURE_REFRACTION: +:ref:`Color` **emission** = ``Color(0, 0, 0, 1)`` :ref:`🔗` -.. _class_BaseMaterial3D_constant_FEATURE_DETAIL: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_FEATURE_MAX: +- |void| **set_emission**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_emission**\ (\ ) -enum **Feature**: +The emitted light's color. See :ref:`emission_enabled`. -- **FEATURE_EMISSION** = **0** --- Constant for setting :ref:`emission_enabled`. +.. rst-class:: classref-item-separator -- **FEATURE_NORMAL_MAPPING** = **1** --- Constant for setting :ref:`normal_enabled`. +---- -- **FEATURE_RIM** = **2** --- Constant for setting :ref:`rim_enabled`. +.. _class_BaseMaterial3D_property_emission_enabled: -- **FEATURE_CLEARCOAT** = **3** --- Constant for setting :ref:`clearcoat_enabled`. +.. rst-class:: classref-property -- **FEATURE_ANISOTROPY** = **4** --- Constant for setting :ref:`anisotropy_enabled`. +:ref:`bool` **emission_enabled** = ``false`` :ref:`🔗` -- **FEATURE_AMBIENT_OCCLUSION** = **5** --- Constant for setting :ref:`ao_enabled`. +.. rst-class:: classref-property-setget -- **FEATURE_HEIGHT_MAPPING** = **6** +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -- **FEATURE_SUBSURACE_SCATTERING** = **7** --- Constant for setting :ref:`subsurf_scatter_enabled`. +If ``true``, the body emits light. Emitting light makes the object appear brighter. The object can also cast light on other objects if a :ref:`VoxelGI`, SDFGI, or :ref:`LightmapGI` is used and this object is used in baked lighting. -- **FEATURE_TRANSMISSION** = **8** --- Constant for setting :ref:`transmission_enabled`. +.. rst-class:: classref-item-separator -- **FEATURE_REFRACTION** = **9** --- Constant for setting :ref:`refraction_enabled`. +---- -- **FEATURE_DETAIL** = **10** --- Constant for setting :ref:`detail_enabled`. +.. _class_BaseMaterial3D_property_emission_energy_multiplier: -- **FEATURE_MAX** = **11** --- Represents the size of the :ref:`Feature` enum. +.. rst-class:: classref-property ----- +:ref:`float` **emission_energy_multiplier** = ``1.0`` :ref:`🔗` -.. _enum_BaseMaterial3D_BlendMode: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_BLEND_MODE_MIX: +- |void| **set_emission_energy_multiplier**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_emission_energy_multiplier**\ (\ ) -.. _class_BaseMaterial3D_constant_BLEND_MODE_ADD: +Multiplier for emitted light. See :ref:`emission_enabled`. -.. _class_BaseMaterial3D_constant_BLEND_MODE_SUB: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_BLEND_MODE_MUL: +---- -enum **BlendMode**: +.. _class_BaseMaterial3D_property_emission_intensity: -- **BLEND_MODE_MIX** = **0** --- Default blend mode. The color of the object is blended over the background based on the object's alpha value. +.. rst-class:: classref-property -- **BLEND_MODE_ADD** = **1** --- The color of the object is added to the background. +:ref:`float` **emission_intensity** :ref:`🔗` -- **BLEND_MODE_SUB** = **2** --- The color of the object is subtracted from the background. +.. rst-class:: classref-property-setget -- **BLEND_MODE_MUL** = **3** --- The color of the object is multiplied by the background. +- |void| **set_emission_intensity**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_emission_intensity**\ (\ ) ----- +Luminance of emitted light, measured in nits (candela per square meter). Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. The default is roughly equivalent to an indoor lightbulb. -.. _enum_BaseMaterial3D_DepthDrawMode: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_DEPTH_DRAW_OPAQUE_ONLY: +---- -.. _class_BaseMaterial3D_constant_DEPTH_DRAW_ALWAYS: +.. _class_BaseMaterial3D_property_emission_on_uv2: -.. _class_BaseMaterial3D_constant_DEPTH_DRAW_DISABLED: +.. rst-class:: classref-property + +:ref:`bool` **emission_on_uv2** = ``false`` :ref:`🔗` -enum **DepthDrawMode**: +.. rst-class:: classref-property-setget -- **DEPTH_DRAW_OPAQUE_ONLY** = **0** --- Default depth draw mode. Depth is drawn only for opaque objects. +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -- **DEPTH_DRAW_ALWAYS** = **1** --- Depth draw is calculated for both opaque and transparent objects. +Use ``UV2`` to read from the :ref:`emission_texture`. -- **DEPTH_DRAW_DISABLED** = **2** --- No depth draw. +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_CullMode: - -.. _class_BaseMaterial3D_constant_CULL_BACK: +.. _class_BaseMaterial3D_property_emission_operator: -.. _class_BaseMaterial3D_constant_CULL_FRONT: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_CULL_DISABLED: +:ref:`EmissionOperator` **emission_operator** = ``0`` :ref:`🔗` -enum **CullMode**: +.. rst-class:: classref-property-setget -- **CULL_BACK** = **0** --- Default cull mode. The back of the object is culled when not visible. +- |void| **set_emission_operator**\ (\ value\: :ref:`EmissionOperator`\ ) +- :ref:`EmissionOperator` **get_emission_operator**\ (\ ) -- **CULL_FRONT** = **1** --- The front of the object is culled when not visible. +Sets how :ref:`emission` interacts with :ref:`emission_texture`. Can either add or multiply. -- **CULL_DISABLED** = **2** --- No culling is performed. +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_Flags: +.. _class_BaseMaterial3D_property_emission_texture: -.. _class_BaseMaterial3D_constant_FLAG_DISABLE_DEPTH_TEST: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_FLAG_ALBEDO_FROM_VERTEX_COLOR: +:ref:`Texture2D` **emission_texture** :ref:`🔗` -.. _class_BaseMaterial3D_constant_FLAG_SRGB_VERTEX_COLOR: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_FLAG_USE_POINT_SIZE: +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -.. _class_BaseMaterial3D_constant_FLAG_FIXED_SIZE: +Texture that specifies how much surface emits light at a given point. -.. _class_BaseMaterial3D_constant_FLAG_BILLBOARD_KEEP_SCALE: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_FLAG_UV1_USE_TRIPLANAR: +---- -.. _class_BaseMaterial3D_constant_FLAG_UV2_USE_TRIPLANAR: +.. _class_BaseMaterial3D_property_fixed_size: -.. _class_BaseMaterial3D_constant_FLAG_UV1_USE_WORLD_TRIPLANAR: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_FLAG_UV2_USE_WORLD_TRIPLANAR: +:ref:`bool` **fixed_size** = ``false`` :ref:`🔗` -.. _class_BaseMaterial3D_constant_FLAG_AO_ON_UV2: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_FLAG_EMISSION_ON_UV2: +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -.. _class_BaseMaterial3D_constant_FLAG_ALBEDO_TEXTURE_FORCE_SRGB: +If ``true``, the object is rendered at the same size regardless of distance. The object's size on screen is the same as if the camera was ``1.0`` units away from the object's origin, regardless of the actual distance from the camera. The :ref:`Camera3D`'s field of view (or :ref:`Camera3D.size` when in orthogonal/frustum mode) still affects the size the object is drawn at. -.. _class_BaseMaterial3D_constant_FLAG_DONT_RECEIVE_SHADOWS: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_FLAG_DISABLE_AMBIENT_LIGHT: +---- -.. _class_BaseMaterial3D_constant_FLAG_USE_SHADOW_TO_OPACITY: +.. _class_BaseMaterial3D_property_fov_override: -.. _class_BaseMaterial3D_constant_FLAG_USE_TEXTURE_REPEAT: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_FLAG_INVERT_HEIGHTMAP: +:ref:`float` **fov_override** = ``75.0`` :ref:`🔗` -.. _class_BaseMaterial3D_constant_FLAG_MAX: +.. rst-class:: classref-property-setget -enum **Flags**: +- |void| **set_fov_override**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_fov_override**\ (\ ) -- **FLAG_DISABLE_DEPTH_TEST** = **0** --- Disables the depth test, so this object is drawn on top of all others. However, objects drawn after it in the draw order may cover it. +Overrides the :ref:`Camera3D`'s field of view angle (in degrees). -- **FLAG_ALBEDO_FROM_VERTEX_COLOR** = **1** --- Set ``ALBEDO`` to the per-vertex color specified in the mesh. +\ **Note:** This behaves as if the field of view is set on a :ref:`Camera3D` with :ref:`Camera3D.keep_aspect` set to :ref:`Camera3D.KEEP_HEIGHT`. Additionally, it may not look correct on a non-perspective camera where the field of view setting is ignored. -- **FLAG_SRGB_VERTEX_COLOR** = **2** --- Vertex color is in sRGB space and needs to be converted to linear. Only applies in the Vulkan renderer. +.. rst-class:: classref-item-separator -- **FLAG_USE_POINT_SIZE** = **3** --- Uses point size to alter the size of primitive points. Also changes the albedo texture lookup to use ``POINT_COORD`` instead of ``UV``. +---- + +.. _class_BaseMaterial3D_property_grow: -- **FLAG_FIXED_SIZE** = **4** --- Object is scaled by depth so that it always appears the same size on screen. +.. rst-class:: classref-property -- **FLAG_BILLBOARD_KEEP_SCALE** = **5** --- Shader will keep the scale set for the mesh. Otherwise the scale is lost when billboarding. Only applies when :ref:`billboard_mode` is :ref:`BILLBOARD_ENABLED`. +:ref:`bool` **grow** = ``false`` :ref:`🔗` -- **FLAG_UV1_USE_TRIPLANAR** = **6** --- Use triplanar texture lookup for all texture lookups that would normally use ``UV``. +.. rst-class:: classref-property-setget -- **FLAG_UV2_USE_TRIPLANAR** = **7** --- Use triplanar texture lookup for all texture lookups that would normally use ``UV2``. +- |void| **set_grow_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_grow_enabled**\ (\ ) -- **FLAG_UV1_USE_WORLD_TRIPLANAR** = **8** --- Use triplanar texture lookup for all texture lookups that would normally use ``UV``. +If ``true``, enables the vertex grow setting. This can be used to create mesh-based outlines using a second material pass and its :ref:`cull_mode` set to :ref:`CULL_FRONT`. See also :ref:`grow_amount`. -- **FLAG_UV2_USE_WORLD_TRIPLANAR** = **9** --- Use triplanar texture lookup for all texture lookups that would normally use ``UV2``. +\ **Note:** Vertex growth cannot create new vertices, which means that visible gaps may occur in sharp corners. This can be alleviated by designing the mesh to use smooth normals exclusively using `face weighted normals `__ in the 3D authoring software. In this case, grow will be able to join every outline together, just like in the original mesh. -- **FLAG_AO_ON_UV2** = **10** --- Use ``UV2`` coordinates to look up from the :ref:`ao_texture`. +.. rst-class:: classref-item-separator -- **FLAG_EMISSION_ON_UV2** = **11** --- Use ``UV2`` coordinates to look up from the :ref:`emission_texture`. +---- -- **FLAG_ALBEDO_TEXTURE_FORCE_SRGB** = **12** --- Forces the shader to convert albedo from sRGB space to linear space. +.. _class_BaseMaterial3D_property_grow_amount: -- **FLAG_DONT_RECEIVE_SHADOWS** = **13** --- Disables receiving shadows from other objects. +.. rst-class:: classref-property -- **FLAG_DISABLE_AMBIENT_LIGHT** = **14** --- Disables receiving ambient light. +:ref:`float` **grow_amount** = ``0.0`` :ref:`🔗` -- **FLAG_USE_SHADOW_TO_OPACITY** = **15** --- Enables the shadow to opacity feature. +.. rst-class:: classref-property-setget -- **FLAG_USE_TEXTURE_REPEAT** = **16** +- |void| **set_grow**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_grow**\ (\ ) -- **FLAG_INVERT_HEIGHTMAP** = **17** --- Invert values read from a depth texture to convert them to height values (heightmap). +Grows object vertices in the direction of their normals. Only effective if :ref:`grow` is ``true``. -- **FLAG_MAX** = **18** --- Represents the size of the :ref:`Flags` enum. +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_DiffuseMode: - -.. _class_BaseMaterial3D_constant_DIFFUSE_BURLEY: +.. _class_BaseMaterial3D_property_heightmap_deep_parallax: -.. _class_BaseMaterial3D_constant_DIFFUSE_LAMBERT: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_DIFFUSE_LAMBERT_WRAP: +:ref:`bool` **heightmap_deep_parallax** = ``false`` :ref:`🔗` -.. _class_BaseMaterial3D_constant_DIFFUSE_OREN_NAYAR: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_DIFFUSE_TOON: +- |void| **set_heightmap_deep_parallax**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_heightmap_deep_parallax_enabled**\ (\ ) -enum **DiffuseMode**: +If ``true``, uses parallax occlusion mapping to represent depth in the material instead of simple offset mapping (see :ref:`heightmap_enabled`). This results in a more convincing depth effect, but is much more expensive on the GPU. Only enable this on materials where it makes a significant visual difference. -- **DIFFUSE_BURLEY** = **0** --- Default diffuse scattering algorithm. +.. rst-class:: classref-item-separator -- **DIFFUSE_LAMBERT** = **1** --- Diffuse scattering ignores roughness. +---- -- **DIFFUSE_LAMBERT_WRAP** = **2** --- Extends Lambert to cover more than 90 degrees when roughness increases. +.. _class_BaseMaterial3D_property_heightmap_enabled: -- **DIFFUSE_OREN_NAYAR** = **3** --- Attempts to use roughness to emulate microsurfacing. +.. rst-class:: classref-property -- **DIFFUSE_TOON** = **4** --- Uses a hard cut for lighting, with smoothing affected by roughness. +:ref:`bool` **heightmap_enabled** = ``false`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _enum_BaseMaterial3D_SpecularMode: +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -.. _class_BaseMaterial3D_constant_SPECULAR_SCHLICK_GGX: +If ``true``, height mapping is enabled (also called "parallax mapping" or "depth mapping"). See also :ref:`normal_enabled`. Height mapping is a demanding feature on the GPU, so it should only be used on materials where it makes a significant visual difference. -.. _class_BaseMaterial3D_constant_SPECULAR_BLINN: +\ **Note:** Height mapping is not supported if triplanar mapping is used on the same material. The value of :ref:`heightmap_enabled` will be ignored if :ref:`uv1_triplanar` is enabled. -.. _class_BaseMaterial3D_constant_SPECULAR_PHONG: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_SPECULAR_TOON: +---- -.. _class_BaseMaterial3D_constant_SPECULAR_DISABLED: +.. _class_BaseMaterial3D_property_heightmap_flip_binormal: -enum **SpecularMode**: +.. rst-class:: classref-property -- **SPECULAR_SCHLICK_GGX** = **0** --- Default specular blob. +:ref:`bool` **heightmap_flip_binormal** = ``false`` :ref:`🔗` -- **SPECULAR_BLINN** = **1** --- Older specular algorithm, included for compatibility. +.. rst-class:: classref-property-setget -- **SPECULAR_PHONG** = **2** --- Older specular algorithm, included for compatibility. +- |void| **set_heightmap_deep_parallax_flip_binormal**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_heightmap_deep_parallax_flip_binormal**\ (\ ) -- **SPECULAR_TOON** = **3** --- Toon blob which changes size based on roughness. +If ``true``, flips the mesh's binormal vectors when interpreting the height map. If the heightmap effect looks strange when the camera moves (even with a reasonable :ref:`heightmap_scale`), try setting this to ``true``. -- **SPECULAR_DISABLED** = **4** --- No specular blob. +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_BillboardMode: +.. _class_BaseMaterial3D_property_heightmap_flip_tangent: -.. _class_BaseMaterial3D_constant_BILLBOARD_DISABLED: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_BILLBOARD_ENABLED: +:ref:`bool` **heightmap_flip_tangent** = ``false`` :ref:`🔗` -.. _class_BaseMaterial3D_constant_BILLBOARD_FIXED_Y: +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_constant_BILLBOARD_PARTICLES: +- |void| **set_heightmap_deep_parallax_flip_tangent**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_heightmap_deep_parallax_flip_tangent**\ (\ ) -enum **BillboardMode**: +If ``true``, flips the mesh's tangent vectors when interpreting the height map. If the heightmap effect looks strange when the camera moves (even with a reasonable :ref:`heightmap_scale`), try setting this to ``true``. -- **BILLBOARD_DISABLED** = **0** --- Billboard mode is disabled. +.. rst-class:: classref-item-separator -- **BILLBOARD_ENABLED** = **1** --- The object's Z axis will always face the camera. +---- -- **BILLBOARD_FIXED_Y** = **2** --- The object's X axis will always face the camera. +.. _class_BaseMaterial3D_property_heightmap_flip_texture: -- **BILLBOARD_PARTICLES** = **3** --- Used for particle systems when assigned to :ref:`Particles` and :ref:`CPUParticles` nodes. Enables ``particles_anim_*`` properties. +.. rst-class:: classref-property -The :ref:`ParticlesMaterial.anim_speed` or :ref:`CPUParticles.anim_speed` should also be set to a positive value for the animation to play. +:ref:`bool` **heightmap_flip_texture** = ``false`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _enum_BaseMaterial3D_TextureChannel: +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_RED: +If ``true``, interprets the height map texture as a depth map, with brighter values appearing to be "lower" in altitude compared to darker values. -.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_GREEN: +This can be enabled for compatibility with some materials authored for Godot 3.x. This is not necessary if the Invert import option was used to invert the depth map in Godot 3.x, in which case :ref:`heightmap_flip_texture` should remain ``false``. -.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_BLUE: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_ALPHA: +---- -.. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_GRAYSCALE: +.. _class_BaseMaterial3D_property_heightmap_max_layers: -enum **TextureChannel**: +.. rst-class:: classref-property -- **TEXTURE_CHANNEL_RED** = **0** --- Used to read from the red channel of a texture. +:ref:`int` **heightmap_max_layers** :ref:`🔗` -- **TEXTURE_CHANNEL_GREEN** = **1** --- Used to read from the green channel of a texture. +.. rst-class:: classref-property-setget -- **TEXTURE_CHANNEL_BLUE** = **2** --- Used to read from the blue channel of a texture. +- |void| **set_heightmap_deep_parallax_max_layers**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_heightmap_deep_parallax_max_layers**\ (\ ) -- **TEXTURE_CHANNEL_ALPHA** = **3** --- Used to read from the alpha channel of a texture. +The number of layers to use for parallax occlusion mapping when the camera is up close to the material. Higher values result in a more convincing depth effect, especially in materials that have steep height changes. Higher values have a significant cost on the GPU, so it should only be increased on materials where it makes a significant visual difference. -- **TEXTURE_CHANNEL_GRAYSCALE** = **4** --- Currently unused. +\ **Note:** Only effective if :ref:`heightmap_deep_parallax` is ``true``. + +.. rst-class:: classref-item-separator ---- -.. _enum_BaseMaterial3D_EmissionOperator: +.. _class_BaseMaterial3D_property_heightmap_min_layers: -.. _class_BaseMaterial3D_constant_EMISSION_OP_ADD: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_EMISSION_OP_MULTIPLY: +:ref:`int` **heightmap_min_layers** :ref:`🔗` -enum **EmissionOperator**: +.. rst-class:: classref-property-setget -- **EMISSION_OP_ADD** = **0** --- Adds the emission color to the color from the emission texture. +- |void| **set_heightmap_deep_parallax_min_layers**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_heightmap_deep_parallax_min_layers**\ (\ ) -- **EMISSION_OP_MULTIPLY** = **1** --- Multiplies the emission color by the color from the emission texture. +The number of layers to use for parallax occlusion mapping when the camera is far away from the material. Higher values result in a more convincing depth effect, especially in materials that have steep height changes. Higher values have a significant cost on the GPU, so it should only be increased on materials where it makes a significant visual difference. ----- +\ **Note:** Only effective if :ref:`heightmap_deep_parallax` is ``true``. -.. _enum_BaseMaterial3D_DistanceFadeMode: +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_constant_DISTANCE_FADE_DISABLED: +---- -.. _class_BaseMaterial3D_constant_DISTANCE_FADE_PIXEL_ALPHA: +.. _class_BaseMaterial3D_property_heightmap_scale: -.. _class_BaseMaterial3D_constant_DISTANCE_FADE_PIXEL_DITHER: +.. rst-class:: classref-property -.. _class_BaseMaterial3D_constant_DISTANCE_FADE_OBJECT_DITHER: +:ref:`float` **heightmap_scale** = ``5.0`` :ref:`🔗` -enum **DistanceFadeMode**: +.. rst-class:: classref-property-setget -- **DISTANCE_FADE_DISABLED** = **0** --- Do not use distance fade. +- |void| **set_heightmap_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_heightmap_scale**\ (\ ) -- **DISTANCE_FADE_PIXEL_ALPHA** = **1** --- Smoothly fades the object out based on each pixel's distance from the camera using the alpha channel. +The heightmap scale to use for the parallax effect (see :ref:`heightmap_enabled`). The default value is tuned so that the highest point (value = 255) appears to be 5 cm higher than the lowest point (value = 0). Higher values result in a deeper appearance, but may result in artifacts appearing when looking at the material from oblique angles, especially when the camera moves. Negative values can be used to invert the parallax effect, but this is different from inverting the texture using :ref:`heightmap_flip_texture` as the material will also appear to be "closer" to the camera. In most cases, :ref:`heightmap_scale` should be kept to a positive value. -- **DISTANCE_FADE_PIXEL_DITHER** = **2** --- Smoothly fades the object out based on each pixel's distance from the camera using a dither approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA`. +\ **Note:** If the height map effect looks strange regardless of this value, try adjusting :ref:`heightmap_flip_binormal` and :ref:`heightmap_flip_tangent`. See also :ref:`heightmap_texture` for recommendations on authoring heightmap textures, as the way the heightmap texture is authored affects how :ref:`heightmap_scale` behaves. -- **DISTANCE_FADE_OBJECT_DITHER** = **3** --- Smoothly fades the object out based on the object's distance from the camera using a dither approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA`. +.. rst-class:: classref-item-separator -Property Descriptions ---------------------- +---- -.. _class_BaseMaterial3D_property_albedo_color: +.. _class_BaseMaterial3D_property_heightmap_texture: -- :ref:`Color` **albedo_color** +.. rst-class:: classref-property -+-----------+-------------------------+ -| *Default* | ``Color( 1, 1, 1, 1 )`` | -+-----------+-------------------------+ -| *Setter* | set_albedo(value) | -+-----------+-------------------------+ -| *Getter* | get_albedo() | -+-----------+-------------------------+ +:ref:`Texture2D` **heightmap_texture** :ref:`🔗` -The material's base color. +.. rst-class:: classref-property-setget ----- +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -.. _class_BaseMaterial3D_property_albedo_tex_force_srgb: +The texture to use as a height map. See also :ref:`heightmap_enabled`. -- :ref:`bool` **albedo_tex_force_srgb** +For best results, the texture should be normalized (with :ref:`heightmap_scale` reduced to compensate). In `GIMP `__, this can be done using **Colors > Auto > Equalize**. If the texture only uses a small part of its available range, the parallax effect may look strange, especially when the camera moves. -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +\ **Note:** To reduce memory usage and improve loading times, you may be able to use a lower-resolution heightmap texture as most heightmaps are only comprised of low-frequency data. -Forces a conversion of the :ref:`albedo_texture` from sRGB space to linear space. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_albedo_texture: +.. _class_BaseMaterial3D_property_metallic: -- :ref:`Texture2D` **albedo_texture** +.. rst-class:: classref-property -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +:ref:`float` **metallic** = ``0.0`` :ref:`🔗` -Texture to multiply by :ref:`albedo_color`. Used for basic texturing of objects. +.. rst-class:: classref-property-setget ----- +- |void| **set_metallic**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_metallic**\ (\ ) -.. _class_BaseMaterial3D_property_alpha_scissor_threshold: +A high value makes the material appear more like a metal. Non-metals use their albedo as the diffuse color and add diffuse to the specular reflection. With non-metals, the reflection appears on top of the albedo color. Metals use their albedo as a multiplier to the specular reflection and set the diffuse color to black resulting in a tinted reflection. Materials work better when fully metal or fully non-metal, values between ``0`` and ``1`` should only be used for blending between metal and non-metal sections. To alter the amount of reflection use :ref:`roughness`. -- :ref:`float` **alpha_scissor_threshold** +.. rst-class:: classref-item-separator -+----------+------------------------------------+ -| *Setter* | set_alpha_scissor_threshold(value) | -+----------+------------------------------------+ -| *Getter* | get_alpha_scissor_threshold() | -+----------+------------------------------------+ +---- -Threshold at which the alpha scissor will discard values. +.. _class_BaseMaterial3D_property_metallic_specular: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_anisotropy: +:ref:`float` **metallic_specular** = ``0.5`` :ref:`🔗` -- :ref:`float` **anisotropy** +.. rst-class:: classref-property-setget -+----------+-----------------------+ -| *Setter* | set_anisotropy(value) | -+----------+-----------------------+ -| *Getter* | get_anisotropy() | -+----------+-----------------------+ +- |void| **set_specular**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_specular**\ (\ ) -The strength of the anisotropy effect. +Adjusts the strength of specular reflections. Specular reflections are composed of scene reflections and the specular lobe which is the bright spot that is reflected from light sources. When set to ``0.0``, no specular reflections will be visible. This differs from the :ref:`SPECULAR_DISABLED` :ref:`SpecularMode` as :ref:`SPECULAR_DISABLED` only applies to the specular lobe from the light source. ----- +\ **Note:** Unlike :ref:`metallic`, this is not energy-conserving, so it should be left at ``0.5`` in most cases. See also :ref:`roughness`. -.. _class_BaseMaterial3D_property_anisotropy_enabled: +.. rst-class:: classref-item-separator -- :ref:`bool` **anisotropy_enabled** +---- -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +.. _class_BaseMaterial3D_property_metallic_texture: -If ``true``, anisotropy is enabled. Changes the shape of the specular blob and aligns it to tangent space. Mesh tangents are needed for this to work. If the mesh does not contain tangents the anisotropy effect will appear broken. +.. rst-class:: classref-property ----- +:ref:`Texture2D` **metallic_texture** :ref:`🔗` -.. _class_BaseMaterial3D_property_anisotropy_flowmap: +.. rst-class:: classref-property-setget -- :ref:`Texture2D` **anisotropy_flowmap** +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +Texture used to specify metallic for an object. This is multiplied by :ref:`metallic`. -Texture that offsets the tangent map for anisotropy calculations. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_ao_enabled: +.. _class_BaseMaterial3D_property_metallic_texture_channel: -- :ref:`bool` **ao_enabled** +.. rst-class:: classref-property -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +:ref:`TextureChannel` **metallic_texture_channel** = ``0`` :ref:`🔗` -If ``true``, ambient occlusion is enabled. Ambient occlusion darkens areas based on the :ref:`ao_texture`. +.. rst-class:: classref-property-setget ----- +- |void| **set_metallic_texture_channel**\ (\ value\: :ref:`TextureChannel`\ ) +- :ref:`TextureChannel` **get_metallic_texture_channel**\ (\ ) -.. _class_BaseMaterial3D_property_ao_light_affect: +Specifies the channel of the :ref:`metallic_texture` in which the metallic information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. -- :ref:`float` **ao_light_affect** +.. rst-class:: classref-item-separator -+----------+----------------------------+ -| *Setter* | set_ao_light_affect(value) | -+----------+----------------------------+ -| *Getter* | get_ao_light_affect() | -+----------+----------------------------+ +---- -Amount that ambient occlusion affects lighting from lights. If ``0``, ambient occlusion only affects ambient light. If ``1``, ambient occlusion affects lights just as much as it affects ambient light. This can be used to impact the strength of the ambient occlusion effect, but typically looks unrealistic. +.. _class_BaseMaterial3D_property_msdf_outline_size: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_ao_on_uv2: +:ref:`float` **msdf_outline_size** = ``0.0`` :ref:`🔗` -- :ref:`bool` **ao_on_uv2** +.. rst-class:: classref-property-setget -+----------+-----------------+ -| *Setter* | set_flag(value) | -+----------+-----------------+ -| *Getter* | get_flag() | -+----------+-----------------+ +- |void| **set_msdf_outline_size**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_msdf_outline_size**\ (\ ) -If ``true``, use ``UV2`` coordinates to look up from the :ref:`ao_texture`. +The width of the shape outline. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_ao_texture: +.. _class_BaseMaterial3D_property_msdf_pixel_range: -- :ref:`Texture2D` **ao_texture** +.. rst-class:: classref-property -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +:ref:`float` **msdf_pixel_range** = ``4.0`` :ref:`🔗` -Texture that defines the amount of ambient occlusion for a given point on the object. +.. rst-class:: classref-property-setget ----- +- |void| **set_msdf_pixel_range**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_msdf_pixel_range**\ (\ ) -.. _class_BaseMaterial3D_property_ao_texture_channel: +The width of the range around the shape between the minimum and maximum representable signed distance. + +.. rst-class:: classref-item-separator -- :ref:`TextureChannel` **ao_texture_channel** +---- -+----------+-------------------------------+ -| *Setter* | set_ao_texture_channel(value) | -+----------+-------------------------------+ -| *Getter* | get_ao_texture_channel() | -+----------+-------------------------------+ +.. _class_BaseMaterial3D_property_no_depth_test: -Specifies the channel of the :ref:`ao_texture` in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. +.. rst-class:: classref-property ----- +:ref:`bool` **no_depth_test** = ``false`` :ref:`🔗` -.. _class_BaseMaterial3D_property_billboard_keep_scale: +.. rst-class:: classref-property-setget -- :ref:`bool` **billboard_keep_scale** +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +If ``true``, depth testing is disabled and the object will be drawn in render order. -If ``true``, the shader will keep the scale set for the mesh. Otherwise the scale is lost when billboarding. Only applies when :ref:`billboard_mode` is :ref:`BILLBOARD_ENABLED`. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_billboard_mode: +.. _class_BaseMaterial3D_property_normal_enabled: -- :ref:`BillboardMode` **billboard_mode** +.. rst-class:: classref-property -+-----------+---------------------------+ -| *Default* | ``0`` | -+-----------+---------------------------+ -| *Setter* | set_billboard_mode(value) | -+-----------+---------------------------+ -| *Getter* | get_billboard_mode() | -+-----------+---------------------------+ +:ref:`bool` **normal_enabled** = ``false`` :ref:`🔗` -Controls how the object faces the camera. See :ref:`BillboardMode`. +.. rst-class:: classref-property-setget ----- +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -.. _class_BaseMaterial3D_property_blend_mode: +If ``true``, normal mapping is enabled. This has a slight performance cost, especially on mobile GPUs. -- :ref:`BlendMode` **blend_mode** +.. rst-class:: classref-item-separator -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_blend_mode(value) | -+-----------+-----------------------+ -| *Getter* | get_blend_mode() | -+-----------+-----------------------+ +---- -The material's blend mode. +.. _class_BaseMaterial3D_property_normal_scale: -**Note:** Values other than ``Mix`` force the object into the transparent pipeline. See :ref:`BlendMode`. +.. rst-class:: classref-property ----- +:ref:`float` **normal_scale** = ``1.0`` :ref:`🔗` -.. _class_BaseMaterial3D_property_clearcoat: +.. rst-class:: classref-property-setget -- :ref:`float` **clearcoat** +- |void| **set_normal_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_normal_scale**\ (\ ) -+----------+----------------------+ -| *Setter* | set_clearcoat(value) | -+----------+----------------------+ -| *Getter* | get_clearcoat() | -+----------+----------------------+ +The strength of the normal map's effect. -Sets the strength of the clearcoat effect. Setting to ``0`` looks the same as disabling the clearcoat effect. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_clearcoat_enabled: +.. _class_BaseMaterial3D_property_normal_texture: -- :ref:`bool` **clearcoat_enabled** +.. rst-class:: classref-property -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +:ref:`Texture2D` **normal_texture** :ref:`🔗` -If ``true``, clearcoat rendering is enabled. Adds a secondary transparent pass to the lighting calculation resulting in an added specular blob. This makes materials appear as if they have a clear layer on them that can be either glossy or rough. +.. rst-class:: classref-property-setget ----- +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture used to specify the normal at a given pixel. The :ref:`normal_texture` only uses the red and green channels; the blue and alpha channels are ignored. The normal read from :ref:`normal_texture` is oriented around the surface normal provided by the :ref:`Mesh`. -.. _class_BaseMaterial3D_property_clearcoat_gloss: +\ **Note:** The mesh must have both normals and tangents defined in its vertex data. Otherwise, the normal map won't render correctly and will only appear to darken the whole surface. If creating geometry with :ref:`SurfaceTool`, you can use :ref:`SurfaceTool.generate_normals()` and :ref:`SurfaceTool.generate_tangents()` to automatically generate normals and tangents respectively. -- :ref:`float` **clearcoat_gloss** +\ **Note:** Godot expects the normal map to use X+, Y+, and Z+ coordinates. See `this page `__ for a comparison of normal map coordinates expected by popular engines. -+----------+----------------------------+ -| *Setter* | set_clearcoat_gloss(value) | -+----------+----------------------------+ -| *Getter* | get_clearcoat_gloss() | -+----------+----------------------------+ +\ **Note:** If :ref:`detail_enabled` is ``true``, the :ref:`detail_albedo` texture is drawn *below* the :ref:`normal_texture`. To display a normal map *above* the :ref:`detail_albedo` texture, use :ref:`detail_normal` instead. -Sets the roughness of the clearcoat pass. A higher value results in a smoother clearcoat while a lower value results in a rougher clearcoat. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_clearcoat_texture: +.. _class_BaseMaterial3D_property_orm_texture: -- :ref:`Texture2D` **clearcoat_texture** +.. rst-class:: classref-property -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +:ref:`Texture2D` **orm_texture** :ref:`🔗` -Texture that defines the strength of the clearcoat effect and the glossiness of the clearcoat. Strength is specified in the red channel while glossiness is specified in the green channel. +.. rst-class:: classref-property-setget ----- +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -.. _class_BaseMaterial3D_property_cull_mode: +The Occlusion/Roughness/Metallic texture to use. This is a more efficient replacement of :ref:`ao_texture`, :ref:`roughness_texture` and :ref:`metallic_texture` in :ref:`ORMMaterial3D`. Ambient occlusion is stored in the red channel. Roughness map is stored in the green channel. Metallic map is stored in the blue channel. The alpha channel is ignored. + +.. rst-class:: classref-item-separator -- :ref:`CullMode` **cull_mode** +---- -+-----------+----------------------+ -| *Default* | ``0`` | -+-----------+----------------------+ -| *Setter* | set_cull_mode(value) | -+-----------+----------------------+ -| *Getter* | get_cull_mode() | -+-----------+----------------------+ +.. _class_BaseMaterial3D_property_particles_anim_h_frames: -Which side of the object is not drawn when backfaces are rendered. See :ref:`CullMode`. +.. rst-class:: classref-property ----- +:ref:`int` **particles_anim_h_frames** :ref:`🔗` -.. _class_BaseMaterial3D_property_depth_draw_mode: +.. rst-class:: classref-property-setget -- :ref:`DepthDrawMode` **depth_draw_mode** +- |void| **set_particles_anim_h_frames**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_particles_anim_h_frames**\ (\ ) -+-----------+----------------------------+ -| *Default* | ``0`` | -+-----------+----------------------------+ -| *Setter* | set_depth_draw_mode(value) | -+-----------+----------------------------+ -| *Getter* | get_depth_draw_mode() | -+-----------+----------------------------+ +The number of horizontal frames in the particle sprite sheet. Only enabled when using :ref:`BILLBOARD_PARTICLES`. See :ref:`billboard_mode`. -Determines when depth rendering takes place. See :ref:`DepthDrawMode`. See also :ref:`transparency`. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_detail_albedo: +.. _class_BaseMaterial3D_property_particles_anim_loop: -- :ref:`Texture2D` **detail_albedo** +.. rst-class:: classref-property -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +:ref:`bool` **particles_anim_loop** :ref:`🔗` -Texture that specifies the color of the detail overlay. +.. rst-class:: classref-property-setget ----- +- |void| **set_particles_anim_loop**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_particles_anim_loop**\ (\ ) -.. _class_BaseMaterial3D_property_detail_blend_mode: +If ``true``, particle animations are looped. Only enabled when using :ref:`BILLBOARD_PARTICLES`. See :ref:`billboard_mode`. -- :ref:`BlendMode` **detail_blend_mode** +.. rst-class:: classref-item-separator + +---- -+----------+------------------------------+ -| *Setter* | set_detail_blend_mode(value) | -+----------+------------------------------+ -| *Getter* | get_detail_blend_mode() | -+----------+------------------------------+ +.. _class_BaseMaterial3D_property_particles_anim_v_frames: -Specifies how the :ref:`detail_albedo` should blend with the current ``ALBEDO``. See :ref:`BlendMode` for options. +.. rst-class:: classref-property ----- +:ref:`int` **particles_anim_v_frames** :ref:`🔗` -.. _class_BaseMaterial3D_property_detail_enabled: +.. rst-class:: classref-property-setget -- :ref:`bool` **detail_enabled** +- |void| **set_particles_anim_v_frames**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_particles_anim_v_frames**\ (\ ) -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +The number of vertical frames in the particle sprite sheet. Only enabled when using :ref:`BILLBOARD_PARTICLES`. See :ref:`billboard_mode`. -If ``true``, enables the detail overlay. Detail is a second texture that gets mixed over the surface of the object based on :ref:`detail_mask`. This can be used to add variation to objects, or to blend between two different albedo/normal textures. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_detail_mask: +.. _class_BaseMaterial3D_property_point_size: + +.. rst-class:: classref-property + +:ref:`float` **point_size** = ``1.0`` :ref:`🔗` -- :ref:`Texture2D` **detail_mask** +.. rst-class:: classref-property-setget -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +- |void| **set_point_size**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_point_size**\ (\ ) -Texture used to specify how the detail textures get blended with the base textures. +The point size in pixels. See :ref:`use_point_size`. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_detail_normal: +.. _class_BaseMaterial3D_property_proximity_fade_distance: -- :ref:`Texture2D` **detail_normal** +.. rst-class:: classref-property -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +:ref:`float` **proximity_fade_distance** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_proximity_fade_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_proximity_fade_distance**\ (\ ) + +Distance over which the fade effect takes place. The larger the distance the longer it takes for an object to fade. -Texture that specifies the per-pixel normal of the detail overlay. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_detail_uv_layer: +.. _class_BaseMaterial3D_property_proximity_fade_enabled: -- :ref:`DetailUV` **detail_uv_layer** +.. rst-class:: classref-property -+----------+----------------------+ -| *Setter* | set_detail_uv(value) | -+----------+----------------------+ -| *Getter* | get_detail_uv() | -+----------+----------------------+ +:ref:`bool` **proximity_fade_enabled** = ``false`` :ref:`🔗` -Specifies whether to use ``UV`` or ``UV2`` for the detail layer. See :ref:`DetailUV` for options. +.. rst-class:: classref-property-setget ----- +- |void| **set_proximity_fade_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_proximity_fade_enabled**\ (\ ) -.. _class_BaseMaterial3D_property_diffuse_mode: +If ``true``, the proximity fade effect is enabled. The proximity fade effect fades out each pixel based on its distance to another object. -- :ref:`DiffuseMode` **diffuse_mode** +.. rst-class:: classref-item-separator -+-----------+-------------------------+ -| *Default* | ``0`` | -+-----------+-------------------------+ -| *Setter* | set_diffuse_mode(value) | -+-----------+-------------------------+ -| *Getter* | get_diffuse_mode() | -+-----------+-------------------------+ +---- -The algorithm used for diffuse light scattering. See :ref:`DiffuseMode`. +.. _class_BaseMaterial3D_property_refraction_enabled: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_disable_ambient_light: +:ref:`bool` **refraction_enabled** = ``false`` :ref:`🔗` -- :ref:`bool` **disable_ambient_light** +.. rst-class:: classref-property-setget -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -If ``true``, the object receives no ambient light. +If ``true``, the refraction effect is enabled. Distorts transparency based on light from behind the object. ----- +\ **Note:** Refraction is implemented using the screen texture. Only opaque materials will appear in the refraction, since transparent materials do not appear in the screen texture. -.. _class_BaseMaterial3D_property_disable_receive_shadows: +.. rst-class:: classref-item-separator -- :ref:`bool` **disable_receive_shadows** +---- -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +.. _class_BaseMaterial3D_property_refraction_scale: -If ``true``, the object receives no shadow that would otherwise be cast onto it. +.. rst-class:: classref-property ----- +:ref:`float` **refraction_scale** = ``0.05`` :ref:`🔗` -.. _class_BaseMaterial3D_property_distance_fade_max_distance: +.. rst-class:: classref-property-setget -- :ref:`float` **distance_fade_max_distance** +- |void| **set_refraction**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_refraction**\ (\ ) -+----------+---------------------------------------+ -| *Setter* | set_distance_fade_max_distance(value) | -+----------+---------------------------------------+ -| *Getter* | get_distance_fade_max_distance() | -+----------+---------------------------------------+ +The strength of the refraction effect. -Distance at which the object fades fully and is no longer visible. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_distance_fade_min_distance: +.. _class_BaseMaterial3D_property_refraction_texture: -- :ref:`float` **distance_fade_min_distance** +.. rst-class:: classref-property -+----------+---------------------------------------+ -| *Setter* | set_distance_fade_min_distance(value) | -+----------+---------------------------------------+ -| *Getter* | get_distance_fade_min_distance() | -+----------+---------------------------------------+ +:ref:`Texture2D` **refraction_texture** :ref:`🔗` -Distance at which the object starts to fade. If the object is less than this distance away it will appear normal. +.. rst-class:: classref-property-setget ----- +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -.. _class_BaseMaterial3D_property_distance_fade_mode: +Texture that controls the strength of the refraction per-pixel. Multiplied by :ref:`refraction_scale`. + +.. rst-class:: classref-item-separator -- :ref:`DistanceFadeMode` **distance_fade_mode** +---- -+-----------+--------------------------+ -| *Default* | ``0`` | -+-----------+--------------------------+ -| *Setter* | set_distance_fade(value) | -+-----------+--------------------------+ -| *Getter* | get_distance_fade() | -+-----------+--------------------------+ +.. _class_BaseMaterial3D_property_refraction_texture_channel: -Specifies which type of fade to use. Can be any of the :ref:`DistanceFadeMode`\ s. +.. rst-class:: classref-property ----- +:ref:`TextureChannel` **refraction_texture_channel** = ``0`` :ref:`🔗` -.. _class_BaseMaterial3D_property_emission: +.. rst-class:: classref-property-setget -- :ref:`Color` **emission** +- |void| **set_refraction_texture_channel**\ (\ value\: :ref:`TextureChannel`\ ) +- :ref:`TextureChannel` **get_refraction_texture_channel**\ (\ ) -+----------+---------------------+ -| *Setter* | set_emission(value) | -+----------+---------------------+ -| *Getter* | get_emission() | -+----------+---------------------+ +Specifies the channel of the :ref:`refraction_texture` in which the refraction information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored refraction in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. -The emitted light's color. See :ref:`emission_enabled`. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_emission_enabled: +.. _class_BaseMaterial3D_property_rim: -- :ref:`bool` **emission_enabled** +.. rst-class:: classref-property -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +:ref:`float` **rim** = ``1.0`` :ref:`🔗` -If ``true``, the body emits light. Emitting light makes the object appear brighter. The object can also cast light on other objects if a :ref:`GIProbe` is used and this object is used in baked lighting. +.. rst-class:: classref-property-setget ----- +- |void| **set_rim**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_rim**\ (\ ) -.. _class_BaseMaterial3D_property_emission_energy: +Sets the strength of the rim lighting effect. -- :ref:`float` **emission_energy** +.. rst-class:: classref-item-separator -+----------+----------------------------+ -| *Setter* | set_emission_energy(value) | -+----------+----------------------------+ -| *Getter* | get_emission_energy() | -+----------+----------------------------+ +---- -The emitted light's strength. See :ref:`emission_enabled`. +.. _class_BaseMaterial3D_property_rim_enabled: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_emission_on_uv2: +:ref:`bool` **rim_enabled** = ``false`` :ref:`🔗` -- :ref:`bool` **emission_on_uv2** +.. rst-class:: classref-property-setget -+----------+-----------------+ -| *Setter* | set_flag(value) | -+----------+-----------------+ -| *Getter* | get_flag() | -+----------+-----------------+ +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -Use ``UV2`` to read from the :ref:`emission_texture`. +If ``true``, rim effect is enabled. Rim lighting increases the brightness at glancing angles on an object. ----- +\ **Note:** Rim lighting is not visible if the material's :ref:`shading_mode` is :ref:`SHADING_MODE_UNSHADED`. -.. _class_BaseMaterial3D_property_emission_operator: +.. rst-class:: classref-item-separator -- :ref:`EmissionOperator` **emission_operator** +---- -+----------+------------------------------+ -| *Setter* | set_emission_operator(value) | -+----------+------------------------------+ -| *Getter* | get_emission_operator() | -+----------+------------------------------+ +.. _class_BaseMaterial3D_property_rim_texture: -Sets how :ref:`emission` interacts with :ref:`emission_texture`. Can either add or multiply. See :ref:`EmissionOperator` for options. +.. rst-class:: classref-property ----- +:ref:`Texture2D` **rim_texture** :ref:`🔗` -.. _class_BaseMaterial3D_property_emission_texture: +.. rst-class:: classref-property-setget -- :ref:`Texture2D` **emission_texture** +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +Texture used to set the strength of the rim lighting effect per-pixel. Multiplied by :ref:`rim`. -Texture that specifies how much surface emits light at a given point. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_fixed_size: +.. _class_BaseMaterial3D_property_rim_tint: -- :ref:`bool` **fixed_size** +.. rst-class:: classref-property -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +:ref:`float` **rim_tint** = ``0.5`` :ref:`🔗` -If ``true``, the object is rendered at the same size regardless of distance. +.. rst-class:: classref-property-setget ----- +- |void| **set_rim_tint**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_rim_tint**\ (\ ) -.. _class_BaseMaterial3D_property_grow: +The amount of to blend light and albedo color when rendering rim effect. If ``0`` the light color is used, while ``1`` means albedo color is used. An intermediate value generally works best. -- :ref:`bool` **grow** +.. rst-class:: classref-item-separator -+-----------+-------------------------+ -| *Default* | ``false`` | -+-----------+-------------------------+ -| *Setter* | set_grow_enabled(value) | -+-----------+-------------------------+ -| *Getter* | is_grow_enabled() | -+-----------+-------------------------+ +---- -If ``true``, enables the vertex grow setting. See :ref:`grow_amount`. +.. _class_BaseMaterial3D_property_roughness: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_grow_amount: +:ref:`float` **roughness** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`float` **grow_amount** +- |void| **set_roughness**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_roughness**\ (\ ) -+-----------+-----------------+ -| *Default* | ``0.0`` | -+-----------+-----------------+ -| *Setter* | set_grow(value) | -+-----------+-----------------+ -| *Getter* | get_grow() | -+-----------+-----------------+ +Surface reflection. A value of ``0`` represents a perfect mirror while a value of ``1`` completely blurs the reflection. See also :ref:`metallic`. -Grows object vertices in the direction of their normals. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_heightmap_deep_parallax: +.. _class_BaseMaterial3D_property_roughness_texture: -- :ref:`bool` **heightmap_deep_parallax** +.. rst-class:: classref-property -+----------+--------------------------------------+ -| *Setter* | set_heightmap_deep_parallax(value) | -+----------+--------------------------------------+ -| *Getter* | is_heightmap_deep_parallax_enabled() | -+----------+--------------------------------------+ +:ref:`Texture2D` **roughness_texture** :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_heightmap_enabled: +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -- :ref:`bool` **heightmap_enabled** +Texture used to control the roughness per-pixel. Multiplied by :ref:`roughness`. -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_heightmap_flip_binormal: +.. _class_BaseMaterial3D_property_roughness_texture_channel: -- :ref:`bool` **heightmap_flip_binormal** +.. rst-class:: classref-property -+----------+--------------------------------------------------+ -| *Setter* | set_heightmap_deep_parallax_flip_binormal(value) | -+----------+--------------------------------------------------+ -| *Getter* | get_heightmap_deep_parallax_flip_binormal() | -+----------+--------------------------------------------------+ +:ref:`TextureChannel` **roughness_texture_channel** = ``0`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_heightmap_flip_tangent: +- |void| **set_roughness_texture_channel**\ (\ value\: :ref:`TextureChannel`\ ) +- :ref:`TextureChannel` **get_roughness_texture_channel**\ (\ ) -- :ref:`bool` **heightmap_flip_tangent** +Specifies the channel of the :ref:`roughness_texture` in which the roughness information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. -+----------+-------------------------------------------------+ -| *Setter* | set_heightmap_deep_parallax_flip_tangent(value) | -+----------+-------------------------------------------------+ -| *Getter* | get_heightmap_deep_parallax_flip_tangent() | -+----------+-------------------------------------------------+ +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_heightmap_flip_texture: +.. _class_BaseMaterial3D_property_shading_mode: -- :ref:`bool` **heightmap_flip_texture** +.. rst-class:: classref-property -+----------+-----------------+ -| *Setter* | set_flag(value) | -+----------+-----------------+ -| *Getter* | get_flag() | -+----------+-----------------+ +:ref:`ShadingMode` **shading_mode** = ``1`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_heightmap_max_layers: +- |void| **set_shading_mode**\ (\ value\: :ref:`ShadingMode`\ ) +- :ref:`ShadingMode` **get_shading_mode**\ (\ ) -- :ref:`int` **heightmap_max_layers** +Sets whether the shading takes place, per-pixel, per-vertex or unshaded. Per-vertex lighting is faster, making it the best choice for mobile applications, however it looks considerably worse than per-pixel. Unshaded rendering is the fastest, but disables all interactions with lights. -+----------+-----------------------------------------------+ -| *Setter* | set_heightmap_deep_parallax_max_layers(value) | -+----------+-----------------------------------------------+ -| *Getter* | get_heightmap_deep_parallax_max_layers() | -+----------+-----------------------------------------------+ +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_heightmap_min_layers: +.. _class_BaseMaterial3D_property_shadow_to_opacity: -- :ref:`int` **heightmap_min_layers** +.. rst-class:: classref-property -+----------+-----------------------------------------------+ -| *Setter* | set_heightmap_deep_parallax_min_layers(value) | -+----------+-----------------------------------------------+ -| *Getter* | get_heightmap_deep_parallax_min_layers() | -+----------+-----------------------------------------------+ +:ref:`bool` **shadow_to_opacity** = ``false`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_heightmap_scale: +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -- :ref:`float` **heightmap_scale** +If ``true``, enables the "shadow to opacity" render mode where lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR. -+----------+----------------------------+ -| *Setter* | set_heightmap_scale(value) | -+----------+----------------------------+ -| *Getter* | get_heightmap_scale() | -+----------+----------------------------+ +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_heightmap_texture: +.. _class_BaseMaterial3D_property_specular_mode: -- :ref:`Texture2D` **heightmap_texture** +.. rst-class:: classref-property -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +:ref:`SpecularMode` **specular_mode** = ``0`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_metallic: +- |void| **set_specular_mode**\ (\ value\: :ref:`SpecularMode`\ ) +- :ref:`SpecularMode` **get_specular_mode**\ (\ ) -- :ref:`float` **metallic** +The method for rendering the specular blob. -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_metallic(value) | -+-----------+---------------------+ -| *Getter* | get_metallic() | -+-----------+---------------------+ +\ **Note:** :ref:`specular_mode` only applies to the specular blob. It does not affect specular reflections from the sky, screen-space reflections, :ref:`VoxelGI`, SDFGI or :ref:`ReflectionProbe`\ s. To disable reflections from these sources as well, set :ref:`metallic_specular` to ``0.0`` instead. -A high value makes the material appear more like a metal. Non-metals use their albedo as the diffuse color and add diffuse to the specular reflection. With non-metals, the reflection appears on top of the albedo color. Metals use their albedo as a multiplier to the specular reflection and set the diffuse color to black resulting in a tinted reflection. Materials work better when fully metal or fully non-metal, values between ``0`` and ``1`` should only be used for blending between metal and non-metal sections. To alter the amount of reflection use :ref:`roughness`. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_metallic_specular: - -- :ref:`float` **metallic_specular** +.. _class_BaseMaterial3D_property_stencil_color: -+-----------+---------------------+ -| *Default* | ``0.5`` | -+-----------+---------------------+ -| *Setter* | set_specular(value) | -+-----------+---------------------+ -| *Getter* | get_specular() | -+-----------+---------------------+ +.. rst-class:: classref-property -Sets the size of the specular lobe. The specular lobe is the bright spot that is reflected from light sources. +:ref:`Color` **stencil_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` -**Note:** unlike :ref:`metallic`, this is not energy-conserving, so it should be left at ``0.5`` in most cases. See also :ref:`roughness`. +.. rst-class:: classref-property-setget ----- - -.. _class_BaseMaterial3D_property_metallic_texture: +- |void| **set_stencil_effect_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_stencil_effect_color**\ (\ ) -- :ref:`Texture2D` **metallic_texture** +**Experimental:** May be affected by future rendering pipeline changes. -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +The primary color of the stencil effect. -Texture used to specify metallic for an object. This is multiplied by :ref:`metallic`. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_metallic_texture_channel: - -- :ref:`TextureChannel` **metallic_texture_channel** +.. _class_BaseMaterial3D_property_stencil_compare: -+-----------+-------------------------------------+ -| *Default* | ``0`` | -+-----------+-------------------------------------+ -| *Setter* | set_metallic_texture_channel(value) | -+-----------+-------------------------------------+ -| *Getter* | get_metallic_texture_channel() | -+-----------+-------------------------------------+ +.. rst-class:: classref-property -Specifies the channel of the :ref:`metallic_texture` in which the metallic information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. +:ref:`StencilCompare` **stencil_compare** = ``0`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_no_depth_test: +- |void| **set_stencil_compare**\ (\ value\: :ref:`StencilCompare`\ ) +- :ref:`StencilCompare` **get_stencil_compare**\ (\ ) -- :ref:`bool` **no_depth_test** +**Experimental:** May be affected by future rendering pipeline changes. -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +The comparison operator to use for stencil masking operations. See :ref:`StencilCompare`. -If ``true``, depth testing is disabled and the object will be drawn in render order. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_normal_enabled: - -- :ref:`bool` **normal_enabled** +.. _class_BaseMaterial3D_property_stencil_flags: -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +.. rst-class:: classref-property -If ``true``, normal mapping is enabled. +:ref:`int` **stencil_flags** = ``0`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_normal_scale: +- |void| **set_stencil_flags**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_stencil_flags**\ (\ ) -- :ref:`float` **normal_scale** +**Experimental:** May be affected by future rendering pipeline changes. -+----------+-------------------------+ -| *Setter* | set_normal_scale(value) | -+----------+-------------------------+ -| *Getter* | get_normal_scale() | -+----------+-------------------------+ +The flags dictating how the stencil operation behaves. See :ref:`StencilFlags`. -The strength of the normal map's effect. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_normal_texture: +.. _class_BaseMaterial3D_property_stencil_mode: -- :ref:`Texture2D` **normal_texture** +.. rst-class:: classref-property -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +:ref:`StencilMode` **stencil_mode** = ``0`` :ref:`🔗` -Texture used to specify the normal at a given pixel. The ``normal_texture`` only uses the red and green channels. The normal read from ``normal_texture`` is oriented around the surface normal provided by the :ref:`Mesh`. +.. rst-class:: classref-property-setget ----- +- |void| **set_stencil_mode**\ (\ value\: :ref:`StencilMode`\ ) +- :ref:`StencilMode` **get_stencil_mode**\ (\ ) -.. _class_BaseMaterial3D_property_orm_texture: +**Experimental:** May be affected by future rendering pipeline changes. -- :ref:`Texture2D` **orm_texture** +The stencil effect mode. See :ref:`StencilMode`. -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_particles_anim_h_frames: - -- :ref:`int` **particles_anim_h_frames** +.. _class_BaseMaterial3D_property_stencil_outline_thickness: -+----------+------------------------------------+ -| *Setter* | set_particles_anim_h_frames(value) | -+----------+------------------------------------+ -| *Getter* | get_particles_anim_h_frames() | -+----------+------------------------------------+ +.. rst-class:: classref-property -The number of horizontal frames in the particle sprite sheet. Only enabled when using :ref:`BILLBOARD_PARTICLES`. See :ref:`billboard_mode`. +:ref:`float` **stencil_outline_thickness** = ``0.01`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_particles_anim_loop: +- |void| **set_stencil_effect_outline_thickness**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_stencil_effect_outline_thickness**\ (\ ) -- :ref:`bool` **particles_anim_loop** +**Experimental:** May be affected by future rendering pipeline changes. -+----------+--------------------------------+ -| *Setter* | set_particles_anim_loop(value) | -+----------+--------------------------------+ -| *Getter* | get_particles_anim_loop() | -+----------+--------------------------------+ +The outline thickness for :ref:`STENCIL_MODE_OUTLINE`. -If ``true``, particle animations are looped. Only enabled when using :ref:`BILLBOARD_PARTICLES`. See :ref:`billboard_mode`. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_particles_anim_v_frames: - -- :ref:`int` **particles_anim_v_frames** +.. _class_BaseMaterial3D_property_stencil_reference: -+----------+------------------------------------+ -| *Setter* | set_particles_anim_v_frames(value) | -+----------+------------------------------------+ -| *Getter* | get_particles_anim_v_frames() | -+----------+------------------------------------+ +.. rst-class:: classref-property -The number of vertical frames in the particle sprite sheet. Only enabled when using :ref:`BILLBOARD_PARTICLES`. See :ref:`billboard_mode`. +:ref:`int` **stencil_reference** = ``1`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_point_size: +- |void| **set_stencil_reference**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_stencil_reference**\ (\ ) -- :ref:`float` **point_size** +**Experimental:** May be affected by future rendering pipeline changes. -+-----------+-----------------------+ -| *Default* | ``1.0`` | -+-----------+-----------------------+ -| *Setter* | set_point_size(value) | -+-----------+-----------------------+ -| *Getter* | get_point_size() | -+-----------+-----------------------+ +The stencil reference value (0-255). Typically a power of 2. -The point size in pixels. See :ref:`use_point_size`. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_proximity_fade_distance: - -- :ref:`float` **proximity_fade_distance** +.. _class_BaseMaterial3D_property_subsurf_scatter_enabled: -+----------+------------------------------------+ -| *Setter* | set_proximity_fade_distance(value) | -+----------+------------------------------------+ -| *Getter* | get_proximity_fade_distance() | -+----------+------------------------------------+ +.. rst-class:: classref-property -Distance over which the fade effect takes place. The larger the distance the longer it takes for an object to fade. +:ref:`bool` **subsurf_scatter_enabled** = ``false`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_proximity_fade_enable: +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -- :ref:`bool` **proximity_fade_enable** +If ``true``, subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges. Subsurface scattering quality is controlled by :ref:`ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_quality`. -+-----------+-----------------------------+ -| *Default* | ``false`` | -+-----------+-----------------------------+ -| *Setter* | set_proximity_fade(value) | -+-----------+-----------------------------+ -| *Getter* | is_proximity_fade_enabled() | -+-----------+-----------------------------+ +\ **Note:** Subsurface scattering is not supported on viewports that have a transparent background (where :ref:`Viewport.transparent_bg` is ``true``). -If ``true``, the proximity fade effect is enabled. The proximity fade effect fades out each pixel based on its distance to another object. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_refraction_enabled: - -- :ref:`bool` **refraction_enabled** +.. _class_BaseMaterial3D_property_subsurf_scatter_skin_mode: -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ - -If ``true``, the refraction effect is enabled. Distorts transparency based on light from behind the object. +.. rst-class:: classref-property ----- +:ref:`bool` **subsurf_scatter_skin_mode** = ``false`` :ref:`🔗` -.. _class_BaseMaterial3D_property_refraction_scale: +.. rst-class:: classref-property-setget -- :ref:`float` **refraction_scale** +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -+----------+-----------------------+ -| *Setter* | set_refraction(value) | -+----------+-----------------------+ -| *Getter* | get_refraction() | -+----------+-----------------------+ +If ``true``, subsurface scattering will use a special mode optimized for the color and density of human skin, such as boosting the intensity of the red channel in subsurface scattering. -The strength of the refraction effect. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_refraction_texture: +.. _class_BaseMaterial3D_property_subsurf_scatter_strength: -- :ref:`Texture2D` **refraction_texture** +.. rst-class:: classref-property -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +:ref:`float` **subsurf_scatter_strength** = ``0.0`` :ref:`🔗` -Texture that controls the strength of the refraction per-pixel. Multiplied by :ref:`refraction_scale`. +.. rst-class:: classref-property-setget ----- +- |void| **set_subsurface_scattering_strength**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_subsurface_scattering_strength**\ (\ ) -.. _class_BaseMaterial3D_property_refraction_texture_channel: +The strength of the subsurface scattering effect. The depth of the effect is also controlled by :ref:`ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_scale`, which is set globally. -- :ref:`TextureChannel` **refraction_texture_channel** +.. rst-class:: classref-item-separator -+----------+---------------------------------------+ -| *Setter* | set_refraction_texture_channel(value) | -+----------+---------------------------------------+ -| *Getter* | get_refraction_texture_channel() | -+----------+---------------------------------------+ +---- -Specifies the channel of the :ref:`ao_texture` in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. +.. _class_BaseMaterial3D_property_subsurf_scatter_texture: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_rim: +:ref:`Texture2D` **subsurf_scatter_texture** :ref:`🔗` -- :ref:`float` **rim** +.. rst-class:: classref-property-setget -+----------+----------------+ -| *Setter* | set_rim(value) | -+----------+----------------+ -| *Getter* | get_rim() | -+----------+----------------+ +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -Sets the strength of the rim lighting effect. +Texture used to control the subsurface scattering strength. Stored in the red texture channel. Multiplied by :ref:`subsurf_scatter_strength`. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_rim_enabled: +.. _class_BaseMaterial3D_property_subsurf_scatter_transmittance_boost: -- :ref:`bool` **rim_enabled** +.. rst-class:: classref-property -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +:ref:`float` **subsurf_scatter_transmittance_boost** = ``0.0`` :ref:`🔗` -If ``true``, rim effect is enabled. Rim lighting increases the brightness at glancing angles on an object. +.. rst-class:: classref-property-setget ----- +- |void| **set_transmittance_boost**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_transmittance_boost**\ (\ ) -.. _class_BaseMaterial3D_property_rim_texture: +The intensity of the subsurface scattering transmittance effect. -- :ref:`Texture2D` **rim_texture** +.. rst-class:: classref-item-separator -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +---- -Texture used to set the strength of the rim lighting effect per-pixel. Multiplied by :ref:`rim`. +.. _class_BaseMaterial3D_property_subsurf_scatter_transmittance_color: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_rim_tint: +:ref:`Color` **subsurf_scatter_transmittance_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` -- :ref:`float` **rim_tint** +.. rst-class:: classref-property-setget -+----------+---------------------+ -| *Setter* | set_rim_tint(value) | -+----------+---------------------+ -| *Getter* | get_rim_tint() | -+----------+---------------------+ +- |void| **set_transmittance_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_transmittance_color**\ (\ ) -The amount of to blend light and albedo color when rendering rim effect. If ``0`` the light color is used, while ``1`` means albedo color is used. An intermediate value generally works best. +The color to multiply the subsurface scattering transmittance effect with. Ignored if :ref:`subsurf_scatter_skin_mode` is ``true``. + +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_roughness: +.. _class_BaseMaterial3D_property_subsurf_scatter_transmittance_depth: -- :ref:`float` **roughness** +.. rst-class:: classref-property -+-----------+----------------------+ -| *Default* | ``1.0`` | -+-----------+----------------------+ -| *Setter* | set_roughness(value) | -+-----------+----------------------+ -| *Getter* | get_roughness() | -+-----------+----------------------+ +:ref:`float` **subsurf_scatter_transmittance_depth** = ``0.1`` :ref:`🔗` -Surface reflection. A value of ``0`` represents a perfect mirror while a value of ``1`` completely blurs the reflection. See also :ref:`metallic`. +.. rst-class:: classref-property-setget ----- +- |void| **set_transmittance_depth**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_transmittance_depth**\ (\ ) -.. _class_BaseMaterial3D_property_roughness_texture: +The depth of the subsurface scattering transmittance effect. -- :ref:`Texture2D` **roughness_texture** +.. rst-class:: classref-item-separator -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +---- -Texture used to control the roughness per-pixel. Multiplied by :ref:`roughness`. +.. _class_BaseMaterial3D_property_subsurf_scatter_transmittance_enabled: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_roughness_texture_channel: +:ref:`bool` **subsurf_scatter_transmittance_enabled** = ``false`` :ref:`🔗` -- :ref:`TextureChannel` **roughness_texture_channel** +.. rst-class:: classref-property-setget -+-----------+--------------------------------------+ -| *Default* | ``0`` | -+-----------+--------------------------------------+ -| *Setter* | set_roughness_texture_channel(value) | -+-----------+--------------------------------------+ -| *Getter* | get_roughness_texture_channel() | -+-----------+--------------------------------------+ +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -Specifies the channel of the :ref:`ao_texture` in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. +If ``true``, enables subsurface scattering transmittance. Only effective if :ref:`subsurf_scatter_enabled` is ``true``. See also :ref:`backlight_enabled`. ----- +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_property_shading_mode: +---- -- :ref:`ShadingMode` **shading_mode** +.. _class_BaseMaterial3D_property_subsurf_scatter_transmittance_texture: -+-----------+-------------------------+ -| *Default* | ``1`` | -+-----------+-------------------------+ -| *Setter* | set_shading_mode(value) | -+-----------+-------------------------+ -| *Getter* | get_shading_mode() | -+-----------+-------------------------+ +.. rst-class:: classref-property ----- +:ref:`Texture2D` **subsurf_scatter_transmittance_texture** :ref:`🔗` -.. _class_BaseMaterial3D_property_shadow_to_opacity: +.. rst-class:: classref-property-setget -- :ref:`bool` **shadow_to_opacity** +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +The texture to use for multiplying the intensity of the subsurface scattering transmittance intensity. See also :ref:`subsurf_scatter_texture`. Ignored if :ref:`subsurf_scatter_skin_mode` is ``true``. -If ``true``, enables the "shadow to opacity" render mode where lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_specular_mode: - -- :ref:`SpecularMode` **specular_mode** +.. _class_BaseMaterial3D_property_texture_filter: -+-----------+--------------------------+ -| *Default* | ``0`` | -+-----------+--------------------------+ -| *Setter* | set_specular_mode(value) | -+-----------+--------------------------+ -| *Getter* | get_specular_mode() | -+-----------+--------------------------+ +.. rst-class:: classref-property -The method for rendering the specular blob. See :ref:`SpecularMode`. +:ref:`TextureFilter` **texture_filter** = ``3`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_subsurf_scatter_enabled: +- |void| **set_texture_filter**\ (\ value\: :ref:`TextureFilter`\ ) +- :ref:`TextureFilter` **get_texture_filter**\ (\ ) -- :ref:`bool` **subsurf_scatter_enabled** +Filter flags for the texture. -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +\ **Note:** :ref:`heightmap_texture` is always sampled with linear filtering, even if nearest-neighbor filtering is selected here. This is to ensure the heightmap effect looks as intended. If you need sharper height transitions between pixels, resize the heightmap texture in an image editor with nearest-neighbor filtering. -If ``true``, subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_subsurf_scatter_strength: +.. _class_BaseMaterial3D_property_texture_repeat: -- :ref:`float` **subsurf_scatter_strength** +.. rst-class:: classref-property -+----------+-------------------------------------------+ -| *Setter* | set_subsurface_scattering_strength(value) | -+----------+-------------------------------------------+ -| *Getter* | get_subsurface_scattering_strength() | -+----------+-------------------------------------------+ +:ref:`bool` **texture_repeat** = ``true`` :ref:`🔗` -The strength of the subsurface scattering effect. +.. rst-class:: classref-property-setget ----- +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -.. _class_BaseMaterial3D_property_subsurf_scatter_texture: +If ``true``, the texture repeats when exceeding the texture's size. See :ref:`FLAG_USE_TEXTURE_REPEAT`. -- :ref:`Texture2D` **subsurf_scatter_texture** +.. rst-class:: classref-item-separator -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +---- -Texture used to control the subsurface scattering strength. Stored in the red texture channel. Multiplied by :ref:`subsurf_scatter_strength`. +.. _class_BaseMaterial3D_property_transparency: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_texture_filter: +:ref:`Transparency` **transparency** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`TextureFilter` **texture_filter** +- |void| **set_transparency**\ (\ value\: :ref:`Transparency`\ ) +- :ref:`Transparency` **get_transparency**\ (\ ) -+-----------+---------------------------+ -| *Default* | ``3`` | -+-----------+---------------------------+ -| *Setter* | set_texture_filter(value) | -+-----------+---------------------------+ -| *Getter* | get_texture_filter() | -+-----------+---------------------------+ +The material's transparency mode. Some transparency modes will disable shadow casting. Any transparency mode other than :ref:`TRANSPARENCY_DISABLED` has a greater performance impact compared to opaque rendering. See also :ref:`blend_mode`. -Filter flags for the texture. See :ref:`TextureFilter` for options. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_texture_repeat: +.. _class_BaseMaterial3D_property_use_fov_override: -- :ref:`bool` **texture_repeat** +.. rst-class:: classref-property -+-----------+-----------------+ -| *Default* | ``true`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +:ref:`bool` **use_fov_override** = ``false`` :ref:`🔗` -Repeat flags for the texture. See :ref:`TextureFilter` for options. +.. rst-class:: classref-property-setget ----- +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -.. _class_BaseMaterial3D_property_transmission: +If ``true`` use :ref:`fov_override` to override the :ref:`Camera3D`'s field of view angle. -- :ref:`Color` **transmission** +.. rst-class:: classref-item-separator -+----------+-------------------------+ -| *Setter* | set_transmission(value) | -+----------+-------------------------+ -| *Getter* | get_transmission() | -+----------+-------------------------+ +---- -The color used by the transmission effect. Represents the light passing through an object. +.. _class_BaseMaterial3D_property_use_particle_trails: ----- +.. rst-class:: classref-property -.. _class_BaseMaterial3D_property_transmission_enabled: +:ref:`bool` **use_particle_trails** = ``false`` :ref:`🔗` -- :ref:`bool` **transmission_enabled** +.. rst-class:: classref-property-setget -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_feature(value) | -+-----------+--------------------+ -| *Getter* | get_feature() | -+-----------+--------------------+ +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -If ``true``, the transmission effect is enabled. +If ``true``, enables parts of the shader required for :ref:`GPUParticles3D` trails to function. This also requires using a mesh with appropriate skinning, such as :ref:`RibbonTrailMesh` or :ref:`TubeTrailMesh`. Enabling this feature outside of materials used in :ref:`GPUParticles3D` meshes will break material rendering. ----- +.. rst-class:: classref-item-separator -.. _class_BaseMaterial3D_property_transmission_texture: +---- -- :ref:`Texture2D` **transmission_texture** +.. _class_BaseMaterial3D_property_use_point_size: -+----------+--------------------+ -| *Setter* | set_texture(value) | -+----------+--------------------+ -| *Getter* | get_texture() | -+----------+--------------------+ +.. rst-class:: classref-property -Texture used to control the transmission effect per-pixel. Added to :ref:`transmission`. +:ref:`bool` **use_point_size** = ``false`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BaseMaterial3D_property_transparency: +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -- :ref:`Transparency` **transparency** +If ``true``, render point size can be changed. -+-----------+-------------------------+ -| *Default* | ``0`` | -+-----------+-------------------------+ -| *Setter* | set_transparency(value) | -+-----------+-------------------------+ -| *Getter* | get_transparency() | -+-----------+-------------------------+ +\ **Note:** This is only effective for objects whose geometry is point-based rather than triangle-based. See also :ref:`point_size`. -If ``true``, transparency is enabled on the body. See also :ref:`blend_mode`. +.. rst-class:: classref-item-separator ---- -.. _class_BaseMaterial3D_property_use_point_size: +.. _class_BaseMaterial3D_property_use_z_clip_scale: -- :ref:`bool` **use_point_size** +.. rst-class:: classref-property -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +:ref:`bool` **use_z_clip_scale** = ``false`` :ref:`🔗` -If ``true``, render point size can be changed. +.. rst-class:: classref-property-setget -**Note:** this is only effective for objects whose geometry is point-based rather than triangle-based. See also :ref:`point_size`. +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +If ``true`` use :ref:`z_clip_scale` to scale the object being rendered towards the camera to avoid clipping into things like walls. + +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_property_uv1_offset: -- :ref:`Vector3` **uv1_offset** +.. rst-class:: classref-property + +:ref:`Vector3` **uv1_offset** = ``Vector3(0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``Vector3( 0, 0, 0 )`` | -+-----------+------------------------+ -| *Setter* | set_uv1_offset(value) | -+-----------+------------------------+ -| *Getter* | get_uv1_offset() | -+-----------+------------------------+ +- |void| **set_uv1_offset**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_uv1_offset**\ (\ ) -How much to offset the ``UV`` coordinates. This amount will be added to ``UV`` in the vertex function. This can be used to offset a texture. +How much to offset the ``UV`` coordinates. This amount will be added to ``UV`` in the vertex function. This can be used to offset a texture. The Z component is used when :ref:`uv1_triplanar` is enabled, but it is not used anywhere else. + +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_property_uv1_scale: -- :ref:`Vector3` **uv1_scale** +.. rst-class:: classref-property + +:ref:`Vector3` **uv1_scale** = ``Vector3(1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_uv1_scale**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_uv1_scale**\ (\ ) -+-----------+------------------------+ -| *Default* | ``Vector3( 1, 1, 1 )`` | -+-----------+------------------------+ -| *Setter* | set_uv1_scale(value) | -+-----------+------------------------+ -| *Getter* | get_uv1_scale() | -+-----------+------------------------+ +How much to scale the ``UV`` coordinates. This is multiplied by ``UV`` in the vertex function. The Z component is used when :ref:`uv1_triplanar` is enabled, but it is not used anywhere else. -How much to scale the ``UV`` coordinates. This is multiplied by ``UV`` in the vertex function. +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_property_uv1_triplanar: -- :ref:`bool` **uv1_triplanar** +.. rst-class:: classref-property -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +:ref:`bool` **uv1_triplanar** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| If ``true``, instead of using ``UV`` textures will use a triplanar texture lookup to determine how to apply textures. Triplanar uses the orientation of the object's surface to blend between texture coordinates. It reads from the source texture 3 times, once for each axis and then blends between the results based on how closely the pixel aligns with each axis. This is often used for natural features to get a realistic blend of materials. Because triplanar texturing requires many more texture reads per-pixel it is much slower than normal UV texturing. Additionally, because it is blending the texture between the three axes, it is unsuitable when you are trying to achieve crisp texturing. +.. rst-class:: classref-item-separator + ---- .. _class_BaseMaterial3D_property_uv1_triplanar_sharpness: -- :ref:`float` **uv1_triplanar_sharpness** +.. rst-class:: classref-property + +:ref:`float` **uv1_triplanar_sharpness** = ``1.0`` :ref:`🔗` -+-----------+------------------------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------------------------+ -| *Setter* | set_uv1_triplanar_blend_sharpness(value) | -+-----------+------------------------------------------+ -| *Getter* | get_uv1_triplanar_blend_sharpness() | -+-----------+------------------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_uv1_triplanar_blend_sharpness**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_uv1_triplanar_blend_sharpness**\ (\ ) A lower number blends the texture more softly while a higher number blends the texture more sharply. +\ **Note:** :ref:`uv1_triplanar_sharpness` is clamped between ``0.0`` and ``150.0`` (inclusive) as values outside that range can look broken depending on the mesh. + +.. rst-class:: classref-item-separator + ---- .. _class_BaseMaterial3D_property_uv1_world_triplanar: -- :ref:`bool` **uv1_world_triplanar** +.. rst-class:: classref-property + +:ref:`bool` **uv1_world_triplanar** = ``false`` :ref:`🔗` -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| If ``true``, triplanar mapping for ``UV`` is calculated in world space rather than object local space. See also :ref:`uv1_triplanar`. +.. rst-class:: classref-item-separator + ---- .. _class_BaseMaterial3D_property_uv2_offset: -- :ref:`Vector3` **uv2_offset** +.. rst-class:: classref-property + +:ref:`Vector3` **uv2_offset** = ``Vector3(0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``Vector3( 0, 0, 0 )`` | -+-----------+------------------------+ -| *Setter* | set_uv2_offset(value) | -+-----------+------------------------+ -| *Getter* | get_uv2_offset() | -+-----------+------------------------+ +- |void| **set_uv2_offset**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_uv2_offset**\ (\ ) -How much to offset the ``UV2`` coordinates. This amount will be added to ``UV2`` in the vertex function. This can be used to offset a texture. +How much to offset the ``UV2`` coordinates. This amount will be added to ``UV2`` in the vertex function. This can be used to offset a texture. The Z component is used when :ref:`uv2_triplanar` is enabled, but it is not used anywhere else. + +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_property_uv2_scale: -- :ref:`Vector3` **uv2_scale** +.. rst-class:: classref-property + +:ref:`Vector3` **uv2_scale** = ``Vector3(1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_uv2_scale**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_uv2_scale**\ (\ ) -+-----------+------------------------+ -| *Default* | ``Vector3( 1, 1, 1 )`` | -+-----------+------------------------+ -| *Setter* | set_uv2_scale(value) | -+-----------+------------------------+ -| *Getter* | get_uv2_scale() | -+-----------+------------------------+ +How much to scale the ``UV2`` coordinates. This is multiplied by ``UV2`` in the vertex function. The Z component is used when :ref:`uv2_triplanar` is enabled, but it is not used anywhere else. -How much to scale the ``UV2`` coordinates. This is multiplied by ``UV2`` in the vertex function. +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_property_uv2_triplanar: -- :ref:`bool` **uv2_triplanar** +.. rst-class:: classref-property -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +:ref:`bool` **uv2_triplanar** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| If ``true``, instead of using ``UV2`` textures will use a triplanar texture lookup to determine how to apply textures. Triplanar uses the orientation of the object's surface to blend between texture coordinates. It reads from the source texture 3 times, once for each axis and then blends between the results based on how closely the pixel aligns with each axis. This is often used for natural features to get a realistic blend of materials. Because triplanar texturing requires many more texture reads per-pixel it is much slower than normal UV texturing. Additionally, because it is blending the texture between the three axes, it is unsuitable when you are trying to achieve crisp texturing. +.. rst-class:: classref-item-separator + ---- .. _class_BaseMaterial3D_property_uv2_triplanar_sharpness: -- :ref:`float` **uv2_triplanar_sharpness** +.. rst-class:: classref-property + +:ref:`float` **uv2_triplanar_sharpness** = ``1.0`` :ref:`🔗` -+-----------+------------------------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------------------------+ -| *Setter* | set_uv2_triplanar_blend_sharpness(value) | -+-----------+------------------------------------------+ -| *Getter* | get_uv2_triplanar_blend_sharpness() | -+-----------+------------------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_uv2_triplanar_blend_sharpness**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_uv2_triplanar_blend_sharpness**\ (\ ) A lower number blends the texture more softly while a higher number blends the texture more sharply. +\ **Note:** :ref:`uv2_triplanar_sharpness` is clamped between ``0.0`` and ``150.0`` (inclusive) as values outside that range can look broken depending on the mesh. + +.. rst-class:: classref-item-separator + ---- .. _class_BaseMaterial3D_property_uv2_world_triplanar: -- :ref:`bool` **uv2_world_triplanar** +.. rst-class:: classref-property + +:ref:`bool` **uv2_world_triplanar** = ``false`` :ref:`🔗` -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| If ``true``, triplanar mapping for ``UV2`` is calculated in world space rather than object local space. See also :ref:`uv2_triplanar`. +.. rst-class:: classref-item-separator + ---- .. _class_BaseMaterial3D_property_vertex_color_is_srgb: -- :ref:`bool` **vertex_color_is_srgb** +.. rst-class:: classref-property + +:ref:`bool` **vertex_color_is_srgb** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -If ``true``, the model's vertex colors are processed as sRGB mode. +If ``true``, vertex colors are considered to be stored in nonlinear sRGB encoding and are converted to linear encoding during rendering. If ``false``, vertex colors are considered to be stored in linear encoding and are rendered as-is. See also :ref:`albedo_texture_force_srgb`. + +\ **Note:** Only effective when using the Forward+ and Mobile rendering methods, not Compatibility. + +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_property_vertex_color_use_as_albedo: -- :ref:`bool` **vertex_color_use_as_albedo** +.. rst-class:: classref-property + +:ref:`bool` **vertex_color_use_as_albedo** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flag(value) | -+-----------+-----------------+ -| *Getter* | get_flag() | -+-----------+-----------------+ +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| If ``true``, the vertex color is used as albedo color. +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_z_clip_scale: + +.. rst-class:: classref-property + +:ref:`float` **z_clip_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_z_clip_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_z_clip_scale**\ (\ ) + +Scales the object being rendered towards the camera to avoid clipping into things like walls. This is intended to be used for objects that are fixed with respect to the camera like player arms, tools, etc. Lighting and shadows will continue to work correctly when this setting is adjusted, but screen-space effects like SSAO and SSR may break with lower scales. Therefore, try to keep this setting as close to ``1.0`` as possible. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- .. _class_BaseMaterial3D_method_get_feature: -- :ref:`bool` **get_feature** **(** :ref:`Feature` feature **)** const +.. rst-class:: classref-method + +:ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| :ref:`🔗` Returns ``true``, if the specified :ref:`Feature` is enabled. +.. rst-class:: classref-item-separator + ---- .. _class_BaseMaterial3D_method_get_flag: -- :ref:`bool` **get_flag** **(** :ref:`Flags` flag **)** const +.. rst-class:: classref-method + +:ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| :ref:`🔗` -Returns ``true``, if the specified flag is enabled. See :ref:`Flags` enumerator for options. +Returns ``true`` if the specified flag is enabled. + +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_method_get_texture: -- :ref:`Texture2D` **get_texture** **(** :ref:`TextureParam` param **)** const +.. rst-class:: classref-method + +:ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| :ref:`🔗` -Returns the :ref:`Texture` associated with the specified :ref:`TextureParam`. +Returns the :ref:`Texture2D` associated with the specified :ref:`TextureParam`. + +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_method_set_feature: -- void **set_feature** **(** :ref:`Feature` feature, :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) :ref:`🔗` -If ``true``, enables the specified :ref:`Feature`. Many features that are available in ``BaseMaterial3D``\ s need to be enabled before use. This way the cost for using the feature is only incurred when specified. Features can also be enabled by setting the corresponding member to ``true``. +If ``true``, enables the specified :ref:`Feature`. Many features that are available in **BaseMaterial3D**\ s need to be enabled before use. This way the cost for using the feature is only incurred when specified. Features can also be enabled by setting the corresponding member to ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_method_set_flag: -- void **set_flag** **(** :ref:`Flags` flag, :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) :ref:`🔗` -If ``true``, enables the specified flag. Flags are optional behavior that can be turned on and off. Only one flag can be enabled at a time with this function, the flag enumerators cannot be bit-masked together to enable or disable multiple flags at once. Flags can also be enabled by setting the corresponding member to ``true``. See :ref:`Flags` enumerator for options. +If ``true``, enables the specified flag. Flags are optional behavior that can be turned on and off. Only one flag can be enabled at a time with this function, the flag enumerators cannot be bit-masked together to enable or disable multiple flags at once. Flags can also be enabled by setting the corresponding member to ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_BaseMaterial3D_method_set_texture: -- void **set_texture** **(** :ref:`TextureParam` param, :ref:`Texture2D` texture **)** +.. rst-class:: classref-method + +|void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) :ref:`🔗` -Sets the texture for the slot specified by ``param``. See :ref:`TextureParam` for available slots. +Sets the texture for the slot specified by ``param``. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_basis.rst b/classes/class_basis.rst index 687988e80db..b2cc9b74019 100644 --- a/classes/class_basis.rst +++ b/classes/class_basis.rst @@ -1,304 +1,1027 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Basis.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Basis.xml. .. _class_Basis: Basis ===== -3×3 matrix datatype. +A 3×3 matrix for representing 3D rotation and scale. + +.. rst-class:: classref-introduction-group Description ----------- -3×3 matrix used for 3D rotation and scale. Contains 3 vector fields X, Y and Z as its columns, which can be interpreted as the local basis vectors of a transformation. Can also be accessed as array of 3D vectors. These vectors are orthogonal to each other, but are not necessarily normalized (due to scaling). Almost always used as an orthogonal basis for a :ref:`Transform`. +The **Basis** built-in :ref:`Variant` type is a 3×3 `matrix `__ used to represent 3D rotation, scale, and shear. It is frequently used within a :ref:`Transform3D`. + +A **Basis** is composed by 3 axis vectors, each representing a column of the matrix: :ref:`x`, :ref:`y`, and :ref:`z`. The length of each axis (:ref:`Vector3.length()`) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted. + +A **Basis** is: + +- **Orthogonal** if its axes are perpendicular to each other. + +- **Normalized** if the length of every axis is ``1.0``. + +- **Uniform** if all axes share the same length (see :ref:`get_scale()`). + +- **Orthonormal** if it is both orthogonal and normalized, which allows it to only represent rotations (see :ref:`orthonormalized()`). + +- **Conformal** if it is both orthogonal and uniform, which ensures it is not distorted. + +For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. + +\ **Note:** Godot uses a `right-handed coordinate system `__, which is a common standard. For directions, the convention for built-in types like :ref:`Camera3D` is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the `3D asset direction conventions <../tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.html#d-asset-direction-conventions>`__ tutorial. + +\ **Note:** The basis matrices are exposed as `column-major `__ order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX. -For such use, it is composed of a scaling and a rotation matrix, in that order (M = R.S). +.. note:: + + There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/3d/using_transforms` +- :doc:`Math documentation index <../tutorials/math/index>` + +- :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` + +- :doc:`Using 3D transforms <../tutorials/3d/using_transforms>` + +- `Matrix Transform Demo `__ + +- `3D Platformer Demo `__ + +- `3D Voxel Demo `__ + +- `2.5D Game Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------------+----------------------------------+------------------------+ -| :ref:`Vector3` | :ref:`x` | ``Vector3( 1, 0, 0 )`` | -+-------------------------------+----------------------------------+------------------------+ -| :ref:`Vector3` | :ref:`y` | ``Vector3( 0, 1, 0 )`` | -+-------------------------------+----------------------------------+------------------------+ -| :ref:`Vector3` | :ref:`z` | ``Vector3( 0, 0, 1 )`` | -+-------------------------------+----------------------------------+------------------------+ +.. table:: + :widths: auto + + +-------------------------------+----------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`x` | ``Vector3(1, 0, 0)`` | + +-------------------------------+----------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`y` | ``Vector3(0, 1, 0)`` | + +-------------------------------+----------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`z` | ``Vector3(0, 0, 1)`` | + +-------------------------------+----------------------------------+----------------------+ + +.. rst-class:: classref-reftable-group + +Constructors +------------ + +.. table:: + :widths: auto + + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`Basis`\ (\ ) | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`Basis`\ (\ from\: :ref:`Basis`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`Basis`\ (\ axis\: :ref:`Vector3`, angle\: :ref:`float`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`Basis`\ (\ from\: :ref:`Quaternion`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`Basis`\ (\ x_axis\: :ref:`Vector3`, y_axis\: :ref:`Vector3`, z_axis\: :ref:`Vector3`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`Basis` **(** :ref:`Quat` from **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`Basis` **(** :ref:`Vector3` from **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`Basis` **(** :ref:`Vector3` axis, :ref:`float` phi **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`Basis` **(** :ref:`Vector3` x_axis, :ref:`Vector3` y_axis, :ref:`Vector3` z_axis **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`determinant` **(** **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_euler` **(** **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_orthogonal_index` **(** **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Quat` | :ref:`get_rotation_quat` **(** **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`get_scale` **(** **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`inverse` **(** **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_equal_approx` **(** :ref:`Basis` b, :ref:`float` epsilon=1e-05 **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`orthonormalized` **(** **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`rotated` **(** :ref:`Vector3` axis, :ref:`float` phi **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`scaled` **(** :ref:`Vector3` scale **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`slerp` **(** :ref:`Basis` b, :ref:`float` t **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`tdotx` **(** :ref:`Vector3` with **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`tdoty` **(** :ref:`Vector3` with **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`tdotz` **(** :ref:`Vector3` with **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Basis` | :ref:`transposed` **(** **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`xform` **(** :ref:`Vector3` v **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`xform_inv` **(** :ref:`Vector3` v **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`determinant`\ (\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`from_euler`\ (\ euler\: :ref:`Vector3`, order\: :ref:`int` = 2\ ) |static| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`from_scale`\ (\ scale\: :ref:`Vector3`\ ) |static| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_euler`\ (\ order\: :ref:`int` = 2\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Quaternion` | :ref:`get_rotation_quaternion`\ (\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_scale`\ (\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`inverse`\ (\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_conformal`\ (\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_equal_approx`\ (\ b\: :ref:`Basis`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_finite`\ (\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`looking_at`\ (\ target\: :ref:`Vector3`, up\: :ref:`Vector3` = Vector3(0, 1, 0), use_model_front\: :ref:`bool` = false\ ) |static| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`orthonormalized`\ (\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`rotated`\ (\ axis\: :ref:`Vector3`, angle\: :ref:`float`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`scaled`\ (\ scale\: :ref:`Vector3`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`scaled_local`\ (\ scale\: :ref:`Vector3`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`slerp`\ (\ to\: :ref:`Basis`, weight\: :ref:`float`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`tdotx`\ (\ with\: :ref:`Vector3`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`tdoty`\ (\ with\: :ref:`Vector3`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`tdotz`\ (\ with\: :ref:`Vector3`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`transposed`\ (\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Operators +--------- + +.. table:: + :widths: auto + + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator !=`\ (\ right\: :ref:`Basis`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`operator *`\ (\ right\: :ref:`Basis`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`operator *`\ (\ right\: :ref:`Vector3`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`operator *`\ (\ right\: :ref:`float`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`operator *`\ (\ right\: :ref:`int`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`operator /`\ (\ right\: :ref:`float`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`operator /`\ (\ right\: :ref:`int`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator ==`\ (\ right\: :ref:`Basis`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`operator []`\ (\ index\: :ref:`int`\ ) | + +-------------------------------+--------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Constants --------- .. _class_Basis_constant_IDENTITY: +.. rst-class:: classref-constant + +**IDENTITY** = ``Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)`` :ref:`🔗` + +The identity **Basis**. This is an orthonormal basis with no rotation, no shear, and a scale of :ref:`Vector3.ONE`. This also means that: + +- The :ref:`x` points right (:ref:`Vector3.RIGHT`); + +- The :ref:`y` points up (:ref:`Vector3.UP`); + +- The :ref:`z` points back (:ref:`Vector3.BACK`). + +:: + + var basis = Basis.IDENTITY + print("| X | Y | Z") + print("| %.f | %.f | %.f" % [basis.x.x, basis.y.x, basis.z.x]) + print("| %.f | %.f | %.f" % [basis.x.y, basis.y.y, basis.z.y]) + print("| %.f | %.f | %.f" % [basis.x.z, basis.y.z, basis.z.z]) + # Prints: + # | X | Y | Z + # | 1 | 0 | 0 + # | 0 | 1 | 0 + # | 0 | 0 | 1 + +If a :ref:`Vector3` or another **Basis** is transformed (multiplied) by this constant, no transformation occurs. + +\ **Note:** In GDScript, this constant is equivalent to creating a :ref:`Basis` without any arguments. It can be used to make your code clearer, and for consistency with C#. + .. _class_Basis_constant_FLIP_X: +.. rst-class:: classref-constant + +**FLIP_X** = ``Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1)`` :ref:`🔗` + +When any basis is multiplied by :ref:`FLIP_X`, it negates all components of the :ref:`x` axis (the X column). + +When :ref:`FLIP_X` is multiplied by any basis, it negates the :ref:`Vector3.x` component of all axes (the X row). + .. _class_Basis_constant_FLIP_Y: +.. rst-class:: classref-constant + +**FLIP_Y** = ``Basis(1, 0, 0, 0, -1, 0, 0, 0, 1)`` :ref:`🔗` + +When any basis is multiplied by :ref:`FLIP_Y`, it negates all components of the :ref:`y` axis (the Y column). + +When :ref:`FLIP_Y` is multiplied by any basis, it negates the :ref:`Vector3.y` component of all axes (the Y row). + .. _class_Basis_constant_FLIP_Z: -- **IDENTITY** = **Basis( 1, 0, 0, 0, 1, 0, 0, 0, 1 )** --- The identity basis. This is identical to calling ``Basis()`` without any parameters. This constant can be used to make your code clearer. +.. rst-class:: classref-constant + +**FLIP_Z** = ``Basis(1, 0, 0, 0, 1, 0, 0, 0, -1)`` :ref:`🔗` -- **FLIP_X** = **Basis( -1, 0, 0, 0, 1, 0, 0, 0, 1 )** --- The basis that will flip something along the X axis when used in a transformation. +When any basis is multiplied by :ref:`FLIP_Z`, it negates all components of the :ref:`z` axis (the Z column). -- **FLIP_Y** = **Basis( 1, 0, 0, 0, -1, 0, 0, 0, 1 )** --- The basis that will flip something along the Y axis when used in a transformation. +When :ref:`FLIP_Z` is multiplied by any basis, it negates the :ref:`Vector3.z` component of all axes (the Z row). -- **FLIP_Z** = **Basis( 1, 0, 0, 0, 1, 0, 0, 0, -1 )** --- The basis that will flip something along the Z axis when used in a transformation. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_Basis_property_x: -- :ref:`Vector3` **x** +.. rst-class:: classref-property + +:ref:`Vector3` **x** = ``Vector3(1, 0, 0)`` :ref:`🔗` + +The basis's X axis, and the column ``0`` of the matrix. -+-----------+------------------------+ -| *Default* | ``Vector3( 1, 0, 0 )`` | -+-----------+------------------------+ +On the identity basis, this vector points right (:ref:`Vector3.RIGHT`). -The basis matrix's X vector. +.. rst-class:: classref-item-separator ---- .. _class_Basis_property_y: -- :ref:`Vector3` **y** +.. rst-class:: classref-property + +:ref:`Vector3` **y** = ``Vector3(0, 1, 0)`` :ref:`🔗` + +The basis's Y axis, and the column ``1`` of the matrix. -+-----------+------------------------+ -| *Default* | ``Vector3( 0, 1, 0 )`` | -+-----------+------------------------+ +On the identity basis, this vector points up (:ref:`Vector3.UP`). -The basis matrix's Y vector. +.. rst-class:: classref-item-separator ---- .. _class_Basis_property_z: -- :ref:`Vector3` **z** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``Vector3( 0, 0, 1 )`` | -+-----------+------------------------+ +:ref:`Vector3` **z** = ``Vector3(0, 0, 1)`` :ref:`🔗` -The basis matrix's Z vector. +The basis's Z axis, and the column ``2`` of the matrix. -Method Descriptions -------------------- +On the identity basis, this vector points back (:ref:`Vector3.BACK`). + +.. rst-class:: classref-section-separator + +---- -.. _class_Basis_method_Basis: +.. rst-class:: classref-descriptions-group -- :ref:`Basis` **Basis** **(** :ref:`Quat` from **)** +Constructor Descriptions +------------------------ -Create a rotation matrix from the given quaternion. +.. _class_Basis_constructor_Basis: + +.. rst-class:: classref-constructor + +:ref:`Basis` **Basis**\ (\ ) :ref:`🔗` + +Constructs a **Basis** identical to :ref:`IDENTITY`. + +\ **Note:** In C#, this constructs a **Basis** with all of its components set to :ref:`Vector3.ZERO`. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`Basis` **Basis**\ (\ from\: :ref:`Basis`\ ) + +Constructs a **Basis** as a copy of the given **Basis**. + +.. rst-class:: classref-item-separator ---- -- :ref:`Basis` **Basis** **(** :ref:`Vector3` from **)** +.. rst-class:: classref-constructor + +:ref:`Basis` **Basis**\ (\ axis\: :ref:`Vector3`, angle\: :ref:`float`\ ) + +Constructs a **Basis** that only represents rotation, rotated around the ``axis`` by the given ``angle``, in radians. The axis must be a normalized vector. -Create a rotation matrix (in the YXZ convention: first Z, then X, and Y last) from the specified Euler angles, given in the vector format as (X angle, Y angle, Z angle). +\ **Note:** This is the same as using :ref:`rotated()` on the :ref:`IDENTITY` basis. With more than one angle consider using :ref:`from_euler()`, instead. + +.. rst-class:: classref-item-separator ---- -- :ref:`Basis` **Basis** **(** :ref:`Vector3` axis, :ref:`float` phi **)** +.. rst-class:: classref-constructor + +:ref:`Basis` **Basis**\ (\ from\: :ref:`Quaternion`\ ) -Create a rotation matrix which rotates around the given axis by the specified angle, in radians. The axis must be a normalized vector. +Constructs a **Basis** that only represents rotation from the given :ref:`Quaternion`. + +\ **Note:** Quaternions *only* store rotation, not scale. Because of this, conversions from **Basis** to :ref:`Quaternion` cannot always be reversed. + +.. rst-class:: classref-item-separator ---- -- :ref:`Basis` **Basis** **(** :ref:`Vector3` x_axis, :ref:`Vector3` y_axis, :ref:`Vector3` z_axis **)** +.. rst-class:: classref-constructor + +:ref:`Basis` **Basis**\ (\ x_axis\: :ref:`Vector3`, y_axis\: :ref:`Vector3`, z_axis\: :ref:`Vector3`\ ) -Create a matrix from 3 axis vectors. +Constructs a **Basis** from 3 axis vectors. These are the columns of the basis matrix. + +.. rst-class:: classref-section-separator ---- +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + .. _class_Basis_method_determinant: -- :ref:`float` **determinant** **(** **)** +.. rst-class:: classref-method + +:ref:`float` **determinant**\ (\ ) |const| :ref:`🔗` + +Returns the `determinant `__ of this basis's matrix. For advanced math, this number can be used to determine a few attributes: + +- If the determinant is exactly ``0.0``, the basis is not invertible (see :ref:`inverse()`). -Returns the determinant of the matrix. +- If the determinant is a negative number, the basis represents a negative scale. + +\ **Note:** If the basis's scale is the same for every axis, its determinant is always that scale by the power of 3. + +.. rst-class:: classref-item-separator ---- -.. _class_Basis_method_get_euler: +.. _class_Basis_method_from_euler: + +.. rst-class:: classref-method + +:ref:`Basis` **from_euler**\ (\ euler\: :ref:`Vector3`, order\: :ref:`int` = 2\ ) |static| :ref:`🔗` + +Constructs a new **Basis** that only represents rotation from the given :ref:`Vector3` of `Euler angles `__, in radians. + +- The :ref:`Vector3.x` should contain the angle around the :ref:`x` axis (pitch); + +- The :ref:`Vector3.y` should contain the angle around the :ref:`y` axis (yaw); + +- The :ref:`Vector3.z` should contain the angle around the :ref:`z` axis (roll). + + +.. tabs:: + + .. code-tab:: gdscript + + # Creates a Basis whose z axis points down. + var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0)) + + print(my_basis.z) # Prints (0.0, -1.0, 0.0) + + .. code-tab:: csharp + + // Creates a Basis whose z axis points down. + var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f)); + + GD.Print(myBasis.Z); // Prints (0, -1, 0) + + + +The order of each consecutive rotation can be changed with ``order`` (see :ref:`EulerOrder` constants). By default, the YXZ convention is used (:ref:`@GlobalScope.EULER_ORDER_YXZ`): the basis rotates first around the Y axis (yaw), then X (pitch), and lastly Z (roll). When using the opposite method :ref:`get_euler()`, this order is reversed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_method_from_scale: + +.. rst-class:: classref-method + +:ref:`Basis` **from_scale**\ (\ scale\: :ref:`Vector3`\ ) |static| :ref:`🔗` + +Constructs a new **Basis** that only represents scale, with no rotation or shear, from the given ``scale`` vector. + + +.. tabs:: + + .. code-tab:: gdscript + + var my_basis = Basis.from_scale(Vector3(2, 4, 8)) + + print(my_basis.x) # Prints (2.0, 0.0, 0.0) + print(my_basis.y) # Prints (0.0, 4.0, 0.0) + print(my_basis.z) # Prints (0.0, 0.0, 8.0) + + .. code-tab:: csharp + + var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f)); + + GD.Print(myBasis.X); // Prints (2, 0, 0) + GD.Print(myBasis.Y); // Prints (0, 4, 0) + GD.Print(myBasis.Z); // Prints (0, 0, 8) -- :ref:`Vector3` **get_euler** **(** **)** -Returns the basis's rotation in the form of Euler angles (in the YXZ convention: first Z, then X, and Y last). The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle). See :ref:`get_rotation_quat` if you need a quaternion instead. + +\ **Note:** In linear algebra, the matrix of this basis is also known as a `diagonal matrix `__. + +.. rst-class:: classref-item-separator ---- -.. _class_Basis_method_get_orthogonal_index: +.. _class_Basis_method_get_euler: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_euler**\ (\ order\: :ref:`int` = 2\ ) |const| :ref:`🔗` + +Returns this basis's rotation as a :ref:`Vector3` of `Euler angles `__, in radians. For the returned value: + +- The :ref:`Vector3.x` contains the angle around the :ref:`x` axis (pitch); + +- The :ref:`Vector3.y` contains the angle around the :ref:`y` axis (yaw); + +- The :ref:`Vector3.z` contains the angle around the :ref:`z` axis (roll). + +The order of each consecutive rotation can be changed with ``order`` (see :ref:`EulerOrder` constants). By default, the YXZ convention is used (:ref:`@GlobalScope.EULER_ORDER_YXZ`): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method :ref:`from_euler()`, this order is reversed. + +\ **Note:** For this method to return correctly, the basis needs to be *orthonormal* (see :ref:`orthonormalized()`). -- :ref:`int` **get_orthogonal_index** **(** **)** +\ **Note:** Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the :ref:`get_rotation_quaternion()` method instead, which returns a :ref:`Quaternion`. -This function considers a discretization of rotations into 24 points on unit sphere, lying along the vectors (x,y,z) with each component being either -1, 0, or 1, and returns the index of the point best representing the orientation of the object. It is mainly used by the grid map editor. For further details, refer to the Godot source code. +\ **Note:** In the Inspector dock, a basis's rotation is often displayed in Euler angles (in degrees), as is the case with the :ref:`Node3D.rotation` property. + +.. rst-class:: classref-item-separator ---- -.. _class_Basis_method_get_rotation_quat: +.. _class_Basis_method_get_rotation_quaternion: + +.. rst-class:: classref-method + +:ref:`Quaternion` **get_rotation_quaternion**\ (\ ) |const| :ref:`🔗` -- :ref:`Quat` **get_rotation_quat** **(** **)** +Returns this basis's rotation as a :ref:`Quaternion`. -Returns the basis's rotation in the form of a quaternion. See :ref:`get_euler` if you need Euler angles, but keep in mind quaternions should generally be preferred to Euler angles. +\ **Note:** Quaternions are much more suitable for 3D math but are less intuitive. For user interfaces, consider using the :ref:`get_euler()` method, which returns Euler angles. + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_get_scale: -- :ref:`Vector3` **get_scale** **(** **)** +.. rst-class:: classref-method + +:ref:`Vector3` **get_scale**\ (\ ) |const| :ref:`🔗` + +Returns the length of each axis of this basis, as a :ref:`Vector3`. If the basis is not sheared, this value is the scaling factor. It is not affected by rotation. + + +.. tabs:: + + .. code-tab:: gdscript + + var my_basis = Basis( + Vector3(2, 0, 0), + Vector3(0, 4, 0), + Vector3(0, 0, 8) + ) + # Rotating the Basis in any way preserves its scale. + my_basis = my_basis.rotated(Vector3.UP, TAU / 2) + my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4) -Assuming that the matrix is the combination of a rotation and scaling, return the absolute value of scaling factors along each axis. + print(my_basis.get_scale()) # Prints (2.0, 4.0, 8.0) + + .. code-tab:: csharp + + var myBasis = new Basis( + Vector3(2.0f, 0.0f, 0.0f), + Vector3(0.0f, 4.0f, 0.0f), + Vector3(0.0f, 0.0f, 8.0f) + ); + // Rotating the Basis in any way preserves its scale. + myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f); + myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f); + + GD.Print(myBasis.Scale); // Prints (2, 4, 8) + + + +\ **Note:** If the value returned by :ref:`determinant()` is negative, the scale is also negative. + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_inverse: -- :ref:`Basis` **inverse** **(** **)** +.. rst-class:: classref-method + +:ref:`Basis` **inverse**\ (\ ) |const| :ref:`🔗` + +Returns the `inverse of this basis's matrix `__. + +.. rst-class:: classref-item-separator -Returns the inverse of the matrix. +---- + +.. _class_Basis_method_is_conformal: + +.. rst-class:: classref-method + +:ref:`bool` **is_conformal**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if this basis is conformal. A conformal basis is both *orthogonal* (the axes are perpendicular to each other) and *uniform* (the axes share the same length). This method can be especially useful during physics calculations. + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_is_equal_approx: -- :ref:`bool` **is_equal_approx** **(** :ref:`Basis` b, :ref:`float` epsilon=1e-05 **)** +.. rst-class:: classref-method + +:ref:`bool` **is_equal_approx**\ (\ b\: :ref:`Basis`\ ) |const| :ref:`🔗` + +Returns ``true`` if this basis and ``b`` are approximately equal, by calling :ref:`@GlobalScope.is_equal_approx()` on all vector components. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_method_is_finite: + +.. rst-class:: classref-method -Returns ``true`` if this basis and ``b`` are approximately equal, by calling ``is_equal_approx`` on each component. +:ref:`bool` **is_finite**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if this basis is finite, by calling :ref:`@GlobalScope.is_finite()` on all vector components. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_method_looking_at: + +.. rst-class:: classref-method + +:ref:`Basis` **looking_at**\ (\ target\: :ref:`Vector3`, up\: :ref:`Vector3` = Vector3(0, 1, 0), use_model_front\: :ref:`bool` = false\ ) |static| :ref:`🔗` + +Creates a new **Basis** with a rotation such that the forward axis (-Z) points towards the ``target`` position. + +By default, the -Z axis (camera forward) is treated as forward (implies +X is right). If ``use_model_front`` is ``true``, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the ``target`` position. + +The up axis (+Y) points as close to the ``up`` vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see :ref:`orthonormalized()`). + +The ``target`` and the ``up`` cannot be :ref:`Vector3.ZERO`, and shouldn't be colinear to avoid unintended rotation around local Z axis. + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_orthonormalized: -- :ref:`Basis` **orthonormalized** **(** **)** +.. rst-class:: classref-method + +:ref:`Basis` **orthonormalized**\ (\ ) |const| :ref:`🔗` + +Returns the orthonormalized version of this basis. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1.0``), which also means it can only represent a rotation. + +It is often useful to call this method to avoid rounding errors on a rotating basis: + + +.. tabs:: + + .. code-tab:: gdscript -Returns the orthonormalized version of the matrix (useful to call from time to time to avoid rounding error for orthogonal matrices). This performs a Gram-Schmidt orthonormalization on the basis of the matrix. + # Rotate this Node3D every frame. + func _process(delta): + basis = basis.rotated(Vector3.UP, TAU * delta) + basis = basis.rotated(Vector3.RIGHT, TAU * delta) + basis = basis.orthonormalized() + + .. code-tab:: csharp + + // Rotate this Node3D every frame. + public override void _Process(double delta) + { + Basis = Basis.Rotated(Vector3.Up, Mathf.Tau * (float)delta) + .Rotated(Vector3.Right, Mathf.Tau * (float)delta) + .Orthonormalized(); + } + + + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_rotated: -- :ref:`Basis` **rotated** **(** :ref:`Vector3` axis, :ref:`float` phi **)** +.. rst-class:: classref-method + +:ref:`Basis` **rotated**\ (\ axis\: :ref:`Vector3`, angle\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns a copy of this basis rotated around the given ``axis`` by the given ``angle`` (in radians). + +The ``axis`` must be a normalized vector (see :ref:`Vector3.normalized()`). If ``angle`` is positive, the basis is rotated counter-clockwise around the axis. + + +.. tabs:: -Introduce an additional rotation around the given axis by phi (radians). The axis must be a normalized vector. + .. code-tab:: gdscript + + var my_basis = Basis.IDENTITY + var angle = TAU / 2 + + my_basis = my_basis.rotated(Vector3.UP, angle) # Rotate around the up axis (yaw). + my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Rotate around the right axis (pitch). + my_basis = my_basis.rotated(Vector3.BACK, angle) # Rotate around the back axis (roll). + + .. code-tab:: csharp + + var myBasis = Basis.Identity; + var angle = Mathf.Tau / 2.0f; + + myBasis = myBasis.Rotated(Vector3.Up, angle); // Rotate around the up axis (yaw). + myBasis = myBasis.Rotated(Vector3.Right, angle); // Rotate around the right axis (pitch). + myBasis = myBasis.Rotated(Vector3.Back, angle); // Rotate around the back axis (roll). + + + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_scaled: -- :ref:`Basis` **scaled** **(** :ref:`Vector3` scale **)** +.. rst-class:: classref-method + +:ref:`Basis` **scaled**\ (\ scale\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns this basis with each axis's components scaled by the given ``scale``'s components. -Introduce an additional scaling specified by the given 3D scaling factor. +The basis matrix's rows are multiplied by ``scale``'s components. This operation is a global scale (relative to the parent). + + +.. tabs:: + + .. code-tab:: gdscript + + var my_basis = Basis( + Vector3(1, 1, 1), + Vector3(2, 2, 2), + Vector3(3, 3, 3) + ) + my_basis = my_basis.scaled(Vector3(0, 2, -2)) + + print(my_basis.x) # Prints (0.0, 2.0, -2.0) + print(my_basis.y) # Prints (0.0, 4.0, -4.0) + print(my_basis.z) # Prints (0.0, 6.0, -6.0) + + .. code-tab:: csharp + + var myBasis = new Basis( + new Vector3(1.0f, 1.0f, 1.0f), + new Vector3(2.0f, 2.0f, 2.0f), + new Vector3(3.0f, 3.0f, 3.0f) + ); + myBasis = myBasis.Scaled(new Vector3(0.0f, 2.0f, -2.0f)); + + GD.Print(myBasis.X); // Prints (0, 2, -2) + GD.Print(myBasis.Y); // Prints (0, 4, -4) + GD.Print(myBasis.Z); // Prints (0, 6, -6) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_method_scaled_local: + +.. rst-class:: classref-method + +:ref:`Basis` **scaled_local**\ (\ scale\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns this basis with each axis scaled by the corresponding component in the given ``scale``. + +The basis matrix's columns are multiplied by ``scale``'s components. This operation is a local scale (relative to self). + + +.. tabs:: + + .. code-tab:: gdscript + + var my_basis = Basis( + Vector3(1, 1, 1), + Vector3(2, 2, 2), + Vector3(3, 3, 3) + ) + my_basis = my_basis.scaled_local(Vector3(0, 2, -2)) + + print(my_basis.x) # Prints (0.0, 0.0, 0.0) + print(my_basis.y) # Prints (4.0, 4.0, 4.0) + print(my_basis.z) # Prints (-6.0, -6.0, -6.0) + + .. code-tab:: csharp + + var myBasis = new Basis( + new Vector3(1.0f, 1.0f, 1.0f), + new Vector3(2.0f, 2.0f, 2.0f), + new Vector3(3.0f, 3.0f, 3.0f) + ); + myBasis = myBasis.ScaledLocal(new Vector3(0.0f, 2.0f, -2.0f)); + + GD.Print(myBasis.X); // Prints (0, 0, 0) + GD.Print(myBasis.Y); // Prints (4, 4, 4) + GD.Print(myBasis.Z); // Prints (-6, -6, -6) + + + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_slerp: -- :ref:`Basis` **slerp** **(** :ref:`Basis` b, :ref:`float` t **)** +.. rst-class:: classref-method + +:ref:`Basis` **slerp**\ (\ to\: :ref:`Basis`, weight\: :ref:`float`\ ) |const| :ref:`🔗` + +Performs a spherical-linear interpolation with the ``to`` basis, given a ``weight``. Both this basis and ``to`` should represent a rotation. -Assuming that the matrix is a proper rotation matrix, slerp performs a spherical-linear interpolation with another rotation matrix. +\ **Example:** Smoothly rotate a :ref:`Node3D` to the target basis over time, with a :ref:`Tween`: + +:: + + var start_basis = Basis.IDENTITY + var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2) + + func _ready(): + create_tween().tween_method(interpolate, 0.0, 1.0, 5.0).set_trans(Tween.TRANS_EXPO) + + func interpolate(weight): + basis = start_basis.slerp(target_basis, weight) + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_tdotx: -- :ref:`float` **tdotx** **(** :ref:`Vector3` with **)** +.. rst-class:: classref-method -Transposed dot product with the X axis of the matrix. +:ref:`float` **tdotx**\ (\ with\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns the transposed dot product between ``with`` and the :ref:`x` axis (see :ref:`transposed()`). + +This is equivalent to ``basis.x.dot(vector)``. + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_tdoty: -- :ref:`float` **tdoty** **(** :ref:`Vector3` with **)** +.. rst-class:: classref-method + +:ref:`float` **tdoty**\ (\ with\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns the transposed dot product between ``with`` and the :ref:`y` axis (see :ref:`transposed()`). -Transposed dot product with the Y axis of the matrix. +This is equivalent to ``basis.y.dot(vector)``. + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_tdotz: -- :ref:`float` **tdotz** **(** :ref:`Vector3` with **)** +.. rst-class:: classref-method + +:ref:`float` **tdotz**\ (\ with\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns the transposed dot product between ``with`` and the :ref:`z` axis (see :ref:`transposed()`). -Transposed dot product with the Z axis of the matrix. +This is equivalent to ``basis.z.dot(vector)``. + +.. rst-class:: classref-item-separator ---- .. _class_Basis_method_transposed: -- :ref:`Basis` **transposed** **(** **)** +.. rst-class:: classref-method + +:ref:`Basis` **transposed**\ (\ ) |const| :ref:`🔗` + +Returns the transposed version of this basis. This turns the basis matrix's columns into rows, and its rows into columns. + + +.. tabs:: + + .. code-tab:: gdscript + + var my_basis = Basis( + Vector3(1, 2, 3), + Vector3(4, 5, 6), + Vector3(7, 8, 9) + ) + my_basis = my_basis.transposed() + + print(my_basis.x) # Prints (1.0, 4.0, 7.0) + print(my_basis.y) # Prints (2.0, 5.0, 8.0) + print(my_basis.z) # Prints (3.0, 6.0, 9.0) + + .. code-tab:: csharp + + var myBasis = new Basis( + new Vector3(1.0f, 2.0f, 3.0f), + new Vector3(4.0f, 5.0f, 6.0f), + new Vector3(7.0f, 8.0f, 9.0f) + ); + myBasis = myBasis.Transposed(); + + GD.Print(myBasis.X); // Prints (1, 4, 7) + GD.Print(myBasis.Y); // Prints (2, 5, 8) + GD.Print(myBasis.Z); // Prints (3, 6, 9) + + + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Operator Descriptions +--------------------- + +.. _class_Basis_operator_neq_Basis: + +.. rst-class:: classref-operator + +:ref:`bool` **operator !=**\ (\ right\: :ref:`Basis`\ ) :ref:`🔗` + +Returns ``true`` if the components of both **Basis** matrices are not equal. + +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_operator_mul_Basis: + +.. rst-class:: classref-operator + +:ref:`Basis` **operator ***\ (\ right\: :ref:`Basis`\ ) :ref:`🔗` + +Transforms (multiplies) the ``right`` basis by this basis. + +This is the operation performed between parent and child :ref:`Node3D`\ s. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_operator_mul_Vector3: + +.. rst-class:: classref-operator + +:ref:`Vector3` **operator ***\ (\ right\: :ref:`Vector3`\ ) :ref:`🔗` -Returns the transposed version of the matrix. +Transforms (multiplies) the ``right`` vector by this basis, returning a :ref:`Vector3`. + + +.. tabs:: + + .. code-tab:: gdscript + + # Basis that swaps the X/Z axes and doubles the scale. + var my_basis = Basis(Vector3(0, 2, 0), Vector3(2, 0, 0), Vector3(0, 0, 2)) + print(my_basis * Vector3(1, 2, 3)) # Prints (4.0, 2.0, 6.0) + + .. code-tab:: csharp + + // Basis that swaps the X/Z axes and doubles the scale. + var myBasis = new Basis(new Vector3(0, 2, 0), new Vector3(2, 0, 0), new Vector3(0, 0, 2)); + GD.Print(myBasis * new Vector3(1, 2, 3)); // Prints (4, 2, 6) + + + +.. rst-class:: classref-item-separator ---- -.. _class_Basis_method_xform: +.. _class_Basis_operator_mul_float: + +.. rst-class:: classref-operator + +:ref:`Basis` **operator ***\ (\ right\: :ref:`float`\ ) :ref:`🔗` -- :ref:`Vector3` **xform** **(** :ref:`Vector3` v **)** +Multiplies all components of the **Basis** by the given :ref:`float`. This affects the basis's scale uniformly, resizing all 3 axes by the ``right`` value. -Returns a vector transformed (multiplied) by the matrix. +.. rst-class:: classref-item-separator ---- -.. _class_Basis_method_xform_inv: +.. _class_Basis_operator_mul_int: + +.. rst-class:: classref-operator + +:ref:`Basis` **operator ***\ (\ right\: :ref:`int`\ ) :ref:`🔗` + +Multiplies all components of the **Basis** by the given :ref:`int`. This affects the basis's scale uniformly, resizing all 3 axes by the ``right`` value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_operator_div_float: + +.. rst-class:: classref-operator + +:ref:`Basis` **operator /**\ (\ right\: :ref:`float`\ ) :ref:`🔗` + +Divides all components of the **Basis** by the given :ref:`float`. This affects the basis's scale uniformly, resizing all 3 axes by the ``right`` value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_operator_div_int: + +.. rst-class:: classref-operator + +:ref:`Basis` **operator /**\ (\ right\: :ref:`int`\ ) :ref:`🔗` + +Divides all components of the **Basis** by the given :ref:`int`. This affects the basis's scale uniformly, resizing all 3 axes by the ``right`` value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_operator_eq_Basis: + +.. rst-class:: classref-operator + +:ref:`bool` **operator ==**\ (\ right\: :ref:`Basis`\ ) :ref:`🔗` + +Returns ``true`` if the components of both **Basis** matrices are exactly equal. + +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_operator_idx_int: + +.. rst-class:: classref-operator -- :ref:`Vector3` **xform_inv** **(** :ref:`Vector3` v **)** +:ref:`Vector3` **operator []**\ (\ index\: :ref:`int`\ ) :ref:`🔗` -Returns a vector transformed (multiplied) by the transposed matrix. +Accesses each axis (column) of this basis by their index. Index ``0`` is the same as :ref:`x`, index ``1`` is the same as :ref:`y`, and index ``2`` is the same as :ref:`z`. -**Note:** This results in a multiplication by the inverse of the matrix only if it represents a rotation-reflection. +\ **Note:** In C++, this operator accesses the rows of the basis matrix, *not* the columns. For the same behavior as scripting languages, use the ``set_column`` and ``get_column`` methods. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_bitmap.rst b/classes/class_bitmap.rst index 957545a751b..c03a2f92e7a 100644 --- a/classes/class_bitmap.rst +++ b/classes/class_bitmap.rst @@ -1,112 +1,237 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BitMap.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BitMap.xml. .. _class_BitMap: BitMap ====== -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Boolean matrix. +.. rst-class:: classref-introduction-group + Description ----------- A two-dimensional array of boolean values, can be used to efficiently store a binary matrix (every matrix element takes only one bit) and query the values using natural cartesian coordinates. +.. rst-class:: classref-reftable-group + Methods ------- -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`create` **(** :ref:`Vector2` size **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`create_from_image_alpha` **(** :ref:`Image` image, :ref:`float` threshold=0.1 **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_bit` **(** :ref:`Vector2` position **)** const | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_size` **(** **)** const | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_true_bit_count` **(** **)** const | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`grow_mask` **(** :ref:`int` pixels, :ref:`Rect2` rect **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`opaque_to_polygons` **(** :ref:`Rect2` rect, :ref:`float` epsilon=2.0 **)** const | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bit` **(** :ref:`Vector2` position, :ref:`bool` bit **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_bit_rect` **(** :ref:`Rect2` rect, :ref:`bool` bit **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Image` | :ref:`convert_to_image`\ (\ ) |const| | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`create`\ (\ size\: :ref:`Vector2i`\ ) | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`create_from_image_alpha`\ (\ image\: :ref:`Image`, threshold\: :ref:`float` = 0.1\ ) | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_bit`\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_bitv`\ (\ position\: :ref:`Vector2i`\ ) |const| | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2i` | :ref:`get_size`\ (\ ) |const| | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_true_bit_count`\ (\ ) |const| | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`grow_mask`\ (\ pixels\: :ref:`int`, rect\: :ref:`Rect2i`\ ) | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`PackedVector2Array`\] | :ref:`opaque_to_polygons`\ (\ rect\: :ref:`Rect2i`, epsilon\: :ref:`float` = 2.0\ ) |const| | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`resize`\ (\ new_size\: :ref:`Vector2i`\ ) | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bit`\ (\ x\: :ref:`int`, y\: :ref:`int`, bit\: :ref:`bool`\ ) | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bit_rect`\ (\ rect\: :ref:`Rect2i`, bit\: :ref:`bool`\ ) | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bitv`\ (\ position\: :ref:`Vector2i`, bit\: :ref:`bool`\ ) | + +----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- +.. _class_BitMap_method_convert_to_image: + +.. rst-class:: classref-method + +:ref:`Image` **convert_to_image**\ (\ ) |const| :ref:`🔗` + +Returns an image of the same size as the bitmap and with an :ref:`Format` of type :ref:`Image.FORMAT_L8`. ``true`` bits of the bitmap are being converted into white pixels, and ``false`` bits into black. + +.. rst-class:: classref-item-separator + +---- + .. _class_BitMap_method_create: -- void **create** **(** :ref:`Vector2` size **)** +.. rst-class:: classref-method + +|void| **create**\ (\ size\: :ref:`Vector2i`\ ) :ref:`🔗` Creates a bitmap with the specified size, filled with ``false``. +.. rst-class:: classref-item-separator + ---- .. _class_BitMap_method_create_from_image_alpha: -- void **create_from_image_alpha** **(** :ref:`Image` image, :ref:`float` threshold=0.1 **)** +.. rst-class:: classref-method + +|void| **create_from_image_alpha**\ (\ image\: :ref:`Image`, threshold\: :ref:`float` = 0.1\ ) :ref:`🔗` Creates a bitmap that matches the given image dimensions, every element of the bitmap is set to ``false`` if the alpha value of the image at that position is equal to ``threshold`` or less, and ``true`` in other case. +.. rst-class:: classref-item-separator + ---- .. _class_BitMap_method_get_bit: -- :ref:`bool` **get_bit** **(** :ref:`Vector2` position **)** const +.. rst-class:: classref-method + +:ref:`bool` **get_bit**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns bitmap's value at the specified position. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BitMap_method_get_bitv: + +.. rst-class:: classref-method + +:ref:`bool` **get_bitv**\ (\ position\: :ref:`Vector2i`\ ) |const| :ref:`🔗` Returns bitmap's value at the specified position. +.. rst-class:: classref-item-separator + ---- .. _class_BitMap_method_get_size: -- :ref:`Vector2` **get_size** **(** **)** const +.. rst-class:: classref-method + +:ref:`Vector2i` **get_size**\ (\ ) |const| :ref:`🔗` Returns bitmap's dimensions. +.. rst-class:: classref-item-separator + ---- .. _class_BitMap_method_get_true_bit_count: -- :ref:`int` **get_true_bit_count** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_true_bit_count**\ (\ ) |const| :ref:`🔗` -Returns the amount of bitmap elements that are set to ``true``. +Returns the number of bitmap elements that are set to ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_BitMap_method_grow_mask: -- void **grow_mask** **(** :ref:`int` pixels, :ref:`Rect2` rect **)** +.. rst-class:: classref-method + +|void| **grow_mask**\ (\ pixels\: :ref:`int`, rect\: :ref:`Rect2i`\ ) :ref:`🔗` + +Applies morphological dilation or erosion to the bitmap. If ``pixels`` is positive, dilation is applied to the bitmap. If ``pixels`` is negative, erosion is applied to the bitmap. ``rect`` defines the area where the morphological operation is applied. Pixels located outside the ``rect`` are unaffected by :ref:`grow_mask()`. + +.. rst-class:: classref-item-separator ---- .. _class_BitMap_method_opaque_to_polygons: -- :ref:`Array` **opaque_to_polygons** **(** :ref:`Rect2` rect, :ref:`float` epsilon=2.0 **)** const +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`PackedVector2Array`\] **opaque_to_polygons**\ (\ rect\: :ref:`Rect2i`, epsilon\: :ref:`float` = 2.0\ ) |const| :ref:`🔗` + +Creates an :ref:`Array` of polygons covering a rectangular portion of the bitmap. It uses a marching squares algorithm, followed by Ramer-Douglas-Peucker (RDP) reduction of the number of vertices. Each polygon is described as a :ref:`PackedVector2Array` of its vertices. + +To get polygons covering the whole bitmap, pass: + +:: + + Rect2(Vector2(), get_size()) + +\ ``epsilon`` is passed to RDP to control how accurately the polygons cover the bitmap: a lower ``epsilon`` corresponds to more points in the polygons. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BitMap_method_resize: + +.. rst-class:: classref-method + +|void| **resize**\ (\ new_size\: :ref:`Vector2i`\ ) :ref:`🔗` + +Resizes the image to ``new_size``. + +.. rst-class:: classref-item-separator ---- .. _class_BitMap_method_set_bit: -- void **set_bit** **(** :ref:`Vector2` position, :ref:`bool` bit **)** +.. rst-class:: classref-method + +|void| **set_bit**\ (\ x\: :ref:`int`, y\: :ref:`int`, bit\: :ref:`bool`\ ) :ref:`🔗` Sets the bitmap's element at the specified position, to the specified value. +.. rst-class:: classref-item-separator + ---- .. _class_BitMap_method_set_bit_rect: -- void **set_bit_rect** **(** :ref:`Rect2` rect, :ref:`bool` bit **)** +.. rst-class:: classref-method + +|void| **set_bit_rect**\ (\ rect\: :ref:`Rect2i`, bit\: :ref:`bool`\ ) :ref:`🔗` Sets a rectangular portion of the bitmap to the specified value. +.. rst-class:: classref-item-separator + +---- + +.. _class_BitMap_method_set_bitv: + +.. rst-class:: classref-method + +|void| **set_bitv**\ (\ position\: :ref:`Vector2i`, bit\: :ref:`bool`\ ) :ref:`🔗` + +Sets the bitmap's element at the specified position, to the specified value. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_bitmapfont.rst b/classes/class_bitmapfont.rst deleted file mode 100644 index 9308a3b0c74..00000000000 --- a/classes/class_bitmapfont.rst +++ /dev/null @@ -1,194 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BitmapFont.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_BitmapFont: - -BitmapFont -========== - -**Inherits:** :ref:`Font` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` - -Renders text using fonts under the `BMFont `_ format. - -Handles files with the ``.fnt`` extension. - -Description ------------ - -Renders text using ``*.fnt`` fonts containing texture atlases. Supports distance fields. For using vector font files like TTF directly, see :ref:`DynamicFont`. - -Properties ----------- - -+-------------------------------------+-----------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`ascent` | ``0.0`` | -+-------------------------------------+-----------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`distance_field` | ``false`` | -+-------------------------------------+-----------------------------------------------------------------+-----------+ -| :ref:`BitmapFont` | :ref:`fallback` | | -+-------------------------------------+-----------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`height` | ``1.0`` | -+-------------------------------------+-----------------------------------------------------------------+-----------+ - -Methods -------- - -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_char` **(** :ref:`int` character, :ref:`int` texture, :ref:`Rect2` rect, :ref:`Vector2` align=Vector2( 0, 0 ), :ref:`float` advance=-1 **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_kerning_pair` **(** :ref:`int` char_a, :ref:`int` char_b, :ref:`int` kerning **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_texture` **(** :ref:`Texture2D` texture **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear` **(** **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`create_from_fnt` **(** :ref:`String` path **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_char_size` **(** :ref:`int` char, :ref:`int` next=0 **)** const | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_kerning_pair` **(** :ref:`int` char_a, :ref:`int` char_b **)** const | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Texture2D` | :ref:`get_texture` **(** :ref:`int` idx **)** const | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_texture_count` **(** **)** const | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Property Descriptions ---------------------- - -.. _class_BitmapFont_property_ascent: - -- :ref:`float` **ascent** - -+-----------+-------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------+ -| *Setter* | set_ascent(value) | -+-----------+-------------------+ -| *Getter* | get_ascent() | -+-----------+-------------------+ - -Ascent (number of pixels above the baseline). - ----- - -.. _class_BitmapFont_property_distance_field: - -- :ref:`bool` **distance_field** - -+-----------+--------------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------------+ -| *Setter* | set_distance_field_hint(value) | -+-----------+--------------------------------+ -| *Getter* | is_distance_field_hint() | -+-----------+--------------------------------+ - -If ``true``, distance field hint is enabled. - ----- - -.. _class_BitmapFont_property_fallback: - -- :ref:`BitmapFont` **fallback** - -+----------+---------------------+ -| *Setter* | set_fallback(value) | -+----------+---------------------+ -| *Getter* | get_fallback() | -+----------+---------------------+ - -The fallback font. - ----- - -.. _class_BitmapFont_property_height: - -- :ref:`float` **height** - -+-----------+-------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------+ -| *Setter* | set_height(value) | -+-----------+-------------------+ -| *Getter* | get_height() | -+-----------+-------------------+ - -Total font height (ascent plus descent) in pixels. - -Method Descriptions -------------------- - -.. _class_BitmapFont_method_add_char: - -- void **add_char** **(** :ref:`int` character, :ref:`int` texture, :ref:`Rect2` rect, :ref:`Vector2` align=Vector2( 0, 0 ), :ref:`float` advance=-1 **)** - -Adds a character to the font, where ``character`` is the Unicode value, ``texture`` is the texture index, ``rect`` is the region in the texture (in pixels!), ``align`` is the (optional) alignment for the character and ``advance`` is the (optional) advance. - ----- - -.. _class_BitmapFont_method_add_kerning_pair: - -- void **add_kerning_pair** **(** :ref:`int` char_a, :ref:`int` char_b, :ref:`int` kerning **)** - -Adds a kerning pair to the ``BitmapFont`` as a difference. Kerning pairs are special cases where a typeface advance is determined by the next character. - ----- - -.. _class_BitmapFont_method_add_texture: - -- void **add_texture** **(** :ref:`Texture2D` texture **)** - -Adds a texture to the ``BitmapFont``. - ----- - -.. _class_BitmapFont_method_clear: - -- void **clear** **(** **)** - -Clears all the font data and settings. - ----- - -.. _class_BitmapFont_method_create_from_fnt: - -- :ref:`Error` **create_from_fnt** **(** :ref:`String` path **)** - -Creates a BitmapFont from the ``*.fnt`` file at ``path``. - ----- - -.. _class_BitmapFont_method_get_char_size: - -- :ref:`Vector2` **get_char_size** **(** :ref:`int` char, :ref:`int` next=0 **)** const - -Returns the size of a character, optionally taking kerning into account if the next character is provided. - ----- - -.. _class_BitmapFont_method_get_kerning_pair: - -- :ref:`int` **get_kerning_pair** **(** :ref:`int` char_a, :ref:`int` char_b **)** const - -Returns a kerning pair as a difference. - ----- - -.. _class_BitmapFont_method_get_texture: - -- :ref:`Texture2D` **get_texture** **(** :ref:`int` idx **)** const - -Returns the font atlas texture at index ``idx``. - ----- - -.. _class_BitmapFont_method_get_texture_count: - -- :ref:`int` **get_texture_count** **(** **)** const - -Returns the number of textures in the BitmapFont atlas. - diff --git a/classes/class_bone2d.rst b/classes/class_bone2d.rst index 560c9d8693a..3bb0ff901d8 100644 --- a/classes/class_bone2d.rst +++ b/classes/class_bone2d.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Bone2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Bone2D.xml. .. _class_Bone2D: @@ -11,94 +12,206 @@ Bone2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Joint used with :ref:`Skeleton2D` to control and animate other nodes. +A joint used with :ref:`Skeleton2D` to control and animate other nodes. + +.. rst-class:: classref-introduction-group Description ----------- -Use a hierarchy of ``Bone2D`` bound to a :ref:`Skeleton2D` to control, and animate other :ref:`Node2D` nodes. +A hierarchy of **Bone2D**\ s can be bound to a :ref:`Skeleton2D` to control and animate other :ref:`Node2D` nodes. -You can use ``Bone2D`` and ``Skeleton2D`` nodes to animate 2D meshes created with the Polygon 2D UV editor. +You can use **Bone2D** and :ref:`Skeleton2D` nodes to animate 2D meshes created with the :ref:`Polygon2D` UV editor. -Each bone has a :ref:`rest` transform that you can reset to with :ref:`apply_rest`. These rest poses are relative to the bone's parent. +Each bone has a :ref:`rest` transform that you can reset to with :ref:`apply_rest()`. These rest poses are relative to the bone's parent. If in the editor, you can set the rest pose of an entire skeleton using a menu option, from the code, you need to iterate over the bones to set their individual rest poses. +.. rst-class:: classref-reftable-group + Properties ---------- -+---------------------------------------+-------------------------------------------------------------+-------------------------------------+ -| :ref:`float` | :ref:`default_length` | ``16.0`` | -+---------------------------------------+-------------------------------------------------------------+-------------------------------------+ -| :ref:`Transform2D` | :ref:`rest` | ``Transform2D( 0, 0, 0, 0, 0, 0 )`` | -+---------------------------------------+-------------------------------------------------------------+-------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------+-----------------------------------------+-----------------------------------+ + | :ref:`Transform2D` | :ref:`rest` | ``Transform2D(0, 0, 0, 0, 0, 0)`` | + +---------------------------------------+-----------------------------------------+-----------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------+-------------------------------------------------------------------------------------------+ -| void | :ref:`apply_rest` **(** **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_index_in_skeleton` **(** **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------+ -| :ref:`Transform2D` | :ref:`get_skeleton_rest` **(** **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`apply_rest`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_autocalculate_length_and_angle`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_bone_angle`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_index_in_skeleton`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_length`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_skeleton_rest`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_autocalculate_length_and_angle`\ (\ auto_calculate\: :ref:`bool`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bone_angle`\ (\ angle\: :ref:`float`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_length`\ (\ length\: :ref:`float`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- -.. _class_Bone2D_property_default_length: +.. _class_Bone2D_property_rest: -- :ref:`float` **default_length** +.. rst-class:: classref-property -+-----------+---------------------------+ -| *Default* | ``16.0`` | -+-----------+---------------------------+ -| *Setter* | set_default_length(value) | -+-----------+---------------------------+ -| *Getter* | get_default_length() | -+-----------+---------------------------+ +:ref:`Transform2D` **rest** = ``Transform2D(0, 0, 0, 0, 0, 0)`` :ref:`🔗` -Length of the bone's representation drawn in the editor's viewport in pixels. +.. rst-class:: classref-property-setget ----- +- |void| **set_rest**\ (\ value\: :ref:`Transform2D`\ ) +- :ref:`Transform2D` **get_rest**\ (\ ) -.. _class_Bone2D_property_rest: +Rest transform of the bone. You can reset the node's transforms to this value using :ref:`apply_rest()`. -- :ref:`Transform2D` **rest** +.. rst-class:: classref-section-separator -+-----------+-------------------------------------+ -| *Default* | ``Transform2D( 0, 0, 0, 0, 0, 0 )`` | -+-----------+-------------------------------------+ -| *Setter* | set_rest(value) | -+-----------+-------------------------------------+ -| *Getter* | get_rest() | -+-----------+-------------------------------------+ +---- -Rest transform of the bone. You can reset the node's transforms to this value using :ref:`apply_rest`. +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_Bone2D_method_apply_rest: -- void **apply_rest** **(** **)** +.. rst-class:: classref-method + +|void| **apply_rest**\ (\ ) :ref:`🔗` + +Resets the bone to the rest pose. This is equivalent to setting :ref:`Node2D.transform` to :ref:`rest`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Bone2D_method_get_autocalculate_length_and_angle: + +.. rst-class:: classref-method + +:ref:`bool` **get_autocalculate_length_and_angle**\ (\ ) |const| :ref:`🔗` -Stores the node's current transforms in :ref:`rest`. +Returns whether this **Bone2D** is going to autocalculate its length and bone angle using its first **Bone2D** child node, if one exists. If there are no **Bone2D** children, then it cannot autocalculate these values and will print a warning. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Bone2D_method_get_bone_angle: + +.. rst-class:: classref-method + +:ref:`float` **get_bone_angle**\ (\ ) |const| :ref:`🔗` + +Returns the angle of the bone in the **Bone2D**. + +\ **Note:** This is different from the **Bone2D**'s rotation. The bone's angle is the rotation of the bone shown by the gizmo, which is unaffected by the **Bone2D**'s :ref:`Node2D.transform`. + +.. rst-class:: classref-item-separator ---- .. _class_Bone2D_method_get_index_in_skeleton: -- :ref:`int` **get_index_in_skeleton** **(** **)** const +.. rst-class:: classref-method + +:ref:`int` **get_index_in_skeleton**\ (\ ) |const| :ref:`🔗` Returns the node's index as part of the entire skeleton. See :ref:`Skeleton2D`. +.. rst-class:: classref-item-separator + +---- + +.. _class_Bone2D_method_get_length: + +.. rst-class:: classref-method + +:ref:`float` **get_length**\ (\ ) |const| :ref:`🔗` + +Returns the length of the bone in the **Bone2D** node. + +.. rst-class:: classref-item-separator + ---- .. _class_Bone2D_method_get_skeleton_rest: -- :ref:`Transform2D` **get_skeleton_rest** **(** **)** const +.. rst-class:: classref-method + +:ref:`Transform2D` **get_skeleton_rest**\ (\ ) |const| :ref:`🔗` + +Returns the node's :ref:`rest` :ref:`Transform2D` if it doesn't have a parent, or its rest pose relative to its parent. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Bone2D_method_set_autocalculate_length_and_angle: + +.. rst-class:: classref-method + +|void| **set_autocalculate_length_and_angle**\ (\ auto_calculate\: :ref:`bool`\ ) :ref:`🔗` + +When set to ``true``, the **Bone2D** node will attempt to automatically calculate the bone angle and length using the first child **Bone2D** node, if one exists. If none exist, the **Bone2D** cannot automatically calculate these values and will print a warning. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Bone2D_method_set_bone_angle: + +.. rst-class:: classref-method + +|void| **set_bone_angle**\ (\ angle\: :ref:`float`\ ) :ref:`🔗` + +Sets the bone angle for the **Bone2D**. This is typically set to the rotation from the **Bone2D** to a child **Bone2D** node. + +\ **Note:** This is different from the **Bone2D**'s rotation. The bone's angle is the rotation of the bone shown by the gizmo, which is unaffected by the **Bone2D**'s :ref:`Node2D.transform`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Bone2D_method_set_length: + +.. rst-class:: classref-method + +|void| **set_length**\ (\ length\: :ref:`float`\ ) :ref:`🔗` -Returns the node's :ref:`rest` ``Transform2D`` if it doesn't have a parent, or its rest pose relative to its parent. +Sets the length of the bone in the **Bone2D**. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_boneattachment.rst b/classes/class_boneattachment.rst deleted file mode 100644 index d61bb8f92b0..00000000000 --- a/classes/class_boneattachment.rst +++ /dev/null @@ -1,44 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BoneAttachment.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_BoneAttachment: - -BoneAttachment -============== - -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -A node that will attach to a bone. - -Description ------------ - -This node must be the child of a :ref:`Skeleton` node. You can then select a bone for this node to attach to. The BoneAttachment node will copy the transform of the selected bone. - -Properties ----------- - -+-----------------------------+-----------------------------------------------------------+--------+ -| :ref:`String` | :ref:`bone_name` | ``""`` | -+-----------------------------+-----------------------------------------------------------+--------+ - -Property Descriptions ---------------------- - -.. _class_BoneAttachment_property_bone_name: - -- :ref:`String` **bone_name** - -+-----------+----------------------+ -| *Default* | ``""`` | -+-----------+----------------------+ -| *Setter* | set_bone_name(value) | -+-----------+----------------------+ -| *Getter* | get_bone_name() | -+-----------+----------------------+ - -The name of the attached bone. - diff --git a/classes/class_boneattachment3d.rst b/classes/class_boneattachment3d.rst new file mode 100644 index 00000000000..6a85f3bf96a --- /dev/null +++ b/classes/class_boneattachment3d.rst @@ -0,0 +1,192 @@ +:github_url: hide + +.. meta:: + :keywords: tag + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BoneAttachment3D.xml. + +.. _class_BoneAttachment3D: + +BoneAttachment3D +================ + +**Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +А node that dynamically copies or overrides the 3D transform of a bone in its parent :ref:`Skeleton3D`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This node selects a bone in a :ref:`Skeleton3D` and attaches to it. This means that the **BoneAttachment3D** node will either dynamically copy or override the 3D transform of the selected bone. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`bone_idx` | ``-1`` | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`bone_name` | ``""`` | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`external_skeleton` | | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`override_pose` | ``false`` | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`PhysicsInterpolationMode` | physics_interpolation_mode | ``2`` (overrides :ref:`Node`) | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`use_external_skeleton` | ``false`` | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------------------+-----------------------------------------------------------------------------------+ + | :ref:`Skeleton3D` | :ref:`get_skeleton`\ (\ ) | + +-------------------------------------+-----------------------------------------------------------------------------------+ + | |void| | :ref:`on_skeleton_update`\ (\ ) | + +-------------------------------------+-----------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_BoneAttachment3D_property_bone_idx: + +.. rst-class:: classref-property + +:ref:`int` **bone_idx** = ``-1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_bone_idx**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_bone_idx**\ (\ ) + +The index of the attached bone. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneAttachment3D_property_bone_name: + +.. rst-class:: classref-property + +:ref:`String` **bone_name** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_bone_name**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_bone_name**\ (\ ) + +The name of the attached bone. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneAttachment3D_property_external_skeleton: + +.. rst-class:: classref-property + +:ref:`NodePath` **external_skeleton** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_external_skeleton**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_external_skeleton**\ (\ ) + +The :ref:`NodePath` to the external :ref:`Skeleton3D` node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneAttachment3D_property_override_pose: + +.. rst-class:: classref-property + +:ref:`bool` **override_pose** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_override_pose**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_override_pose**\ (\ ) + +Whether the **BoneAttachment3D** node will override the bone pose of the bone it is attached to. When set to ``true``, the **BoneAttachment3D** node can change the pose of the bone. When set to ``false``, the **BoneAttachment3D** will always be set to the bone's transform. + +\ **Note:** This override performs interruptively in the skeleton update process using signals due to the old design. It may cause unintended behavior when used at the same time with :ref:`SkeletonModifier3D`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneAttachment3D_property_use_external_skeleton: + +.. rst-class:: classref-property + +:ref:`bool` **use_external_skeleton** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_external_skeleton**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_use_external_skeleton**\ (\ ) + +Whether the **BoneAttachment3D** node will use an external :ref:`Skeleton3D` node rather than attempting to use its parent node as the :ref:`Skeleton3D`. When set to ``true``, the **BoneAttachment3D** node will use the external :ref:`Skeleton3D` node set in :ref:`external_skeleton`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_BoneAttachment3D_method_get_skeleton: + +.. rst-class:: classref-method + +:ref:`Skeleton3D` **get_skeleton**\ (\ ) :ref:`🔗` + +Returns the parent or external :ref:`Skeleton3D` node if it exists, otherwise returns ``null``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneAttachment3D_method_on_skeleton_update: + +.. rst-class:: classref-method + +|void| **on_skeleton_update**\ (\ ) :ref:`🔗` + +A function that is called automatically when the :ref:`Skeleton3D` is updated. This function is where the **BoneAttachment3D** node updates its position so it is correctly bound when it is *not* set to override the bone pose. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_boneconstraint3d.rst b/classes/class_boneconstraint3d.rst new file mode 100644 index 00000000000..95c4d77aba0 --- /dev/null +++ b/classes/class_boneconstraint3d.rst @@ -0,0 +1,239 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BoneConstraint3D.xml. + +.. _class_BoneConstraint3D: + +BoneConstraint3D +================ + +**Inherits:** :ref:`SkeletonModifier3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +**Inherited By:** :ref:`AimModifier3D`, :ref:`ConvertTransformModifier3D`, :ref:`CopyTransformModifier3D` + +A node that may modify Skeleton3D's bone with associating the two bones. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Base class of :ref:`SkeletonModifier3D` that modifies the bone set in :ref:`set_apply_bone()` based on the transform of the bone retrieved by :ref:`get_reference_bone()`. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_setting`\ (\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_amount`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_apply_bone`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_apply_bone_name`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_reference_bone`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_reference_bone_name`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_setting_count`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_amount`\ (\ index\: :ref:`int`, amount\: :ref:`float`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_apply_bone`\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_apply_bone_name`\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_reference_bone`\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_reference_bone_name`\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_setting_count`\ (\ count\: :ref:`int`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_BoneConstraint3D_method_clear_setting: + +.. rst-class:: classref-method + +|void| **clear_setting**\ (\ ) :ref:`🔗` + +Clear all settings. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_amount: + +.. rst-class:: classref-method + +:ref:`float` **get_amount**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the apply amount of the setting at ``index``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_apply_bone: + +.. rst-class:: classref-method + +:ref:`int` **get_apply_bone**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the apply bone of the setting at ``index``. This bone will be modified. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_apply_bone_name: + +.. rst-class:: classref-method + +:ref:`String` **get_apply_bone_name**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the apply bone name of the setting at ``index``. This bone will be modified. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_reference_bone: + +.. rst-class:: classref-method + +:ref:`int` **get_reference_bone**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the reference bone of the setting at ``index``. + +This bone will be only referenced and not modified by this modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_reference_bone_name: + +.. rst-class:: classref-method + +:ref:`String` **get_reference_bone_name**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the reference bone name of the setting at ``index``. + +This bone will be only referenced and not modified by this modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_setting_count: + +.. rst-class:: classref-method + +:ref:`int` **get_setting_count**\ (\ ) |const| :ref:`🔗` + +Returns the number of settings in the modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_amount: + +.. rst-class:: classref-method + +|void| **set_amount**\ (\ index\: :ref:`int`, amount\: :ref:`float`\ ) :ref:`🔗` + +Sets the apply amount of the setting at ``index`` to ``amount``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_apply_bone: + +.. rst-class:: classref-method + +|void| **set_apply_bone**\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) :ref:`🔗` + +Sets the apply bone of the setting at ``index`` to ``bone``. This bone will be modified. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_apply_bone_name: + +.. rst-class:: classref-method + +|void| **set_apply_bone_name**\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) :ref:`🔗` + +Sets the apply bone of the setting at ``index`` to ``bone_name``. This bone will be modified. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_reference_bone: + +.. rst-class:: classref-method + +|void| **set_reference_bone**\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) :ref:`🔗` + +Sets the reference bone of the setting at ``index`` to ``bone``. + +This bone will be only referenced and not modified by this modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_reference_bone_name: + +.. rst-class:: classref-method + +|void| **set_reference_bone_name**\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) :ref:`🔗` + +Sets the reference bone of the setting at ``index`` to ``bone_name``. + +This bone will be only referenced and not modified by this modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_setting_count: + +.. rst-class:: classref-method + +|void| **set_setting_count**\ (\ count\: :ref:`int`\ ) :ref:`🔗` + +Sets the number of settings in the modifier. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_bonemap.rst b/classes/class_bonemap.rst new file mode 100644 index 00000000000..c359e3aace2 --- /dev/null +++ b/classes/class_bonemap.rst @@ -0,0 +1,167 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BoneMap.xml. + +.. _class_BoneMap: + +BoneMap +======= + +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Describes a mapping of bone names for retargeting :ref:`Skeleton3D` into common names defined by a :ref:`SkeletonProfile`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This class contains a dictionary that uses a list of bone names in :ref:`SkeletonProfile` as key names. + +By assigning the actual :ref:`Skeleton3D` bone name as the key value, it maps the :ref:`Skeleton3D` to the :ref:`SkeletonProfile`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Retargeting 3D Skeletons <../tutorials/assets_pipeline/retargeting_3d_skeletons>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------------------------+------------------------------------------------+ + | :ref:`SkeletonProfile` | :ref:`profile` | + +-----------------------------------------------+------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`find_profile_bone_name`\ (\ skeleton_bone_name\: :ref:`StringName`\ ) |const| | + +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_skeleton_bone_name`\ (\ profile_bone_name\: :ref:`StringName`\ ) |const| | + +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_skeleton_bone_name`\ (\ profile_bone_name\: :ref:`StringName`, skeleton_bone_name\: :ref:`StringName`\ ) | + +-------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_BoneMap_signal_bone_map_updated: + +.. rst-class:: classref-signal + +**bone_map_updated**\ (\ ) :ref:`🔗` + +This signal is emitted when change the key value in the **BoneMap**. This is used to validate mapping and to update **BoneMap** editor. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneMap_signal_profile_updated: + +.. rst-class:: classref-signal + +**profile_updated**\ (\ ) :ref:`🔗` + +This signal is emitted when change the value in profile or change the reference of profile. This is used to update key names in the **BoneMap** and to redraw the **BoneMap** editor. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_BoneMap_property_profile: + +.. rst-class:: classref-property + +:ref:`SkeletonProfile` **profile** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_profile**\ (\ value\: :ref:`SkeletonProfile`\ ) +- :ref:`SkeletonProfile` **get_profile**\ (\ ) + +A :ref:`SkeletonProfile` of the mapping target. Key names in the **BoneMap** are synchronized with it. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_BoneMap_method_find_profile_bone_name: + +.. rst-class:: classref-method + +:ref:`StringName` **find_profile_bone_name**\ (\ skeleton_bone_name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns a profile bone name having ``skeleton_bone_name``. If not found, an empty :ref:`StringName` will be returned. + +In the retargeting process, the returned bone name is the bone name of the target skeleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneMap_method_get_skeleton_bone_name: + +.. rst-class:: classref-method + +:ref:`StringName` **get_skeleton_bone_name**\ (\ profile_bone_name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns a skeleton bone name is mapped to ``profile_bone_name``. + +In the retargeting process, the returned bone name is the bone name of the source skeleton. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneMap_method_set_skeleton_bone_name: + +.. rst-class:: classref-method + +|void| **set_skeleton_bone_name**\ (\ profile_bone_name\: :ref:`StringName`, skeleton_bone_name\: :ref:`StringName`\ ) :ref:`🔗` + +Maps a skeleton bone name to ``profile_bone_name``. + +In the retargeting process, the setting bone name is the bone name of the source skeleton. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_bool.rst b/classes/class_bool.rst index d4e36ad5deb..19d783fef37 100644 --- a/classes/class_bool.rst +++ b/classes/class_bool.rst @@ -1,88 +1,220 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the bool.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/bool.xml. .. _class_bool: bool ==== -Boolean built-in type. +A built-in boolean type. + +.. rst-class:: classref-introduction-group Description ----------- -Boolean is a built-in type. It can represent any data type that is either a true or false value. You can think of it as an switch with on or off (1 or 0) setting. It's often used as part of programming logic in condition statements like ``if`` statements. +The **bool** is a built-in :ref:`Variant` type that may only store one of two values: ``true`` or ``false``. You can imagine it as a switch that can be either turned on or off, or as a binary digit that can either be 1 or 0. + +Booleans can be directly used in ``if``, and other conditional statements: + -**Note:** In a code below ``if can_shoot`` is equivalent of ``if can_shoot == true``. It is good practice to follow the natural spoken language structure when possible. Use ``if can_shoot`` rather than ``if can_shoot == true`` and use ``if not can_shoot`` rather than ``if can_shoot == false``. +.. tabs:: -:: + .. code-tab:: gdscript var can_shoot = true - - func shoot(): - if can_shoot: - # Perform shooting actions here. + if can_shoot: + launch_bullet() -The following code will only create a bullet if both conditions are met: action "shoot" is pressed and if ``can_shoot`` is ``true``. + .. code-tab:: csharp -**Note:** ``Input.is_action_pressed("shoot")`` is also a boolean that is ``true`` when "shoot" is pressed and ``false`` when "shoot" isn't pressed. + bool canShoot = true; + if (canShoot) + { + LaunchBullet(); + } -:: - var can_shoot = true - - func shoot(): - if can_shoot and Input.is_action_pressed("shoot"): - create_bullet() -The following code will set ``can_shoot`` to ``false`` and start a timer. This will prevent player from shooting until the timer runs out. Next ``can_shoot`` will be set to ``true`` again allowing player to shoot once again. +All comparison operators return booleans (``==``, ``>``, ``<=``, etc.). As such, it is not necessary to compare booleans themselves. You do not need to add ``== true`` or ``== false``. -:: +Booleans can be combined with the logical operators ``and``, ``or``, ``not`` to create complex conditions: - var can_shoot = true - onready var cool_down = $CoolDownTimer - - func shoot(): - if can_shoot and Input.is_action_pressed("shoot"): - create_bullet() - can_shoot = false - cool_down.start() - - func _on_CoolDownTimer_timeout(): - can_shoot = true -Methods -------- +.. tabs:: + + .. code-tab:: gdscript + + if bullets > 0 and not is_reloading(): + launch_bullet() + + if bullets == 0 or is_reloading(): + play_clack_sound() + + .. code-tab:: csharp + + if (bullets > 0 && !IsReloading()) + { + LaunchBullet(); + } + + if (bullets == 0 || IsReloading()) + { + PlayClackSound(); + } + + + +\ **Note:** In modern programming languages, logical operators are evaluated in order. All remaining conditions are skipped if their result would have no effect on the final value. This concept is known as `short-circuit evaluation `__ and can be useful to avoid evaluating expensive conditions in some performance-critical cases. + +\ **Note:** By convention, built-in methods and properties that return booleans are usually defined as yes-no questions, single adjectives, or similar (:ref:`String.is_empty()`, :ref:`Node.can_process()`, :ref:`Camera2D.enabled`, etc.). + +.. rst-class:: classref-reftable-group + +Constructors +------------ -+-------------------------+----------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`bool` **(** :ref:`int` from **)** | -+-------------------------+----------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`bool` **(** :ref:`float` from **)** | -+-------------------------+----------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`bool` **(** :ref:`String` from **)** | -+-------------------------+----------------------------------------------------------------------------------+ +.. table:: + :widths: auto -Method Descriptions -------------------- + +-------------------------+----------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`bool`\ (\ ) | + +-------------------------+----------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`bool`\ (\ from\: :ref:`bool`\ ) | + +-------------------------+----------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`bool`\ (\ from\: :ref:`float`\ ) | + +-------------------------+----------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`bool`\ (\ from\: :ref:`int`\ ) | + +-------------------------+----------------------------------------------------------------------------------+ -.. _class_bool_method_bool: +.. rst-class:: classref-reftable-group -- :ref:`bool` **bool** **(** :ref:`int` from **)** +Operators +--------- -Cast an :ref:`int` value to a boolean value, this method will return ``true`` if called with an integer value different to 0 and ``false`` in other case. +.. table:: + :widths: auto + + +-------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator !=`\ (\ right\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator \<`\ (\ right\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator ==`\ (\ right\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator >`\ (\ right\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator ---- -- :ref:`bool` **bool** **(** :ref:`float` from **)** +.. rst-class:: classref-descriptions-group + +Constructor Descriptions +------------------------ + +.. _class_bool_constructor_bool: + +.. rst-class:: classref-constructor -Cast a :ref:`float` value to a boolean value, this method will return ``true`` if called with a floating-point value different to 0 and ``false`` in other case. +:ref:`bool` **bool**\ (\ ) :ref:`🔗` + +Constructs a **bool** set to ``false``. + +.. rst-class:: classref-item-separator ---- -- :ref:`bool` **bool** **(** :ref:`String` from **)** +.. rst-class:: classref-constructor + +:ref:`bool` **bool**\ (\ from\: :ref:`bool`\ ) + +Constructs a **bool** as a copy of the given **bool**. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`bool` **bool**\ (\ from\: :ref:`float`\ ) + +Cast a :ref:`float` value to a boolean value. Returns ``false`` if ``from`` is equal to ``0.0`` (including ``-0.0``), and ``true`` for all other values (including :ref:`@GDScript.INF` and :ref:`@GDScript.NAN`). + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`bool` **bool**\ (\ from\: :ref:`int`\ ) + +Cast an :ref:`int` value to a boolean value. Returns ``false`` if ``from`` is equal to ``0``, and ``true`` for all other values. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Operator Descriptions +--------------------- + +.. _class_bool_operator_neq_bool: + +.. rst-class:: classref-operator + +:ref:`bool` **operator !=**\ (\ right\: :ref:`bool`\ ) :ref:`🔗` + +Returns ``true`` if the two booleans are not equal. That is, one is ``true`` and the other is ``false``. This operation can be seen as a logical XOR. + +.. rst-class:: classref-item-separator + +---- + +.. _class_bool_operator_lt_bool: + +.. rst-class:: classref-operator + +:ref:`bool` **operator <**\ (\ right\: :ref:`bool`\ ) :ref:`🔗` + +Returns ``true`` if the left operand is ``false`` and the right operand is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_bool_operator_eq_bool: + +.. rst-class:: classref-operator + +:ref:`bool` **operator ==**\ (\ right\: :ref:`bool`\ ) :ref:`🔗` + +Returns ``true`` if the two booleans are equal. That is, both are ``true`` or both are ``false``. This operation can be seen as a logical EQ or XNOR. + +.. rst-class:: classref-item-separator + +---- + +.. _class_bool_operator_gt_bool: + +.. rst-class:: classref-operator + +:ref:`bool` **operator >**\ (\ right\: :ref:`bool`\ ) :ref:`🔗` -Cast a :ref:`String` value to a boolean value, this method will return ``true`` if called with a non-empty string and ``false`` in other case. Examples: ``bool("False")`` returns ``true``, ``bool("")`` returns ``false``. +Returns ``true`` if the left operand is ``true`` and the right operand is ``false``. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_boxcontainer.rst b/classes/class_boxcontainer.rst index 255f888c227..99dac8ba900 100644 --- a/classes/class_boxcontainer.rst +++ b/classes/class_boxcontainer.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BoxContainer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BoxContainer.xml. .. _class_BoxContainer: @@ -11,71 +12,182 @@ BoxContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -**Inherited By:** :ref:`ColorPicker`, :ref:`HBoxContainer`, :ref:`VBoxContainer` +**Inherited By:** :ref:`HBoxContainer`, :ref:`VBoxContainer` -Base class for box containers. +A container that arranges its child controls horizontally or vertically. + +.. rst-class:: classref-introduction-group Description ----------- -Arranges child :ref:`Control` nodes vertically or horizontally, and rearranges them automatically when their minimum size changes. +A container that arranges its child controls horizontally or vertically, rearranging them automatically when their minimum size changes. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------+---------------------------------------------------------+-------+ -| :ref:`AlignMode` | :ref:`alignment` | ``0`` | -+-----------------------------------------------+---------------------------------------------------------+-------+ +.. table:: + :widths: auto + + +-------------------------------------------------------+---------------------------------------------------------+-----------+ + | :ref:`AlignmentMode` | :ref:`alignment` | ``0`` | + +-------------------------------------------------------+---------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`vertical` | ``false`` | + +-------------------------------------------------------+---------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group Methods ------- -+------+---------------------------------------------------------------------------------------------------+ -| void | :ref:`add_spacer` **(** :ref:`bool` begin **)** | -+------+---------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------+------------------------------------------------------------------------------------------------+ + | :ref:`Control` | :ref:`add_spacer`\ (\ begin\: :ref:`bool`\ ) | + +-------------------------------+------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Theme Properties +---------------- + +.. table:: + :widths: auto + + +-----------------------+-----------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`separation` | ``4`` | + +-----------------------+-----------------------------------------------------------------+-------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ -.. _enum_BoxContainer_AlignMode: +.. _enum_BoxContainer_AlignmentMode: + +.. rst-class:: classref-enumeration + +enum **AlignmentMode**: :ref:`🔗` + +.. _class_BoxContainer_constant_ALIGNMENT_BEGIN: + +.. rst-class:: classref-enumeration-constant + +:ref:`AlignmentMode` **ALIGNMENT_BEGIN** = ``0`` + +The child controls will be arranged at the beginning of the container, i.e. top if orientation is vertical, left if orientation is horizontal (right for RTL layout). + +.. _class_BoxContainer_constant_ALIGNMENT_CENTER: + +.. rst-class:: classref-enumeration-constant + +:ref:`AlignmentMode` **ALIGNMENT_CENTER** = ``1`` -.. _class_BoxContainer_constant_ALIGN_BEGIN: +The child controls will be centered in the container. -.. _class_BoxContainer_constant_ALIGN_CENTER: +.. _class_BoxContainer_constant_ALIGNMENT_END: -.. _class_BoxContainer_constant_ALIGN_END: +.. rst-class:: classref-enumeration-constant -enum **AlignMode**: +:ref:`AlignmentMode` **ALIGNMENT_END** = ``2`` -- **ALIGN_BEGIN** = **0** --- Aligns children with the beginning of the container. +The child controls will be arranged at the end of the container, i.e. bottom if orientation is vertical, right if orientation is horizontal (left for RTL layout). -- **ALIGN_CENTER** = **1** --- Aligns children with the center of the container. +.. rst-class:: classref-section-separator -- **ALIGN_END** = **2** --- Aligns children with the end of the container. +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_BoxContainer_property_alignment: -- :ref:`AlignMode` **alignment** +.. rst-class:: classref-property + +:ref:`AlignmentMode` **alignment** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_alignment**\ (\ value\: :ref:`AlignmentMode`\ ) +- :ref:`AlignmentMode` **get_alignment**\ (\ ) + +The alignment of the container's children (must be one of :ref:`ALIGNMENT_BEGIN`, :ref:`ALIGNMENT_CENTER`, or :ref:`ALIGNMENT_END`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoxContainer_property_vertical: + +.. rst-class:: classref-property + +:ref:`bool` **vertical** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_vertical**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_vertical**\ (\ ) -+-----------+----------------------+ -| *Default* | ``0`` | -+-----------+----------------------+ -| *Setter* | set_alignment(value) | -+-----------+----------------------+ -| *Getter* | get_alignment() | -+-----------+----------------------+ +If ``true``, the **BoxContainer** will arrange its children vertically, rather than horizontally. -The alignment of the container's children (must be one of :ref:`ALIGN_BEGIN`, :ref:`ALIGN_CENTER`, or :ref:`ALIGN_END`). +Can't be changed when using :ref:`HBoxContainer` and :ref:`VBoxContainer`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_BoxContainer_method_add_spacer: -- void **add_spacer** **(** :ref:`bool` begin **)** +.. rst-class:: classref-method + +:ref:`Control` **add_spacer**\ (\ begin\: :ref:`bool`\ ) :ref:`🔗` Adds a :ref:`Control` node to the box as a spacer. If ``begin`` is ``true``, it will insert the :ref:`Control` node in front of all other children. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Theme Property Descriptions +--------------------------- + +.. _class_BoxContainer_theme_constant_separation: + +.. rst-class:: classref-themeproperty + +:ref:`int` **separation** = ``4`` :ref:`🔗` + +The space between the **BoxContainer**'s elements, in pixels. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_boxmesh.rst b/classes/class_boxmesh.rst new file mode 100644 index 00000000000..7c9c8c44bf6 --- /dev/null +++ b/classes/class_boxmesh.rst @@ -0,0 +1,127 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BoxMesh.xml. + +.. _class_BoxMesh: + +BoxMesh +======= + +**Inherits:** :ref:`PrimitiveMesh` **<** :ref:`Mesh` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Generate an axis-aligned box :ref:`PrimitiveMesh`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Generate an axis-aligned box :ref:`PrimitiveMesh`. + +The box's UV layout is arranged in a 3×2 layout that allows texturing each face individually. To apply the same texture on all faces, change the material's UV property to ``Vector3(3, 2, 1)``. This is equivalent to adding ``UV *= vec2(3.0, 2.0)`` in a vertex shader. + +\ **Note:** When using a large textured **BoxMesh** (e.g. as a floor), you may stumble upon UV jittering issues depending on the camera angle. To solve this, increase :ref:`subdivide_depth`, :ref:`subdivide_height` and :ref:`subdivide_width` until you no longer notice UV jittering. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------+------------------------------------------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`size` | ``Vector3(1, 1, 1)`` | + +-------------------------------+------------------------------------------------------------------+----------------------+ + | :ref:`int` | :ref:`subdivide_depth` | ``0`` | + +-------------------------------+------------------------------------------------------------------+----------------------+ + | :ref:`int` | :ref:`subdivide_height` | ``0`` | + +-------------------------------+------------------------------------------------------------------+----------------------+ + | :ref:`int` | :ref:`subdivide_width` | ``0`` | + +-------------------------------+------------------------------------------------------------------+----------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_BoxMesh_property_size: + +.. rst-class:: classref-property + +:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_size**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_size**\ (\ ) + +The box's width, height and depth. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoxMesh_property_subdivide_depth: + +.. rst-class:: classref-property + +:ref:`int` **subdivide_depth** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_subdivide_depth**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_subdivide_depth**\ (\ ) + +Number of extra edge loops inserted along the Z axis. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoxMesh_property_subdivide_height: + +.. rst-class:: classref-property + +:ref:`int` **subdivide_height** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_subdivide_height**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_subdivide_height**\ (\ ) + +Number of extra edge loops inserted along the Y axis. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoxMesh_property_subdivide_width: + +.. rst-class:: classref-property + +:ref:`int` **subdivide_width** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_subdivide_width**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_subdivide_width**\ (\ ) + +Number of extra edge loops inserted along the X axis. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_boxoccluder3d.rst b/classes/class_boxoccluder3d.rst new file mode 100644 index 00000000000..6bb59fc0b93 --- /dev/null +++ b/classes/class_boxoccluder3d.rst @@ -0,0 +1,75 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BoxOccluder3D.xml. + +.. _class_BoxOccluder3D: + +BoxOccluder3D +============= + +**Inherits:** :ref:`Occluder3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Cuboid shape for use with occlusion culling in :ref:`OccluderInstance3D`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**BoxOccluder3D** stores a cuboid shape that can be used by the engine's occlusion culling system. + +See :ref:`OccluderInstance3D`'s documentation for instructions on setting up occlusion culling. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Occlusion culling <../tutorials/3d/occlusion_culling>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------+------------------------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`size` | ``Vector3(1, 1, 1)`` | + +-------------------------------+------------------------------------------------+----------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_BoxOccluder3D_property_size: + +.. rst-class:: classref-property + +:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_size**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_size**\ (\ ) + +The box's size in 3D units. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_boxshape.rst b/classes/class_boxshape.rst deleted file mode 100644 index 00cb4f9fa44..00000000000 --- a/classes/class_boxshape.rst +++ /dev/null @@ -1,44 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BoxShape.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_BoxShape: - -BoxShape -======== - -**Inherits:** :ref:`Shape` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` - -Box shape resource. - -Description ------------ - -3D box shape that can be a child of a :ref:`PhysicsBody` or :ref:`Area`. - -Properties ----------- - -+-------------------------------+-------------------------------------------------+------------------------+ -| :ref:`Vector3` | :ref:`extents` | ``Vector3( 1, 1, 1 )`` | -+-------------------------------+-------------------------------------------------+------------------------+ - -Property Descriptions ---------------------- - -.. _class_BoxShape_property_extents: - -- :ref:`Vector3` **extents** - -+-----------+------------------------+ -| *Default* | ``Vector3( 1, 1, 1 )`` | -+-----------+------------------------+ -| *Setter* | set_extents(value) | -+-----------+------------------------+ -| *Getter* | get_extents() | -+-----------+------------------------+ - -The box's half extents. The width, height and depth of this shape is twice the half extents. - diff --git a/classes/class_boxshape3d.rst b/classes/class_boxshape3d.rst new file mode 100644 index 00000000000..7e4eacc12c0 --- /dev/null +++ b/classes/class_boxshape3d.rst @@ -0,0 +1,79 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/BoxShape3D.xml. + +.. _class_BoxShape3D: + +BoxShape3D +========== + +**Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +A 3D box shape used for physics collision. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A 3D box shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. + +\ **Performance:** **BoxShape3D** is fast to check collisions against. It is faster than :ref:`CapsuleShape3D` and :ref:`CylinderShape3D`, but slower than :ref:`SphereShape3D`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `3D Physics Tests Demo `__ + +- `3D Kinematic Character Demo `__ + +- `3D Platformer Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------+---------------------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`size` | ``Vector3(1, 1, 1)`` | + +-------------------------------+---------------------------------------------+----------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_BoxShape3D_property_size: + +.. rst-class:: classref-property + +:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_size**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_size**\ (\ ) + +The box's width, height and depth. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_bulletphysicsdirectbodystate.rst b/classes/class_bulletphysicsdirectbodystate.rst deleted file mode 100644 index 088dd91b7f9..00000000000 --- a/classes/class_bulletphysicsdirectbodystate.rst +++ /dev/null @@ -1,15 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BulletPhysicsDirectBodyState.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_BulletPhysicsDirectBodyState: - -BulletPhysicsDirectBodyState -============================ - -**Inherits:** :ref:`PhysicsDirectBodyState` **<** :ref:`Object` - - - diff --git a/classes/class_bulletphysicsserver.rst b/classes/class_bulletphysicsserver.rst deleted file mode 100644 index 47ef924ed31..00000000000 --- a/classes/class_bulletphysicsserver.rst +++ /dev/null @@ -1,15 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the BulletPhysicsServer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_BulletPhysicsServer: - -BulletPhysicsServer -=================== - -**Inherits:** :ref:`PhysicsServer` **<** :ref:`Object` - - - diff --git a/classes/class_button.rst b/classes/class_button.rst index 268bd3138e6..ac36fa9c325 100644 --- a/classes/class_button.rst +++ b/classes/class_button.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Button.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Button.xml. .. _class_Button: @@ -11,170 +12,798 @@ Button **Inherits:** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -**Inherited By:** :ref:`CheckBox`, :ref:`CheckButton`, :ref:`ColorPickerButton`, :ref:`MenuButton`, :ref:`OptionButton`, :ref:`ToolButton` +**Inherited By:** :ref:`CheckBox`, :ref:`CheckButton`, :ref:`ColorPickerButton`, :ref:`MenuButton`, :ref:`OptionButton` -Standard themed Button. +A themed button that can contain text and an icon. + +.. rst-class:: classref-introduction-group Description ----------- -Button is the standard themed button. It can contain text and an icon, and will display them according to the current :ref:`Theme`. +**Button** is the standard themed button. It can contain text and an icon, and it will display them according to the current :ref:`Theme`. + +\ **Example:** Create a button and connect a method that will be called when the button is pressed: + + +.. tabs:: + + .. code-tab:: gdscript + + func _ready(): + var button = Button.new() + button.text = "Click me" + button.pressed.connect(_button_pressed) + add_child(button) + + func _button_pressed(): + print("Hello world!") + + .. code-tab:: csharp + + public override void _Ready() + { + var button = new Button(); + button.Text = "Click me"; + button.Pressed += ButtonPressed; + AddChild(button); + } + + private void ButtonPressed() + { + GD.Print("Hello world!"); + } + + + +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + +\ **Note:** Buttons do not detect touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `2D Dodge The Creeps Demo `__ + +- `Operating System Testing Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------+-------------------------------------------------------+-----------+ -| :ref:`TextAlign` | :ref:`align` | ``1`` | -+-----------------------------------------+-------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`clip_text` | ``false`` | -+-----------------------------------------+-------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`expand_icon` | ``false`` | -+-----------------------------------------+-------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`flat` | ``false`` | -+-----------------------------------------+-------------------------------------------------------+-----------+ -| :ref:`Texture2D` | :ref:`icon` | | -+-----------------------------------------+-------------------------------------------------------+-----------+ -| :ref:`String` | :ref:`text` | ``""`` | -+-----------------------------------------+-------------------------------------------------------+-----------+ +.. table:: + :widths: auto + + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`HorizontalAlignment` | :ref:`alignment` | ``1`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`AutowrapMode` | :ref:`autowrap_mode` | ``0`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | |bitfield|\[:ref:`LineBreakFlag`\] | :ref:`autowrap_trim_flags` | ``128`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`clip_text` | ``false`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`expand_icon` | ``false`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`flat` | ``false`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`Texture2D` | :ref:`icon` | | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`HorizontalAlignment` | :ref:`icon_alignment` | ``0`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`language` | ``""`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`text` | ``""`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`TextDirection` | :ref:`text_direction` | ``0`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`OverrunBehavior` | :ref:`text_overrun_behavior` | ``0`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | :ref:`VerticalAlignment` | :ref:`vertical_icon_alignment` | ``1`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group Theme Properties ---------------- -+---------------------------------+---------------------+------------------------------+ -| :ref:`StyleBox` | disabled | | -+---------------------------------+---------------------+------------------------------+ -| :ref:`StyleBox` | focus | | -+---------------------------------+---------------------+------------------------------+ -| :ref:`Font` | font | | -+---------------------------------+---------------------+------------------------------+ -| :ref:`Color` | font_color | Color( 0.88, 0.88, 0.88, 1 ) | -+---------------------------------+---------------------+------------------------------+ -| :ref:`Color` | font_color_disabled | Color( 0.9, 0.9, 0.9, 0.2 ) | -+---------------------------------+---------------------+------------------------------+ -| :ref:`Color` | font_color_hover | Color( 0.94, 0.94, 0.94, 1 ) | -+---------------------------------+---------------------+------------------------------+ -| :ref:`Color` | font_color_pressed | Color( 1, 1, 1, 1 ) | -+---------------------------------+---------------------+------------------------------+ -| :ref:`StyleBox` | hover | | -+---------------------------------+---------------------+------------------------------+ -| :ref:`int` | hseparation | 2 | -+---------------------------------+---------------------+------------------------------+ -| :ref:`StyleBox` | normal | | -+---------------------------------+---------------------+------------------------------+ -| :ref:`StyleBox` | pressed | | -+---------------------------------+---------------------+------------------------------+ +.. table:: + :widths: auto + + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_color` | ``Color(0.875, 0.875, 0.875, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_disabled_color` | ``Color(0.875, 0.875, 0.875, 0.5)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_focus_color` | ``Color(0.95, 0.95, 0.95, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_hover_color` | ``Color(0.95, 0.95, 0.95, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_hover_pressed_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_outline_color` | ``Color(0, 0, 0, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_pressed_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_disabled_color` | ``Color(1, 1, 1, 0.4)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_focus_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_hover_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_hover_pressed_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_normal_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_pressed_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`align_to_largest_stylebox` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`h_separation` | ``4`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`icon_max_width` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`line_spacing` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`outline_size` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Font` | :ref:`font` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`font_size` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`icon` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`disabled` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`disabled_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`focus` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`hover` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`hover_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`hover_pressed` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`hover_pressed_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`normal` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`normal_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`pressed` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`pressed_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + +.. rst-class:: classref-section-separator -Enumerations ------------- +---- -.. _enum_Button_TextAlign: +.. rst-class:: classref-descriptions-group -.. _class_Button_constant_ALIGN_LEFT: +Property Descriptions +--------------------- -.. _class_Button_constant_ALIGN_CENTER: +.. _class_Button_property_alignment: -.. _class_Button_constant_ALIGN_RIGHT: +.. rst-class:: classref-property -enum **TextAlign**: +:ref:`HorizontalAlignment` **alignment** = ``1`` :ref:`🔗` -- **ALIGN_LEFT** = **0** --- Align the text to the left. +.. rst-class:: classref-property-setget -- **ALIGN_CENTER** = **1** --- Align the text to the center. +- |void| **set_text_alignment**\ (\ value\: :ref:`HorizontalAlignment`\ ) +- :ref:`HorizontalAlignment` **get_text_alignment**\ (\ ) -- **ALIGN_RIGHT** = **2** --- Align the text to the right. +Text alignment policy for the button's text. -Property Descriptions ---------------------- +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_property_autowrap_mode: + +.. rst-class:: classref-property + +:ref:`AutowrapMode` **autowrap_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_autowrap_mode**\ (\ value\: :ref:`AutowrapMode`\ ) +- :ref:`AutowrapMode` **get_autowrap_mode**\ (\ ) -.. _class_Button_property_align: +If set to something other than :ref:`TextServer.AUTOWRAP_OFF`, the text gets wrapped inside the node's bounding rectangle. -- :ref:`TextAlign` **align** +.. rst-class:: classref-item-separator -+-----------+-----------------------+ -| *Default* | ``1`` | -+-----------+-----------------------+ -| *Setter* | set_text_align(value) | -+-----------+-----------------------+ -| *Getter* | get_text_align() | -+-----------+-----------------------+ +---- + +.. _class_Button_property_autowrap_trim_flags: + +.. rst-class:: classref-property + +|bitfield|\[:ref:`LineBreakFlag`\] **autowrap_trim_flags** = ``128`` :ref:`🔗` + +.. rst-class:: classref-property-setget -Text alignment policy for the button's text, use one of the :ref:`TextAlign` constants. +- |void| **set_autowrap_trim_flags**\ (\ value\: |bitfield|\[:ref:`LineBreakFlag`\]\ ) +- |bitfield|\[:ref:`LineBreakFlag`\] **get_autowrap_trim_flags**\ (\ ) + +Autowrap space trimming flags. See :ref:`TextServer.BREAK_TRIM_START_EDGE_SPACES` and :ref:`TextServer.BREAK_TRIM_END_EDGE_SPACES` for more info. + +.. rst-class:: classref-item-separator ---- .. _class_Button_property_clip_text: -- :ref:`bool` **clip_text** +.. rst-class:: classref-property + +:ref:`bool` **clip_text** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_clip_text**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_clip_text**\ (\ ) -+-----------+----------------------+ -| *Default* | ``false`` | -+-----------+----------------------+ -| *Setter* | set_clip_text(value) | -+-----------+----------------------+ -| *Getter* | get_clip_text() | -+-----------+----------------------+ +If ``true``, text that is too large to fit the button is clipped horizontally. If ``false``, the button will always be wide enough to hold the text. The text is not vertically clipped, and the button's height is not affected by this property. -When this property is enabled, text that is too large to fit the button is clipped, when disabled the Button will always be wide enough to hold the text. +.. rst-class:: classref-item-separator ---- .. _class_Button_property_expand_icon: -- :ref:`bool` **expand_icon** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``false`` | -+-----------+------------------------+ -| *Setter* | set_expand_icon(value) | -+-----------+------------------------+ -| *Getter* | is_expand_icon() | -+-----------+------------------------+ +:ref:`bool` **expand_icon** = ``false`` :ref:`🔗` -When enabled, the button's icon will expand/shrink to fit the button's size while keeping its aspect. +.. rst-class:: classref-property-setget + +- |void| **set_expand_icon**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_expand_icon**\ (\ ) + +When enabled, the button's icon will expand/shrink to fit the button's size while keeping its aspect. See also :ref:`icon_max_width`. + +.. rst-class:: classref-item-separator ---- .. _class_Button_property_flat: -- :ref:`bool` **flat** +.. rst-class:: classref-property -+-----------+-----------------+ -| *Default* | ``false`` | -+-----------+-----------------+ -| *Setter* | set_flat(value) | -+-----------+-----------------+ -| *Getter* | is_flat() | -+-----------+-----------------+ +:ref:`bool` **flat** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flat**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_flat**\ (\ ) Flat buttons don't display decoration. +.. rst-class:: classref-item-separator + ---- .. _class_Button_property_icon: -- :ref:`Texture2D` **icon** +.. rst-class:: classref-property -+----------+------------------------+ -| *Setter* | set_button_icon(value) | -+----------+------------------------+ -| *Getter* | get_button_icon() | -+----------+------------------------+ +:ref:`Texture2D` **icon** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_button_icon**\ (\ value\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_button_icon**\ (\ ) Button's icon, if text is present the icon will be placed before the text. +To edit margin and spacing of the icon, use :ref:`h_separation` theme property and ``content_margin_*`` properties of the used :ref:`StyleBox`\ es. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_property_icon_alignment: + +.. rst-class:: classref-property + +:ref:`HorizontalAlignment` **icon_alignment** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_icon_alignment**\ (\ value\: :ref:`HorizontalAlignment`\ ) +- :ref:`HorizontalAlignment` **get_icon_alignment**\ (\ ) + +Specifies if the icon should be aligned horizontally to the left, right, or center of a button. Uses the same :ref:`HorizontalAlignment` constants as the text alignment. If centered horizontally and vertically, text will draw on top of the icon. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_property_language: + +.. rst-class:: classref-property + +:ref:`String` **language** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_language**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_language**\ (\ ) + +Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead. + +.. rst-class:: classref-item-separator + ---- .. _class_Button_property_text: -- :ref:`String` **text** +.. rst-class:: classref-property + +:ref:`String` **text** = ``""`` :ref:`🔗` -+-----------+-----------------+ -| *Default* | ``""`` | -+-----------+-----------------+ -| *Setter* | set_text(value) | -+-----------+-----------------+ -| *Getter* | get_text() | -+-----------+-----------------+ +.. rst-class:: classref-property-setget + +- |void| **set_text**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_text**\ (\ ) The button's text that will be displayed inside the button's area. +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_property_text_direction: + +.. rst-class:: classref-property + +:ref:`TextDirection` **text_direction** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_text_direction**\ (\ value\: :ref:`TextDirection`\ ) +- :ref:`TextDirection` **get_text_direction**\ (\ ) + +Base text writing direction. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_property_text_overrun_behavior: + +.. rst-class:: classref-property + +:ref:`OverrunBehavior` **text_overrun_behavior** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_text_overrun_behavior**\ (\ value\: :ref:`OverrunBehavior`\ ) +- :ref:`OverrunBehavior` **get_text_overrun_behavior**\ (\ ) + +Sets the clipping behavior when the text exceeds the node's bounding rectangle. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_property_vertical_icon_alignment: + +.. rst-class:: classref-property + +:ref:`VerticalAlignment` **vertical_icon_alignment** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_vertical_icon_alignment**\ (\ value\: :ref:`VerticalAlignment`\ ) +- :ref:`VerticalAlignment` **get_vertical_icon_alignment**\ (\ ) + +Specifies if the icon should be aligned vertically to the top, bottom, or center of a button. Uses the same :ref:`VerticalAlignment` constants as the text alignment. If centered horizontally and vertically, text will draw on top of the icon. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Theme Property Descriptions +--------------------------- + +.. _class_Button_theme_color_font_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **font_color** = ``Color(0.875, 0.875, 0.875, 1)`` :ref:`🔗` + +Default text :ref:`Color` of the **Button**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_font_disabled_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **font_disabled_color** = ``Color(0.875, 0.875, 0.875, 0.5)`` :ref:`🔗` + +Text :ref:`Color` used when the **Button** is disabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_font_focus_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **font_focus_color** = ``Color(0.95, 0.95, 0.95, 1)`` :ref:`🔗` + +Text :ref:`Color` used when the **Button** is focused. Only replaces the normal text color of the button. Disabled, hovered, and pressed states take precedence over this color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_font_hover_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **font_hover_color** = ``Color(0.95, 0.95, 0.95, 1)`` :ref:`🔗` + +Text :ref:`Color` used when the **Button** is being hovered. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_font_hover_pressed_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **font_hover_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +Text :ref:`Color` used when the **Button** is being hovered and pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_font_outline_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **font_outline_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +The tint of text outline of the **Button**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_font_pressed_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **font_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +Text :ref:`Color` used when the **Button** is being pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_icon_disabled_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **icon_disabled_color** = ``Color(1, 1, 1, 0.4)`` :ref:`🔗` + +Icon modulate :ref:`Color` used when the **Button** is disabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_icon_focus_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **icon_focus_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +Icon modulate :ref:`Color` used when the **Button** is focused. Only replaces the normal modulate color of the button. Disabled, hovered, and pressed states take precedence over this color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_icon_hover_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **icon_hover_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +Icon modulate :ref:`Color` used when the **Button** is being hovered. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_icon_hover_pressed_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **icon_hover_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +Icon modulate :ref:`Color` used when the **Button** is being hovered and pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_icon_normal_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **icon_normal_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +Default icon modulate :ref:`Color` of the **Button**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_color_icon_pressed_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **icon_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +Icon modulate :ref:`Color` used when the **Button** is being pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_constant_align_to_largest_stylebox: + +.. rst-class:: classref-themeproperty + +:ref:`int` **align_to_largest_stylebox** = ``0`` :ref:`🔗` + +This constant acts as a boolean. If ``true``, the minimum size of the button and text/icon alignment is always based on the largest stylebox margins, otherwise it's based on the current button state stylebox margins. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_constant_h_separation: + +.. rst-class:: classref-themeproperty + +:ref:`int` **h_separation** = ``4`` :ref:`🔗` + +The horizontal space between **Button**'s icon and text. Negative values will be treated as ``0`` when used. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_constant_icon_max_width: + +.. rst-class:: classref-themeproperty + +:ref:`int` **icon_max_width** = ``0`` :ref:`🔗` + +The maximum allowed width of the **Button**'s icon. This limit is applied on top of the default size of the icon, or its expanded size if :ref:`expand_icon` is ``true``. The height is adjusted according to the icon's ratio. If the button has additional icons (e.g. :ref:`CheckBox`), they will also be limited. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_constant_line_spacing: + +.. rst-class:: classref-themeproperty + +:ref:`int` **line_spacing** = ``0`` :ref:`🔗` + +Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_constant_outline_size: + +.. rst-class:: classref-themeproperty + +:ref:`int` **outline_size** = ``0`` :ref:`🔗` + +The size of the text outline. + +\ **Note:** If using a font with :ref:`FontFile.multichannel_signed_distance_field` enabled, its :ref:`FontFile.msdf_pixel_range` must be set to at least *twice* the value of :ref:`outline_size` for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_font_font: + +.. rst-class:: classref-themeproperty + +:ref:`Font` **font** :ref:`🔗` + +:ref:`Font` of the **Button**'s text. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_font_size_font_size: + +.. rst-class:: classref-themeproperty + +:ref:`int` **font_size** :ref:`🔗` + +Font size of the **Button**'s text. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_icon_icon: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **icon** :ref:`🔗` + +Default icon for the **Button**. Appears only if :ref:`icon` is not assigned. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **disabled** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is disabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_disabled_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **disabled_mirrored** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is disabled (for right-to-left layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_focus: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **focus** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is focused. The :ref:`focus` :ref:`StyleBox` is displayed *over* the base :ref:`StyleBox`, so a partially transparent :ref:`StyleBox` should be used to ensure the base :ref:`StyleBox` remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_hover: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **hover** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is being hovered. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_hover_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **hover_mirrored** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is being hovered (for right-to-left layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_hover_pressed: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **hover_pressed** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is being pressed and hovered at the same time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_hover_pressed_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **hover_pressed_mirrored** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is being pressed and hovered at the same time (for right-to-left layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_normal: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **normal** :ref:`🔗` + +Default :ref:`StyleBox` for the **Button**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_normal_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **normal_mirrored** :ref:`🔗` + +Default :ref:`StyleBox` for the **Button** (for right-to-left layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_pressed: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **pressed** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is being pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_style_pressed_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **pressed_mirrored** :ref:`🔗` + +:ref:`StyleBox` used when the **Button** is being pressed (for right-to-left layouts). + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_buttongroup.rst b/classes/class_buttongroup.rst index ad73a2ea40e..ab41d271059 100644 --- a/classes/class_buttongroup.rst +++ b/classes/class_buttongroup.rst @@ -1,55 +1,133 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ButtonGroup.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. meta:: + :keywords: radio + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ButtonGroup.xml. .. _class_ButtonGroup: ButtonGroup =========== -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +A group of buttons that doesn't allow more than one button to be pressed at a time. -Group of Buttons. +.. rst-class:: classref-introduction-group Description ----------- -Group of :ref:`Button`. All direct and indirect children buttons become radios. Only one allows being pressed. +A group of :ref:`BaseButton`-derived buttons. The buttons in a **ButtonGroup** are treated like radio buttons: No more than one button can be pressed at a time. Some types of buttons (such as :ref:`CheckBox`) may have a special appearance in this state. + +Every member of a **ButtonGroup** should have :ref:`BaseButton.toggle_mode` set to ``true``. -:ref:`BaseButton.toggle_mode` should be ``true``. +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------+-------------------------+-----------------+ -| :ref:`bool` | resource_local_to_scene | **O:** ``true`` | -+-------------------------+-------------------------+-----------------+ +.. table:: + :widths: auto + + +-------------------------+----------------------------------------------------------------+---------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`allow_unpress` | ``false`` | + +-------------------------+----------------------------------------------------------------+---------------------------------------------------------------------------------------+ + | :ref:`bool` | resource_local_to_scene | ``true`` (overrides :ref:`Resource`) | + +-------------------------+----------------------------------------------------------------+---------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------+------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_buttons` **(** **)** | -+-------------------------------------+------------------------------------------------------------------------------------+ -| :ref:`BaseButton` | :ref:`get_pressed_button` **(** **)** | -+-------------------------------------+------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`BaseButton`\] | :ref:`get_buttons`\ (\ ) | + +------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`BaseButton` | :ref:`get_pressed_button`\ (\ ) | + +------------------------------------------------------------------+------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_ButtonGroup_signal_pressed: + +.. rst-class:: classref-signal + +**pressed**\ (\ button\: :ref:`BaseButton`\ ) :ref:`🔗` + +Emitted when one of the buttons of the group is pressed. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_ButtonGroup_property_allow_unpress: + +.. rst-class:: classref-property + +:ref:`bool` **allow_unpress** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_allow_unpress**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_allow_unpress**\ (\ ) + +If ``true``, it is possible to unpress all buttons in this **ButtonGroup**. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_ButtonGroup_method_get_buttons: -- :ref:`Array` **get_buttons** **(** **)** +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`BaseButton`\] **get_buttons**\ (\ ) :ref:`🔗` -Returns an :ref:`Array` of :ref:`Button`\ s who have this as their ``ButtonGroup`` (see :ref:`BaseButton.group`). +Returns an :ref:`Array` of :ref:`Button`\ s who have this as their **ButtonGroup** (see :ref:`BaseButton.button_group`). + +.. rst-class:: classref-item-separator ---- .. _class_ButtonGroup_method_get_pressed_button: -- :ref:`BaseButton` **get_pressed_button** **(** **)** +.. rst-class:: classref-method + +:ref:`BaseButton` **get_pressed_button**\ (\ ) :ref:`🔗` Returns the current pressed button. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_callable.rst b/classes/class_callable.rst index 19e83e15798..9ad65d199a5 100644 --- a/classes/class_callable.rst +++ b/classes/class_callable.rst @@ -1,128 +1,567 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Callable.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Callable.xml. .. _class_Callable: Callable ======== -An object representing a method in a certain object that can be called. +A built-in type representing a method or a standalone function. + +.. rst-class:: classref-introduction-group Description ----------- -``Callable`` is a first class object which can be held in variables and passed to functions. It represents a given method in an :ref:`Object`, and is typically used for signal callbacks. +**Callable** is a built-in :ref:`Variant` type that represents a function. It can either be a method within an :ref:`Object` instance, or a custom callable used for different purposes (see :ref:`is_custom()`). Like all :ref:`Variant` types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks. -**Example:** -:: +.. tabs:: + + .. code-tab:: gdscript - var callable = Callable(self, "print_args") func print_args(arg1, arg2, arg3 = ""): prints(arg1, arg2, arg3) + func test(): - callable.call("hello", "world") # Prints "hello world". - callable.call(Vector2.UP, 42, callable) # Prints "(0, -1) 42 Node(Node.gd)::print_args". + var callable = Callable(self, "print_args") + callable.call("hello", "world") # Prints "hello world ". + callable.call(Vector2.UP, 42, callable) # Prints "(0.0, -1.0) 42 Node(node.gd)::print_args" callable.call("invalid") # Invalid call, should have at least 2 arguments. + .. code-tab:: csharp + + // Default parameter values are not supported. + public void PrintArgs(Variant arg1, Variant arg2, Variant arg3 = default) + { + GD.PrintS(arg1, arg2, arg3); + } + + public void Test() + { + // Invalid calls fail silently. + Callable callable = new Callable(this, MethodName.PrintArgs); + callable.Call("hello", "world"); // Default parameter values are not supported, should have 3 arguments. + callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs" + callable.Call("invalid"); // Invalid call, should have 3 arguments. + } + + + +In GDScript, it's possible to create lambda functions within a method. Lambda functions are custom callables that are not associated with an :ref:`Object` instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling :ref:`get_method()`. + +:: + + func _init(): + var my_lambda = func (message): + print(message) + + # Prints "Hello everyone!" + my_lambda.call("Hello everyone!") + + # Prints "Attack!", when the button_pressed signal is emitted. + button_pressed.connect(func(): print("Attack!")) + +In GDScript, you can access methods and global functions as **Callable**\ s: + +:: + + tween.tween_callback(node.queue_free) # Object methods. + tween.tween_callback(array.clear) # Methods of built-in types. + tween.tween_callback(print.bind("Test")) # Global functions. + +\ **Note:** :ref:`Dictionary` does not support the above due to ambiguity with keys. + +:: + + var dictionary = { "hello": "world" } + + # This will not work, `clear` is treated as a key. + tween.tween_callback(dictionary.clear) + + # This will work. + tween.tween_callback(Callable.create(dictionary, "clear")) + +.. note:: + + There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. + +.. rst-class:: classref-reftable-group + +Constructors +------------ + +.. table:: + :widths: auto + + +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Callable` | :ref:`Callable`\ (\ ) | + +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Callable` | :ref:`Callable`\ (\ from\: :ref:`Callable`\ ) | + +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Callable` | :ref:`Callable`\ (\ object\: :ref:`Object`, method\: :ref:`StringName`\ ) | + +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + Methods ------- -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Callable` | :ref:`Callable` **(** :ref:`Object` object, :ref:`StringName` method_name **)** | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`call` **(** ... **)** vararg | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`call_deferred` **(** ... **)** vararg | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_method` **(** **)** | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Object` | :ref:`get_object` **(** **)** | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_object_id` **(** **)** | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`hash` **(** **)** | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_custom` **(** **)** | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_null` **(** **)** | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_standard` **(** **)** | -+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Callable` | :ref:`bind`\ (\ ...\ ) |vararg| |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Callable` | :ref:`bindv`\ (\ arguments\: :ref:`Array`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`call`\ (\ ...\ ) |vararg| |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`call_deferred`\ (\ ...\ ) |vararg| |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`callv`\ (\ arguments\: :ref:`Array`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Callable` | :ref:`create`\ (\ variant\: :ref:`Variant`, method\: :ref:`StringName`\ ) |static| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_argument_count`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`get_bound_arguments`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_bound_arguments_count`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_method`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Object` | :ref:`get_object`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_object_id`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_unbound_arguments_count`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`hash`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_custom`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_null`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_standard`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_valid`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`rpc`\ (\ ...\ ) |vararg| |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`rpc_id`\ (\ peer_id\: :ref:`int`, ...\ ) |vararg| |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Callable` | :ref:`unbind`\ (\ argcount\: :ref:`int`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Operators +--------- + +.. table:: + :widths: auto + + +-------------------------+---------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator !=`\ (\ right\: :ref:`Callable`\ ) | + +-------------------------+---------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator ==`\ (\ right\: :ref:`Callable`\ ) | + +-------------------------+---------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constructor Descriptions +------------------------ + +.. _class_Callable_constructor_Callable: + +.. rst-class:: classref-constructor + +:ref:`Callable` **Callable**\ (\ ) :ref:`🔗` + +Constructs an empty **Callable**, with no object nor method bound. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`Callable` **Callable**\ (\ from\: :ref:`Callable`\ ) + +Constructs a **Callable** as a copy of the given **Callable**. + +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`Callable` **Callable**\ (\ object\: :ref:`Object`, method\: :ref:`StringName`\ ) + +Creates a new **Callable** for the method named ``method`` in the specified ``object``. + +\ **Note:** For methods of built-in :ref:`Variant` types, use :ref:`create()` instead. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_Callable_method_Callable: +.. _class_Callable_method_bind: + +.. rst-class:: classref-method -- :ref:`Callable` **Callable** **(** :ref:`Object` object, :ref:`StringName` method_name **)** +:ref:`Callable` **bind**\ (\ ...\ ) |vararg| |const| :ref:`🔗` -Creates a new ``Callable`` for the method called ``method_name`` in the specified ``object``. +Returns a copy of this **Callable** with one or more arguments bound. When called, the bound arguments are passed *after* the arguments supplied by :ref:`call()`. See also :ref:`unbind()`. + +\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_bindv: + +.. rst-class:: classref-method + +:ref:`Callable` **bindv**\ (\ arguments\: :ref:`Array`\ ) :ref:`🔗` + +Returns a copy of this **Callable** with one or more arguments bound, reading them from an array. When called, the bound arguments are passed *after* the arguments supplied by :ref:`call()`. See also :ref:`unbind()`. + +\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. + +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_call: -- :ref:`Variant` **call** **(** ... **)** vararg +.. rst-class:: classref-method + +:ref:`Variant` **call**\ (\ ...\ ) |vararg| |const| :ref:`🔗` + +Calls the method represented by this **Callable**. Arguments can be passed and should match the method's signature. -Calls the method represented by this ``Callable``. Arguments can be passed and should match the method's signature. +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_call_deferred: -- void **call_deferred** **(** ... **)** vararg +.. rst-class:: classref-method + +|void| **call_deferred**\ (\ ...\ ) |vararg| |const| :ref:`🔗` + +Calls the method represented by this **Callable** in deferred mode, i.e. at the end of the current frame. Arguments can be passed and should match the method's signature. + + +.. tabs:: + + .. code-tab:: gdscript + + func _ready(): + grab_focus.call_deferred() -Calls the method represented by this ``Callable`` in deferred mode, i.e. during the idle frame. Arguments can be passed and should match the method's signature. + .. code-tab:: csharp + + public override void _Ready() + { + Callable.From(GrabFocus).CallDeferred(); + } + + + +\ **Note:** Deferred calls are processed at idle time. Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly. + +See also :ref:`Object.call_deferred()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_callv: + +.. rst-class:: classref-method + +:ref:`Variant` **callv**\ (\ arguments\: :ref:`Array`\ ) |const| :ref:`🔗` + +Calls the method represented by this **Callable**. Unlike :ref:`call()`, this method expects all arguments to be contained inside the ``arguments`` :ref:`Array`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_create: + +.. rst-class:: classref-method + +:ref:`Callable` **create**\ (\ variant\: :ref:`Variant`, method\: :ref:`StringName`\ ) |static| :ref:`🔗` + +Creates a new **Callable** for the method named ``method`` in the specified ``variant``. To represent a method of a built-in :ref:`Variant` type, a custom callable is used (see :ref:`is_custom()`). If ``variant`` is :ref:`Object`, then a standard callable will be created instead. + +\ **Note:** This method is always necessary for the :ref:`Dictionary` type, as property syntax is used to access its entries. You may also use this method when ``variant``'s type is not known in advance (for polymorphism). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_get_argument_count: + +.. rst-class:: classref-method + +:ref:`int` **get_argument_count**\ (\ ) |const| :ref:`🔗` + +Returns the total number of arguments this **Callable** should take, including optional arguments. This means that any arguments bound with :ref:`bind()` are *subtracted* from the result, and any arguments unbound with :ref:`unbind()` are *added* to the result. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_get_bound_arguments: + +.. rst-class:: classref-method + +:ref:`Array` **get_bound_arguments**\ (\ ) |const| :ref:`🔗` + +Returns the array of arguments bound via successive :ref:`bind()` or :ref:`unbind()` calls. These arguments will be added *after* the arguments passed to the call, from which :ref:`get_unbound_arguments_count()` arguments on the right have been previously excluded. + +:: + + func get_effective_arguments(callable, call_args): + assert(call_args.size() - callable.get_unbound_arguments_count() >= 0) + var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count()) + result.append_array(callable.get_bound_arguments()) + return result + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_get_bound_arguments_count: + +.. rst-class:: classref-method + +:ref:`int` **get_bound_arguments_count**\ (\ ) |const| :ref:`🔗` + +Returns the total amount of arguments bound via successive :ref:`bind()` or :ref:`unbind()` calls. This is the same as the size of the array returned by :ref:`get_bound_arguments()`. See :ref:`get_bound_arguments()` for details. + +\ **Note:** The :ref:`get_bound_arguments_count()` and :ref:`get_unbound_arguments_count()` methods can both return positive values. + +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_get_method: -- :ref:`StringName` **get_method** **(** **)** +.. rst-class:: classref-method + +:ref:`StringName` **get_method**\ (\ ) |const| :ref:`🔗` -Returns the name of the method represented by this ``Callable``. +Returns the name of the method represented by this **Callable**. If the callable is a GDScript lambda function, returns the function's name or ``""``. + +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_get_object: -- :ref:`Object` **get_object** **(** **)** +.. rst-class:: classref-method + +:ref:`Object` **get_object**\ (\ ) |const| :ref:`🔗` + +Returns the object on which this **Callable** is called. -Returns the object on which this ``Callable`` is called. +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_get_object_id: -- :ref:`int` **get_object_id** **(** **)** +.. rst-class:: classref-method -Returns the ID of this ``Callable``'s object (see :ref:`Object.get_instance_id`). +:ref:`int` **get_object_id**\ (\ ) |const| :ref:`🔗` + +Returns the ID of this **Callable**'s object (see :ref:`Object.get_instance_id()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_get_unbound_arguments_count: + +.. rst-class:: classref-method + +:ref:`int` **get_unbound_arguments_count**\ (\ ) |const| :ref:`🔗` + +Returns the total amount of arguments unbound via successive :ref:`bind()` or :ref:`unbind()` calls. See :ref:`get_bound_arguments()` for details. + +\ **Note:** The :ref:`get_bound_arguments_count()` and :ref:`get_unbound_arguments_count()` methods can both return positive values. + +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_hash: -- :ref:`int` **hash** **(** **)** +.. rst-class:: classref-method + +:ref:`int` **hash**\ (\ ) |const| :ref:`🔗` + +Returns the 32-bit hash value of this **Callable**'s object. + +\ **Note:** **Callable**\ s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does *not* imply the callables are equal, because different callables can have identical hash values due to hash collisions. The engine uses a 32-bit hash algorithm for :ref:`hash()`. + +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_is_custom: -- :ref:`bool` **is_custom** **(** **)** +.. rst-class:: classref-method + +:ref:`bool` **is_custom**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if this **Callable** is a custom callable. Custom callables are used: + +- for binding/unbinding arguments (see :ref:`bind()` and :ref:`unbind()`); + +- for representing methods of built-in :ref:`Variant` types (see :ref:`create()`); + +- for representing global, lambda, and RPC functions in GDScript; + +- for other purposes in the core, GDExtension, and C#. + +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_is_null: -- :ref:`bool` **is_null** **(** **)** +.. rst-class:: classref-method + +:ref:`bool` **is_null**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if this **Callable** has no target to call the method on. Equivalent to ``callable == Callable()``. + +\ **Note:** This is *not* the same as ``not is_valid()`` and using ``not is_null()`` will *not* guarantee that this callable can be called. Use :ref:`is_valid()` instead. + +.. rst-class:: classref-item-separator ---- .. _class_Callable_method_is_standard: -- :ref:`bool` **is_standard** **(** **)** +.. rst-class:: classref-method + +:ref:`bool` **is_standard**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if this **Callable** is a standard callable. This method is the opposite of :ref:`is_custom()`. Returns ``false`` if this callable is a lambda function. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_is_valid: + +.. rst-class:: classref-method + +:ref:`bool` **is_valid**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the callable's object exists and has a valid method name assigned, or is a custom callable. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_rpc: + +.. rst-class:: classref-method + +|void| **rpc**\ (\ ...\ ) |vararg| |const| :ref:`🔗` + +Perform an RPC (Remote Procedure Call) on all connected peers. This is used for multiplayer and is normally not available, unless the function being called has been marked as *RPC* (using :ref:`@GDScript.@rpc` or :ref:`Node.rpc_config()`). Calling this method on unsupported functions will result in an error. See :ref:`Node.rpc()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_rpc_id: + +.. rst-class:: classref-method + +|void| **rpc_id**\ (\ peer_id\: :ref:`int`, ...\ ) |vararg| |const| :ref:`🔗` + +Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as *RPC* (using :ref:`@GDScript.@rpc` or :ref:`Node.rpc_config()`). Calling this method on unsupported functions will result in an error. See :ref:`Node.rpc_id()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_unbind: + +.. rst-class:: classref-method + +:ref:`Callable` **unbind**\ (\ argcount\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns a copy of this **Callable** with a number of arguments unbound. In other words, when the new callable is called the last few arguments supplied by the user are ignored, according to ``argcount``. The remaining arguments are passed to the callable. This allows to use the original callable in a context that attempts to pass more arguments than this callable can handle, e.g. a signal with a fixed number of arguments. See also :ref:`bind()`. + +\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. + +:: + + func _ready(): + foo.unbind(1).call(1, 2) # Calls foo(1). + foo.bind(3, 4).unbind(1).call(1, 2) # Calls foo(1, 3, 4), note that it does not change the arguments from bind. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Operator Descriptions +--------------------- + +.. _class_Callable_operator_neq_Callable: + +.. rst-class:: classref-operator + +:ref:`bool` **operator !=**\ (\ right\: :ref:`Callable`\ ) :ref:`🔗` + +Returns ``true`` if both **Callable**\ s invoke different targets. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_operator_eq_Callable: + +.. rst-class:: classref-operator + +:ref:`bool` **operator ==**\ (\ right\: :ref:`Callable`\ ) :ref:`🔗` + +Returns ``true`` if both **Callable**\ s invoke the same custom target. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_callbacktweener.rst b/classes/class_callbacktweener.rst new file mode 100644 index 00000000000..ce57848a558 --- /dev/null +++ b/classes/class_callbacktweener.rst @@ -0,0 +1,72 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CallbackTweener.xml. + +.. _class_CallbackTweener: + +CallbackTweener +=============== + +**Inherits:** :ref:`Tweener` **<** :ref:`RefCounted` **<** :ref:`Object` + +Calls the specified method after optional delay. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**CallbackTweener** is used to call a method in a tweening sequence. See :ref:`Tween.tween_callback()` for more usage information. + +The tweener will finish automatically if the callback's target object is freed. + +\ **Note:** :ref:`Tween.tween_callback()` is the only correct way to create **CallbackTweener**. Any **CallbackTweener** created manually will not function correctly. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | :ref:`CallbackTweener` | :ref:`set_delay`\ (\ delay\: :ref:`float`\ ) | + +-----------------------------------------------+---------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CallbackTweener_method_set_delay: + +.. rst-class:: classref-method + +:ref:`CallbackTweener` **set_delay**\ (\ delay\: :ref:`float`\ ) :ref:`🔗` + +Makes the callback call delayed by given time in seconds. + +\ **Example:** Call :ref:`Node.queue_free()` after 2 seconds: + +:: + + var tween = get_tree().create_tween() + tween.tween_callback(queue_free).set_delay(2) + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_camera.rst b/classes/class_camera.rst deleted file mode 100644 index 252fcd0c947..00000000000 --- a/classes/class_camera.rst +++ /dev/null @@ -1,493 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Camera.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_Camera: - -Camera -====== - -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -**Inherited By:** :ref:`ARVRCamera`, :ref:`ClippedCamera`, :ref:`InterpolatedCamera` - -Camera node, displays from a point of view. - -Description ------------ - -Camera is a special node that displays what is visible from its current location. Cameras register themselves in the nearest :ref:`Viewport` node (when ascending the tree). Only one camera can be active per viewport. If no viewport is available ascending the tree, the camera will register in the global viewport. In other words, a camera just provides 3D display capabilities to a :ref:`Viewport`, and, without one, a scene registered in that :ref:`Viewport` (or higher viewports) can't be displayed. - -Properties ----------- - -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`cull_mask` | ``1048575`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`current` | ``false`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`DopplerTracking` | :ref:`doppler_tracking` | ``0`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`CameraEffects` | :ref:`effects` | | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`Environment` | :ref:`environment` | | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`far` | ``100.0`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`fov` | ``70.0`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`frustum_offset` | ``Vector2( 0, 0 )`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`h_offset` | ``0.0`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`KeepAspect` | :ref:`keep_aspect` | ``1`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`near` | ``0.05`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`Projection` | :ref:`projection` | ``0`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`size` | ``1.0`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`v_offset` | ``0.0`` | -+-----------------------------------------------------+-----------------------------------------------------------------+---------------------+ - -Methods -------- - -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_current` **(** :ref:`bool` enable_next=true **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`RID` | :ref:`get_camera_rid` **(** **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform` | :ref:`get_camera_transform` **(** **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_cull_mask_bit` **(** :ref:`int` layer **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_frustum` **(** **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_position_behind` **(** :ref:`Vector3` world_point **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`make_current` **(** **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`project_local_ray_normal` **(** :ref:`Vector2` screen_point **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`project_position` **(** :ref:`Vector2` screen_point, :ref:`float` z_depth **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`project_ray_normal` **(** :ref:`Vector2` screen_point **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector3` | :ref:`project_ray_origin` **(** :ref:`Vector2` screen_point **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_cull_mask_bit` **(** :ref:`int` layer, :ref:`bool` enable **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_frustum` **(** :ref:`float` size, :ref:`Vector2` offset, :ref:`float` z_near, :ref:`float` z_far **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_orthogonal` **(** :ref:`float` size, :ref:`float` z_near, :ref:`float` z_far **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_perspective` **(** :ref:`float` fov, :ref:`float` z_near, :ref:`float` z_far **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`unproject_position` **(** :ref:`Vector3` world_point **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Enumerations ------------- - -.. _enum_Camera_Projection: - -.. _class_Camera_constant_PROJECTION_PERSPECTIVE: - -.. _class_Camera_constant_PROJECTION_ORTHOGONAL: - -.. _class_Camera_constant_PROJECTION_FRUSTUM: - -enum **Projection**: - -- **PROJECTION_PERSPECTIVE** = **0** --- Perspective projection. Objects on the screen becomes smaller when they are far away. - -- **PROJECTION_ORTHOGONAL** = **1** --- Orthogonal projection, also known as orthographic projection. Objects remain the same size on the screen no matter how far away they are. - -- **PROJECTION_FRUSTUM** = **2** --- Frustum projection. This mode allows adjusting :ref:`frustum_offset` to create "tilted frustum" effects. - ----- - -.. _enum_Camera_KeepAspect: - -.. _class_Camera_constant_KEEP_WIDTH: - -.. _class_Camera_constant_KEEP_HEIGHT: - -enum **KeepAspect**: - -- **KEEP_WIDTH** = **0** --- Preserves the horizontal aspect ratio; also known as Vert- scaling. This is usually the best option for projects running in portrait mode, as taller aspect ratios will benefit from a wider vertical FOV. - -- **KEEP_HEIGHT** = **1** --- Preserves the vertical aspect ratio; also known as Hor+ scaling. This is usually the best option for projects running in landscape mode, as wider aspect ratios will automatically benefit from a wider horizontal FOV. - ----- - -.. _enum_Camera_DopplerTracking: - -.. _class_Camera_constant_DOPPLER_TRACKING_DISABLED: - -.. _class_Camera_constant_DOPPLER_TRACKING_IDLE_STEP: - -.. _class_Camera_constant_DOPPLER_TRACKING_PHYSICS_STEP: - -enum **DopplerTracking**: - -- **DOPPLER_TRACKING_DISABLED** = **0** --- Disables `Doppler effect `_ simulation (default). - -- **DOPPLER_TRACKING_IDLE_STEP** = **1** --- Simulate `Doppler effect `_ by tracking positions of objects that are changed in ``_process``. Changes in the relative velocity of this camera compared to those objects affect how Audio is perceived (changing the Audio's ``pitch shift``). - -- **DOPPLER_TRACKING_PHYSICS_STEP** = **2** --- Simulate `Doppler effect `_ by tracking positions of objects that are changed in ``_physics_process``. Changes in the relative velocity of this camera compared to those objects affect how Audio is perceived (changing the Audio's ``pitch shift``). - -Property Descriptions ---------------------- - -.. _class_Camera_property_cull_mask: - -- :ref:`int` **cull_mask** - -+-----------+----------------------+ -| *Default* | ``1048575`` | -+-----------+----------------------+ -| *Setter* | set_cull_mask(value) | -+-----------+----------------------+ -| *Getter* | get_cull_mask() | -+-----------+----------------------+ - -The culling mask that describes which 3D render layers are rendered by this camera. - ----- - -.. _class_Camera_property_current: - -- :ref:`bool` **current** - -+-----------+--------------------+ -| *Default* | ``false`` | -+-----------+--------------------+ -| *Setter* | set_current(value) | -+-----------+--------------------+ -| *Getter* | is_current() | -+-----------+--------------------+ - -If ``true``, the ancestor :ref:`Viewport` is currently using this camera. - ----- - -.. _class_Camera_property_doppler_tracking: - -- :ref:`DopplerTracking` **doppler_tracking** - -+-----------+-----------------------------+ -| *Default* | ``0`` | -+-----------+-----------------------------+ -| *Setter* | set_doppler_tracking(value) | -+-----------+-----------------------------+ -| *Getter* | get_doppler_tracking() | -+-----------+-----------------------------+ - -If not :ref:`DOPPLER_TRACKING_DISABLED`, this camera will simulate the `Doppler effect `_ for objects changed in particular ``_process`` methods. See :ref:`DopplerTracking` for possible values. - ----- - -.. _class_Camera_property_effects: - -- :ref:`CameraEffects` **effects** - -+----------+--------------------+ -| *Setter* | set_effects(value) | -+----------+--------------------+ -| *Getter* | get_effects() | -+----------+--------------------+ - ----- - -.. _class_Camera_property_environment: - -- :ref:`Environment` **environment** - -+----------+------------------------+ -| *Setter* | set_environment(value) | -+----------+------------------------+ -| *Getter* | get_environment() | -+----------+------------------------+ - -The :ref:`Environment` to use for this camera. - ----- - -.. _class_Camera_property_far: - -- :ref:`float` **far** - -+-----------+-----------------+ -| *Default* | ``100.0`` | -+-----------+-----------------+ -| *Setter* | set_zfar(value) | -+-----------+-----------------+ -| *Getter* | get_zfar() | -+-----------+-----------------+ - -The distance to the far culling boundary for this camera relative to its local Z axis. - ----- - -.. _class_Camera_property_fov: - -- :ref:`float` **fov** - -+-----------+----------------+ -| *Default* | ``70.0`` | -+-----------+----------------+ -| *Setter* | set_fov(value) | -+-----------+----------------+ -| *Getter* | get_fov() | -+-----------+----------------+ - -The camera's field of view angle (in degrees). Only applicable in perspective mode. Since :ref:`keep_aspect` locks one axis, ``fov`` sets the other axis' field of view angle. - ----- - -.. _class_Camera_property_frustum_offset: - -- :ref:`Vector2` **frustum_offset** - -+-----------+---------------------------+ -| *Default* | ``Vector2( 0, 0 )`` | -+-----------+---------------------------+ -| *Setter* | set_frustum_offset(value) | -+-----------+---------------------------+ -| *Getter* | get_frustum_offset() | -+-----------+---------------------------+ - -The camera's frustum offset. This can be changed from the default to create "tilted frustum" effects such as `Y-shearing `_. - ----- - -.. _class_Camera_property_h_offset: - -- :ref:`float` **h_offset** - -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_h_offset(value) | -+-----------+---------------------+ -| *Getter* | get_h_offset() | -+-----------+---------------------+ - -The horizontal (X) offset of the camera viewport. - ----- - -.. _class_Camera_property_keep_aspect: - -- :ref:`KeepAspect` **keep_aspect** - -+-----------+-----------------------------+ -| *Default* | ``1`` | -+-----------+-----------------------------+ -| *Setter* | set_keep_aspect_mode(value) | -+-----------+-----------------------------+ -| *Getter* | get_keep_aspect_mode() | -+-----------+-----------------------------+ - -The axis to lock during :ref:`fov`/:ref:`size` adjustments. Can be either :ref:`KEEP_WIDTH` or :ref:`KEEP_HEIGHT`. - ----- - -.. _class_Camera_property_near: - -- :ref:`float` **near** - -+-----------+------------------+ -| *Default* | ``0.05`` | -+-----------+------------------+ -| *Setter* | set_znear(value) | -+-----------+------------------+ -| *Getter* | get_znear() | -+-----------+------------------+ - -The distance to the near culling boundary for this camera relative to its local Z axis. - ----- - -.. _class_Camera_property_projection: - -- :ref:`Projection` **projection** - -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_projection(value) | -+-----------+-----------------------+ -| *Getter* | get_projection() | -+-----------+-----------------------+ - -The camera's projection mode. In :ref:`PROJECTION_PERSPECTIVE` mode, objects' Z distance from the camera's local space scales their perceived size. - ----- - -.. _class_Camera_property_size: - -- :ref:`float` **size** - -+-----------+-----------------+ -| *Default* | ``1.0`` | -+-----------+-----------------+ -| *Setter* | set_size(value) | -+-----------+-----------------+ -| *Getter* | get_size() | -+-----------+-----------------+ - -The camera's size measured as 1/2 the width or height. Only applicable in orthogonal mode. Since :ref:`keep_aspect` locks on axis, ``size`` sets the other axis' size length. - ----- - -.. _class_Camera_property_v_offset: - -- :ref:`float` **v_offset** - -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_v_offset(value) | -+-----------+---------------------+ -| *Getter* | get_v_offset() | -+-----------+---------------------+ - -The vertical (Y) offset of the camera viewport. - -Method Descriptions -------------------- - -.. _class_Camera_method_clear_current: - -- void **clear_current** **(** :ref:`bool` enable_next=true **)** - -If this is the current camera, remove it from being current. If ``enable_next`` is ``true``, request to make the next camera current, if any. - ----- - -.. _class_Camera_method_get_camera_rid: - -- :ref:`RID` **get_camera_rid** **(** **)** const - -Returns the camera's RID from the :ref:`VisualServer`. - ----- - -.. _class_Camera_method_get_camera_transform: - -- :ref:`Transform` **get_camera_transform** **(** **)** const - -Gets the camera transform. Subclassed cameras such as :ref:`InterpolatedCamera` may provide different transforms than the :ref:`Node` transform. - ----- - -.. _class_Camera_method_get_cull_mask_bit: - -- :ref:`bool` **get_cull_mask_bit** **(** :ref:`int` layer **)** const - -Returns ``true`` if the given ``layer`` in the :ref:`cull_mask` is enabled, ``false`` otherwise. - ----- - -.. _class_Camera_method_get_frustum: - -- :ref:`Array` **get_frustum** **(** **)** const - -Returns the camera's frustum planes in world-space units as an array of :ref:`Plane`\ s in the following order: near, far, left, top, right, bottom. Not to be confused with :ref:`frustum_offset`. - ----- - -.. _class_Camera_method_is_position_behind: - -- :ref:`bool` **is_position_behind** **(** :ref:`Vector3` world_point **)** const - -Returns ``true`` if the given position is behind the camera. - -**Note:** A position which returns ``false`` may still be outside the camera's field of view. - ----- - -.. _class_Camera_method_make_current: - -- void **make_current** **(** **)** - -Makes this camera the current camera for the :ref:`Viewport` (see class description). If the camera node is outside the scene tree, it will attempt to become current once it's added. - ----- - -.. _class_Camera_method_project_local_ray_normal: - -- :ref:`Vector3` **project_local_ray_normal** **(** :ref:`Vector2` screen_point **)** const - -Returns a normal vector from the screen point location directed along the camera. Orthogonal cameras are normalized. Perspective cameras account for perspective, screen width/height, etc. - ----- - -.. _class_Camera_method_project_position: - -- :ref:`Vector3` **project_position** **(** :ref:`Vector2` screen_point, :ref:`float` z_depth **)** const - -Returns the 3D point in worldspace that maps to the given 2D coordinate in the :ref:`Viewport` rectangle on a plane that is the given ``z_depth`` distance into the scene away from the camera. - ----- - -.. _class_Camera_method_project_ray_normal: - -- :ref:`Vector3` **project_ray_normal** **(** :ref:`Vector2` screen_point **)** const - -Returns a normal vector in worldspace, that is the result of projecting a point on the :ref:`Viewport` rectangle by the camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. - ----- - -.. _class_Camera_method_project_ray_origin: - -- :ref:`Vector3` **project_ray_origin** **(** :ref:`Vector2` screen_point **)** const - -Returns a 3D position in worldspace, that is the result of projecting a point on the :ref:`Viewport` rectangle by the camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. - ----- - -.. _class_Camera_method_set_cull_mask_bit: - -- void **set_cull_mask_bit** **(** :ref:`int` layer, :ref:`bool` enable **)** - -Enables or disables the given ``layer`` in the :ref:`cull_mask`. - ----- - -.. _class_Camera_method_set_frustum: - -- void **set_frustum** **(** :ref:`float` size, :ref:`Vector2` offset, :ref:`float` z_near, :ref:`float` z_far **)** - -Sets the camera projection to frustum mode (see :ref:`PROJECTION_FRUSTUM`), by specifying a ``size``, an ``offset``, and the ``z_near`` and ``z_far`` clip planes in world-space units. - ----- - -.. _class_Camera_method_set_orthogonal: - -- void **set_orthogonal** **(** :ref:`float` size, :ref:`float` z_near, :ref:`float` z_far **)** - -Sets the camera projection to orthogonal mode (see :ref:`PROJECTION_ORTHOGONAL`), by specifying a ``size``, and the ``z_near`` and ``z_far`` clip planes in world-space units. (As a hint, 2D games often use this projection, with values specified in pixels.) - ----- - -.. _class_Camera_method_set_perspective: - -- void **set_perspective** **(** :ref:`float` fov, :ref:`float` z_near, :ref:`float` z_far **)** - -Sets the camera projection to perspective mode (see :ref:`PROJECTION_PERSPECTIVE`), by specifying a ``fov`` (field of view) angle in degrees, and the ``z_near`` and ``z_far`` clip planes in world-space units. - ----- - -.. _class_Camera_method_unproject_position: - -- :ref:`Vector2` **unproject_position** **(** :ref:`Vector3` world_point **)** const - -Returns the 2D coordinate in the :ref:`Viewport` rectangle that maps to the given 3D point in worldspace. - diff --git a/classes/class_camera2d.rst b/classes/class_camera2d.rst index 59250b0bcc0..ef8d99ed917 100644 --- a/classes/class_camera2d.rst +++ b/classes/class_camera2d.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Camera2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Camera2D.xml. .. _class_Camera2D: @@ -13,613 +14,843 @@ Camera2D Camera node for 2D scenes. +.. rst-class:: classref-introduction-group + Description ----------- Camera node for 2D scenes. It forces the screen (current layer) to scroll following this node. This makes it easier (and faster) to program scrollable scenes than manually changing the position of :ref:`CanvasItem`-based nodes. -This node is intended to be a simple helper to get things going quickly and it may happen that more functionality is desired to change how the camera works. To make your own custom camera node, simply inherit from :ref:`Node2D` and change the transform of the canvas by calling get_viewport().set_canvas_transform(m) in :ref:`Viewport`. +Cameras register themselves in the nearest :ref:`Viewport` node (when ascending the tree). Only one camera can be active per viewport. If no viewport is available ascending the tree, the camera will register in the global viewport. + +This node is intended to be a simple helper to get things going quickly, but more functionality may be desired to change how the camera works. To make your own custom camera node, inherit it from :ref:`Node2D` and change the transform of the canvas by setting :ref:`Viewport.canvas_transform` in :ref:`Viewport` (you can obtain the current :ref:`Viewport` by using :ref:`Node.get_viewport()`). + +Note that the **Camera2D** node's :ref:`Node2D.global_position` doesn't represent the actual position of the screen, which may differ due to applied smoothing or limits. You can use :ref:`get_screen_center_position()` to get the real position. Same for the node's :ref:`Node2D.global_rotation` which may be different due to applied rotation smoothing. You can use :ref:`get_screen_rotation()` to get the current rotation of the screen. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `2D Platformer Demo `__ + +- `2D Isometric Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`AnchorMode` | :ref:`anchor_mode` | ``1`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`current` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`Node` | :ref:`custom_viewport` | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`drag_margin_bottom` | ``0.2`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`drag_margin_h_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`drag_margin_left` | ``0.2`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`drag_margin_right` | ``0.2`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`drag_margin_top` | ``0.2`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`drag_margin_v_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`editor_draw_drag_margin` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`editor_draw_limits` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`editor_draw_screen` | ``true`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`limit_bottom` | ``10000000`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`limit_left` | ``-10000000`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`limit_right` | ``10000000`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`limit_smoothed` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`limit_top` | ``-10000000`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`offset` | ``Vector2( 0, 0 )`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`offset_h` | ``0.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`offset_v` | ``0.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`Camera2DProcessMode` | :ref:`process_mode` | ``1`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`rotating` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`smoothing_enabled` | ``false`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`smoothing_speed` | ``5.0`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`zoom` | ``Vector2( 1, 1 )`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+---------------------+ +.. table:: + :widths: auto + + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`AnchorMode` | :ref:`anchor_mode` | ``1`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`Node` | :ref:`custom_viewport` | | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`drag_bottom_margin` | ``0.2`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`drag_horizontal_enabled` | ``false`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`drag_horizontal_offset` | ``0.0`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`drag_left_margin` | ``0.2`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`drag_right_margin` | ``0.2`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`drag_top_margin` | ``0.2`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`drag_vertical_enabled` | ``false`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`drag_vertical_offset` | ``0.0`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`editor_draw_drag_margin` | ``false`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`editor_draw_limits` | ``false`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`editor_draw_screen` | ``true`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`enabled` | ``true`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`ignore_rotation` | ``true`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`int` | :ref:`limit_bottom` | ``10000000`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`limit_enabled` | ``true`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`int` | :ref:`limit_left` | ``-10000000`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`int` | :ref:`limit_right` | ``10000000`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`limit_smoothed` | ``false`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`int` | :ref:`limit_top` | ``-10000000`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`Vector2` | :ref:`offset` | ``Vector2(0, 0)`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`position_smoothing_enabled` | ``false`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`position_smoothing_speed` | ``5.0`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`Camera2DProcessCallback` | :ref:`process_callback` | ``1`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`rotation_smoothing_enabled` | ``false`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`rotation_smoothing_speed` | ``5.0`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`Vector2` | :ref:`zoom` | ``Vector2(1, 1)`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`align` **(** **)** | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_current` **(** **)** | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`force_update_scroll` **(** **)** | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_camera_position` **(** **)** const | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_camera_screen_center` **(** **)** const | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_drag_margin` **(** :ref:`Margin` margin **)** const | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_limit` **(** :ref:`Margin` margin **)** const | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`make_current` **(** **)** | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`reset_smoothing` **(** **)** | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_drag_margin` **(** :ref:`Margin` margin, :ref:`float` drag_margin **)** | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_limit` **(** :ref:`Margin` margin, :ref:`int` limit **)** | -+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`align`\ (\ ) | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`force_update_scroll`\ (\ ) | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_drag_margin`\ (\ margin\: :ref:`Side`\ ) |const| | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_limit`\ (\ margin\: :ref:`Side`\ ) |const| | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_screen_center_position`\ (\ ) |const| | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_screen_rotation`\ (\ ) |const| | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_target_position`\ (\ ) |const| | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_current`\ (\ ) |const| | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`make_current`\ (\ ) | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`reset_smoothing`\ (\ ) | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_drag_margin`\ (\ margin\: :ref:`Side`, drag_margin\: :ref:`float`\ ) | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_limit`\ (\ margin\: :ref:`Side`, limit\: :ref:`int`\ ) | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_Camera2D_AnchorMode: +.. rst-class:: classref-enumeration + +enum **AnchorMode**: :ref:`🔗` + .. _class_Camera2D_constant_ANCHOR_MODE_FIXED_TOP_LEFT: +.. rst-class:: classref-enumeration-constant + +:ref:`AnchorMode` **ANCHOR_MODE_FIXED_TOP_LEFT** = ``0`` + +The camera's position is fixed so that the top-left corner is always at the origin. + .. _class_Camera2D_constant_ANCHOR_MODE_DRAG_CENTER: -enum **AnchorMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`AnchorMode` **ANCHOR_MODE_DRAG_CENTER** = ``1`` -- **ANCHOR_MODE_FIXED_TOP_LEFT** = **0** --- The camera's position is fixed so that the top-left corner is always at the origin. +The camera's position takes into account vertical/horizontal offsets and the screen size. -- **ANCHOR_MODE_DRAG_CENTER** = **1** --- The camera's position takes into account vertical/horizontal offsets and the screen size. +.. rst-class:: classref-item-separator ---- -.. _enum_Camera2D_Camera2DProcessMode: +.. _enum_Camera2D_Camera2DProcessCallback: + +.. rst-class:: classref-enumeration + +enum **Camera2DProcessCallback**: :ref:`🔗` .. _class_Camera2D_constant_CAMERA2D_PROCESS_PHYSICS: +.. rst-class:: classref-enumeration-constant + +:ref:`Camera2DProcessCallback` **CAMERA2D_PROCESS_PHYSICS** = ``0`` + +The camera updates during physics frames (see :ref:`Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS`). + .. _class_Camera2D_constant_CAMERA2D_PROCESS_IDLE: -enum **Camera2DProcessMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`Camera2DProcessCallback` **CAMERA2D_PROCESS_IDLE** = ``1`` + +The camera updates during process frames (see :ref:`Node.NOTIFICATION_INTERNAL_PROCESS`). -- **CAMERA2D_PROCESS_PHYSICS** = **0** --- The camera updates with the ``_physics_process`` callback. +.. rst-class:: classref-section-separator + +---- -- **CAMERA2D_PROCESS_IDLE** = **1** --- The camera updates with the ``_process`` callback. +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_Camera2D_property_anchor_mode: -- :ref:`AnchorMode` **anchor_mode** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``1`` | -+-----------+------------------------+ -| *Setter* | set_anchor_mode(value) | -+-----------+------------------------+ -| *Getter* | get_anchor_mode() | -+-----------+------------------------+ +:ref:`AnchorMode` **anchor_mode** = ``1`` :ref:`🔗` -The Camera2D's anchor point. See :ref:`AnchorMode` constants. +.. rst-class:: classref-property-setget + +- |void| **set_anchor_mode**\ (\ value\: :ref:`AnchorMode`\ ) +- :ref:`AnchorMode` **get_anchor_mode**\ (\ ) + +The Camera2D's anchor point. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_current: +.. _class_Camera2D_property_custom_viewport: + +.. rst-class:: classref-property + +:ref:`Node` **custom_viewport** :ref:`🔗` -- :ref:`bool` **current** +.. rst-class:: classref-property-setget -+-----------+--------------+ -| *Default* | ``false`` | -+-----------+--------------+ -| *Getter* | is_current() | -+-----------+--------------+ +- |void| **set_custom_viewport**\ (\ value\: :ref:`Node`\ ) +- :ref:`Node` **get_custom_viewport**\ (\ ) -If ``true``, the camera is the active camera for the current scene. Only one camera can be current, so setting a different camera ``current`` will disable this one. +The custom :ref:`Viewport` node attached to the **Camera2D**. If ``null`` or not a :ref:`Viewport`, uses the default viewport instead. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_custom_viewport: +.. _class_Camera2D_property_drag_bottom_margin: + +.. rst-class:: classref-property + +:ref:`float` **drag_bottom_margin** = ``0.2`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`Node` **custom_viewport** +- |void| **set_drag_margin**\ (\ margin\: :ref:`Side`, drag_margin\: :ref:`float`\ ) +- :ref:`float` **get_drag_margin**\ (\ margin\: :ref:`Side`\ ) |const| -+----------+----------------------------+ -| *Setter* | set_custom_viewport(value) | -+----------+----------------------------+ -| *Getter* | get_custom_viewport() | -+----------+----------------------------+ +Bottom margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the bottom edge of the screen. -The custom :ref:`Viewport` node attached to the ``Camera2D``. If ``null`` or not a :ref:`Viewport`, uses the default viewport instead. +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_drag_margin_bottom: +.. _class_Camera2D_property_drag_horizontal_enabled: -- :ref:`float` **drag_margin_bottom** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``0.2`` | -+-----------+------------------------+ -| *Setter* | set_drag_margin(value) | -+-----------+------------------------+ -| *Getter* | get_drag_margin() | -+-----------+------------------------+ +:ref:`bool` **drag_horizontal_enabled** = ``false`` :ref:`🔗` -Bottom margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the edge of the screen. +.. rst-class:: classref-property-setget + +- |void| **set_drag_horizontal_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_drag_horizontal_enabled**\ (\ ) + +If ``true``, the camera only moves when reaching the horizontal (left and right) drag margins. If ``false``, the camera moves horizontally regardless of margins. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_drag_margin_h_enabled: +.. _class_Camera2D_property_drag_horizontal_offset: + +.. rst-class:: classref-property + +:ref:`float` **drag_horizontal_offset** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`bool` **drag_margin_h_enabled** +- |void| **set_drag_horizontal_offset**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_drag_horizontal_offset**\ (\ ) -+-----------+---------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------+ -| *Setter* | set_h_drag_enabled(value) | -+-----------+---------------------------+ -| *Getter* | is_h_drag_enabled() | -+-----------+---------------------------+ +The relative horizontal drag offset of the camera between the right (``-1``) and left (``1``) drag margins. -If ``true``, the camera only moves when reaching the horizontal drag margins. If ``false``, the camera moves horizontally regardless of margins. +\ **Note:** Used to set the initial horizontal drag offset; determine the current offset; or force the current offset. It's not automatically updated when :ref:`drag_horizontal_enabled` is ``true`` or the drag margins are changed. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_drag_margin_left: +.. _class_Camera2D_property_drag_left_margin: + +.. rst-class:: classref-property + +:ref:`float` **drag_left_margin** = ``0.2`` :ref:`🔗` -- :ref:`float` **drag_margin_left** +.. rst-class:: classref-property-setget -+-----------+------------------------+ -| *Default* | ``0.2`` | -+-----------+------------------------+ -| *Setter* | set_drag_margin(value) | -+-----------+------------------------+ -| *Getter* | get_drag_margin() | -+-----------+------------------------+ +- |void| **set_drag_margin**\ (\ margin\: :ref:`Side`, drag_margin\: :ref:`float`\ ) +- :ref:`float` **get_drag_margin**\ (\ margin\: :ref:`Side`\ ) |const| -Left margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the edge of the screen. +Left margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the left edge of the screen. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_drag_margin_right: +.. _class_Camera2D_property_drag_right_margin: + +.. rst-class:: classref-property -- :ref:`float` **drag_margin_right** +:ref:`float` **drag_right_margin** = ``0.2`` :ref:`🔗` -+-----------+------------------------+ -| *Default* | ``0.2`` | -+-----------+------------------------+ -| *Setter* | set_drag_margin(value) | -+-----------+------------------------+ -| *Getter* | get_drag_margin() | -+-----------+------------------------+ +.. rst-class:: classref-property-setget -Right margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the edge of the screen. +- |void| **set_drag_margin**\ (\ margin\: :ref:`Side`, drag_margin\: :ref:`float`\ ) +- :ref:`float` **get_drag_margin**\ (\ margin\: :ref:`Side`\ ) |const| + +Right margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the right edge of the screen. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera2D_property_drag_top_margin: + +.. rst-class:: classref-property + +:ref:`float` **drag_top_margin** = ``0.2`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_drag_margin**\ (\ margin\: :ref:`Side`, drag_margin\: :ref:`float`\ ) +- :ref:`float` **get_drag_margin**\ (\ margin\: :ref:`Side`\ ) |const| + +Top margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the top edge of the screen. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_drag_margin_top: +.. _class_Camera2D_property_drag_vertical_enabled: -- :ref:`float` **drag_margin_top** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``0.2`` | -+-----------+------------------------+ -| *Setter* | set_drag_margin(value) | -+-----------+------------------------+ -| *Getter* | get_drag_margin() | -+-----------+------------------------+ +:ref:`bool` **drag_vertical_enabled** = ``false`` :ref:`🔗` -Top margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the edge of the screen. +.. rst-class:: classref-property-setget + +- |void| **set_drag_vertical_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_drag_vertical_enabled**\ (\ ) + +If ``true``, the camera only moves when reaching the vertical (top and bottom) drag margins. If ``false``, the camera moves vertically regardless of the drag margins. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_drag_margin_v_enabled: +.. _class_Camera2D_property_drag_vertical_offset: + +.. rst-class:: classref-property + +:ref:`float` **drag_vertical_offset** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`bool` **drag_margin_v_enabled** +- |void| **set_drag_vertical_offset**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_drag_vertical_offset**\ (\ ) -+-----------+---------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------+ -| *Setter* | set_v_drag_enabled(value) | -+-----------+---------------------------+ -| *Getter* | is_v_drag_enabled() | -+-----------+---------------------------+ +The relative vertical drag offset of the camera between the bottom (``-1``) and top (``1``) drag margins. -If ``true``, the camera only moves when reaching the vertical drag margins. If ``false``, the camera moves vertically regardless of margins. +\ **Note:** Used to set the initial vertical drag offset; determine the current offset; or force the current offset. It's not automatically updated when :ref:`drag_vertical_enabled` is ``true`` or the drag margins are changed. + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_property_editor_draw_drag_margin: -- :ref:`bool` **editor_draw_drag_margin** +.. rst-class:: classref-property + +:ref:`bool` **editor_draw_drag_margin** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------------------+ -| *Default* | ``false`` | -+-----------+-----------------------------------+ -| *Setter* | set_margin_drawing_enabled(value) | -+-----------+-----------------------------------+ -| *Getter* | is_margin_drawing_enabled() | -+-----------+-----------------------------------+ +- |void| **set_margin_drawing_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_margin_drawing_enabled**\ (\ ) If ``true``, draws the camera's drag margin rectangle in the editor. +.. rst-class:: classref-item-separator + ---- .. _class_Camera2D_property_editor_draw_limits: -- :ref:`bool` **editor_draw_limits** +.. rst-class:: classref-property + +:ref:`bool` **editor_draw_limits** = ``false`` :ref:`🔗` -+-----------+----------------------------------+ -| *Default* | ``false`` | -+-----------+----------------------------------+ -| *Setter* | set_limit_drawing_enabled(value) | -+-----------+----------------------------------+ -| *Getter* | is_limit_drawing_enabled() | -+-----------+----------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_limit_drawing_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_limit_drawing_enabled**\ (\ ) If ``true``, draws the camera's limits rectangle in the editor. +.. rst-class:: classref-item-separator + ---- .. _class_Camera2D_property_editor_draw_screen: -- :ref:`bool` **editor_draw_screen** +.. rst-class:: classref-property + +:ref:`bool` **editor_draw_screen** = ``true`` :ref:`🔗` -+-----------+-----------------------------------+ -| *Default* | ``true`` | -+-----------+-----------------------------------+ -| *Setter* | set_screen_drawing_enabled(value) | -+-----------+-----------------------------------+ -| *Getter* | is_screen_drawing_enabled() | -+-----------+-----------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_screen_drawing_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_screen_drawing_enabled**\ (\ ) If ``true``, draws the camera's screen rectangle in the editor. +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera2D_property_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **enabled** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_enabled**\ (\ ) + +Controls whether the camera can be active or not. If ``true``, the **Camera2D** will become the main camera when it enters the scene tree and there is no active camera currently (see :ref:`Viewport.get_camera_2d()`). + +When the camera is currently active and :ref:`enabled` is set to ``false``, the next enabled **Camera2D** in the scene tree will become active. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera2D_property_ignore_rotation: + +.. rst-class:: classref-property + +:ref:`bool` **ignore_rotation** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_ignore_rotation**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_ignoring_rotation**\ (\ ) + +If ``true``, the camera's rendered view is not affected by its :ref:`Node2D.rotation` and :ref:`Node2D.global_rotation`. + +.. rst-class:: classref-item-separator + ---- .. _class_Camera2D_property_limit_bottom: -- :ref:`int` **limit_bottom** +.. rst-class:: classref-property + +:ref:`int` **limit_bottom** = ``10000000`` :ref:`🔗` -+-----------+------------------+ -| *Default* | ``10000000`` | -+-----------+------------------+ -| *Setter* | set_limit(value) | -+-----------+------------------+ -| *Getter* | get_limit() | -+-----------+------------------+ +.. rst-class:: classref-property-setget -Bottom scroll limit in pixels. The camera stops moving when reaching this value. +- |void| **set_limit**\ (\ margin\: :ref:`Side`, limit\: :ref:`int`\ ) +- :ref:`int` **get_limit**\ (\ margin\: :ref:`Side`\ ) |const| + +Bottom scroll limit in pixels. The camera stops moving when reaching this value, but :ref:`offset` can push the view past the limit. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera2D_property_limit_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **limit_enabled** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_limit_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_limit_enabled**\ (\ ) + +If ``true``, the limits will be enabled. Disabling this will allow the camera to focus anywhere, when the four ``limit_*`` properties will not work. + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_property_limit_left: -- :ref:`int` **limit_left** +.. rst-class:: classref-property + +:ref:`int` **limit_left** = ``-10000000`` :ref:`🔗` -+-----------+------------------+ -| *Default* | ``-10000000`` | -+-----------+------------------+ -| *Setter* | set_limit(value) | -+-----------+------------------+ -| *Getter* | get_limit() | -+-----------+------------------+ +.. rst-class:: classref-property-setget -Left scroll limit in pixels. The camera stops moving when reaching this value. +- |void| **set_limit**\ (\ margin\: :ref:`Side`, limit\: :ref:`int`\ ) +- :ref:`int` **get_limit**\ (\ margin\: :ref:`Side`\ ) |const| + +Left scroll limit in pixels. The camera stops moving when reaching this value, but :ref:`offset` can push the view past the limit. + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_property_limit_right: -- :ref:`int` **limit_right** +.. rst-class:: classref-property + +:ref:`int` **limit_right** = ``10000000`` :ref:`🔗` -+-----------+------------------+ -| *Default* | ``10000000`` | -+-----------+------------------+ -| *Setter* | set_limit(value) | -+-----------+------------------+ -| *Getter* | get_limit() | -+-----------+------------------+ +.. rst-class:: classref-property-setget -Right scroll limit in pixels. The camera stops moving when reaching this value. +- |void| **set_limit**\ (\ margin\: :ref:`Side`, limit\: :ref:`int`\ ) +- :ref:`int` **get_limit**\ (\ margin\: :ref:`Side`\ ) |const| + +Right scroll limit in pixels. The camera stops moving when reaching this value, but :ref:`offset` can push the view past the limit. + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_property_limit_smoothed: -- :ref:`bool` **limit_smoothed** +.. rst-class:: classref-property + +:ref:`bool` **limit_smoothed** = ``false`` :ref:`🔗` -+-----------+------------------------------------+ -| *Default* | ``false`` | -+-----------+------------------------------------+ -| *Setter* | set_limit_smoothing_enabled(value) | -+-----------+------------------------------------+ -| *Getter* | is_limit_smoothing_enabled() | -+-----------+------------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_limit_smoothing_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_limit_smoothing_enabled**\ (\ ) If ``true``, the camera smoothly stops when reaches its limits. +This property has no effect if :ref:`position_smoothing_enabled` is ``false``. + +\ **Note:** To immediately update the camera's position to be within limits without smoothing, even with this setting enabled, invoke :ref:`reset_smoothing()`. + +.. rst-class:: classref-item-separator + ---- .. _class_Camera2D_property_limit_top: -- :ref:`int` **limit_top** +.. rst-class:: classref-property + +:ref:`int` **limit_top** = ``-10000000`` :ref:`🔗` -+-----------+------------------+ -| *Default* | ``-10000000`` | -+-----------+------------------+ -| *Setter* | set_limit(value) | -+-----------+------------------+ -| *Getter* | get_limit() | -+-----------+------------------+ +.. rst-class:: classref-property-setget -Top scroll limit in pixels. The camera stops moving when reaching this value. +- |void| **set_limit**\ (\ margin\: :ref:`Side`, limit\: :ref:`int`\ ) +- :ref:`int` **get_limit**\ (\ margin\: :ref:`Side`\ ) |const| + +Top scroll limit in pixels. The camera stops moving when reaching this value, but :ref:`offset` can push the view past the limit. + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_property_offset: -- :ref:`Vector2` **offset** +.. rst-class:: classref-property + +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` -+-----------+---------------------+ -| *Default* | ``Vector2( 0, 0 )`` | -+-----------+---------------------+ -| *Setter* | set_offset(value) | -+-----------+---------------------+ -| *Getter* | get_offset() | -+-----------+---------------------+ +.. rst-class:: classref-property-setget -The camera's offset, useful for looking around or camera shake animations. +- |void| **set_offset**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_offset**\ (\ ) + +The camera's relative offset. Useful for looking around or camera shake animations. The offsetted camera can go past the limits defined in :ref:`limit_top`, :ref:`limit_bottom`, :ref:`limit_left` and :ref:`limit_right`. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_offset_h: +.. _class_Camera2D_property_position_smoothing_enabled: + +.. rst-class:: classref-property -- :ref:`float` **offset_h** +:ref:`bool` **position_smoothing_enabled** = ``false`` :ref:`🔗` -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_h_offset(value) | -+-----------+---------------------+ -| *Getter* | get_h_offset() | -+-----------+---------------------+ +.. rst-class:: classref-property-setget -The horizontal offset of the camera, relative to the drag margins. +- |void| **set_position_smoothing_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_position_smoothing_enabled**\ (\ ) -**Note:** Offset H is used only to force offset relative to margins. It's not updated in any way if drag margins are enabled and can be used to set initial offset. +If ``true``, the camera's view smoothly moves towards its target position at :ref:`position_smoothing_speed`. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_offset_v: +.. _class_Camera2D_property_position_smoothing_speed: -- :ref:`float` **offset_v** +.. rst-class:: classref-property -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_v_offset(value) | -+-----------+---------------------+ -| *Getter* | get_v_offset() | -+-----------+---------------------+ +:ref:`float` **position_smoothing_speed** = ``5.0`` :ref:`🔗` -The vertical offset of the camera, relative to the drag margins. +.. rst-class:: classref-property-setget -**Note:** Used the same as :ref:`offset_h`. +- |void| **set_position_smoothing_speed**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_position_smoothing_speed**\ (\ ) ----- +Speed in pixels per second of the camera's smoothing effect when :ref:`position_smoothing_enabled` is ``true``. -.. _class_Camera2D_property_process_mode: +.. rst-class:: classref-item-separator -- :ref:`Camera2DProcessMode` **process_mode** +---- -+-----------+-------------------------+ -| *Default* | ``1`` | -+-----------+-------------------------+ -| *Setter* | set_process_mode(value) | -+-----------+-------------------------+ -| *Getter* | get_process_mode() | -+-----------+-------------------------+ +.. _class_Camera2D_property_process_callback: -The camera's process callback. See :ref:`Camera2DProcessMode`. +.. rst-class:: classref-property ----- +:ref:`Camera2DProcessCallback` **process_callback** = ``1`` :ref:`🔗` -.. _class_Camera2D_property_rotating: +.. rst-class:: classref-property-setget -- :ref:`bool` **rotating** +- |void| **set_process_callback**\ (\ value\: :ref:`Camera2DProcessCallback`\ ) +- :ref:`Camera2DProcessCallback` **get_process_callback**\ (\ ) -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_rotating(value) | -+-----------+---------------------+ -| *Getter* | is_rotating() | -+-----------+---------------------+ +The camera's process callback. -If ``true``, the camera rotates with the target. +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_smoothing_enabled: +.. _class_Camera2D_property_rotation_smoothing_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **rotation_smoothing_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_rotation_smoothing_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_rotation_smoothing_enabled**\ (\ ) -- :ref:`bool` **smoothing_enabled** +If ``true``, the camera's view smoothly rotates, via asymptotic smoothing, to align with its target rotation at :ref:`rotation_smoothing_speed`. -+-----------+------------------------------------+ -| *Default* | ``false`` | -+-----------+------------------------------------+ -| *Setter* | set_enable_follow_smoothing(value) | -+-----------+------------------------------------+ -| *Getter* | is_follow_smoothing_enabled() | -+-----------+------------------------------------+ +\ **Note:** This property has no effect if :ref:`ignore_rotation` is ``true``. -If ``true``, the camera smoothly moves towards the target at :ref:`smoothing_speed`. +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_property_smoothing_speed: +.. _class_Camera2D_property_rotation_smoothing_speed: -- :ref:`float` **smoothing_speed** +.. rst-class:: classref-property -+-----------+-----------------------------+ -| *Default* | ``5.0`` | -+-----------+-----------------------------+ -| *Setter* | set_follow_smoothing(value) | -+-----------+-----------------------------+ -| *Getter* | get_follow_smoothing() | -+-----------+-----------------------------+ +:ref:`float` **rotation_smoothing_speed** = ``5.0`` :ref:`🔗` -Speed in pixels per second of the camera's smoothing effect when :ref:`smoothing_enabled` is ``true``. +.. rst-class:: classref-property-setget + +- |void| **set_rotation_smoothing_speed**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_rotation_smoothing_speed**\ (\ ) + +The angular, asymptotic speed of the camera's rotation smoothing effect when :ref:`rotation_smoothing_enabled` is ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_property_zoom: -- :ref:`Vector2` **zoom** +.. rst-class:: classref-property + +:ref:`Vector2` **zoom** = ``Vector2(1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``Vector2( 1, 1 )`` | -+-----------+---------------------+ -| *Setter* | set_zoom(value) | -+-----------+---------------------+ -| *Getter* | get_zoom() | -+-----------+---------------------+ +- |void| **set_zoom**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_zoom**\ (\ ) -The camera's zoom relative to the viewport. Values larger than ``Vector2(1, 1)`` zoom out and smaller values zoom in. For an example, use ``Vector2(0.5, 0.5)`` for a 2× zoom-in, and ``Vector2(4, 4)`` for a 4× zoom-out. +The camera's zoom. Higher values are more zoomed in. For example, a zoom of ``Vector2(2.0, 2.0)`` will be twice as zoomed in on each axis (the view covers an area four times smaller). In contrast, a zoom of ``Vector2(0.5, 0.5)`` will be twice as zoomed out on each axis (the view covers an area four times larger). The X and Y components should generally always be set to the same value, unless you wish to stretch the camera view. + +\ **Note:** :ref:`FontFile.oversampling` does *not* take **Camera2D** zoom into account. This means that zooming in/out will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated unless the font is part of a :ref:`CanvasLayer` that makes it ignore camera zoom. To ensure text remains crisp regardless of zoom, you can enable MSDF font rendering by enabling :ref:`ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field` (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, :ref:`SystemFont.multichannel_signed_distance_field` can be enabled in the inspector. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_Camera2D_method_align: -- void **align** **(** **)** +.. rst-class:: classref-method + +|void| **align**\ (\ ) :ref:`🔗` Aligns the camera to the tracked node. +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera2D_method_force_update_scroll: + +.. rst-class:: classref-method + +|void| **force_update_scroll**\ (\ ) :ref:`🔗` + +Forces the camera to update scroll immediately. + +.. rst-class:: classref-item-separator + ---- -.. _class_Camera2D_method_clear_current: +.. _class_Camera2D_method_get_drag_margin: -- void **clear_current** **(** **)** +.. rst-class:: classref-method -Removes any ``Camera2D`` from the ancestor :ref:`Viewport`'s internal currently-assigned camera. +:ref:`float` **get_drag_margin**\ (\ margin\: :ref:`Side`\ ) |const| :ref:`🔗` + +Returns the specified :ref:`Side`'s margin. See also :ref:`drag_bottom_margin`, :ref:`drag_top_margin`, :ref:`drag_left_margin`, and :ref:`drag_right_margin`. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_method_force_update_scroll: +.. _class_Camera2D_method_get_limit: -- void **force_update_scroll** **(** **)** +.. rst-class:: classref-method -Forces the camera to update scroll immediately. +:ref:`int` **get_limit**\ (\ margin\: :ref:`Side`\ ) |const| :ref:`🔗` + +Returns the camera limit for the specified :ref:`Side`. See also :ref:`limit_bottom`, :ref:`limit_top`, :ref:`limit_left`, and :ref:`limit_right`. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_method_get_camera_position: +.. _class_Camera2D_method_get_screen_center_position: + +.. rst-class:: classref-method -- :ref:`Vector2` **get_camera_position** **(** **)** const +:ref:`Vector2` **get_screen_center_position**\ (\ ) |const| :ref:`🔗` -Returns the camera position. +Returns the center of the screen from this camera's point of view, in global coordinates. + +\ **Note:** The exact targeted position of the camera may be different. See :ref:`get_target_position()`. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_method_get_camera_screen_center: +.. _class_Camera2D_method_get_screen_rotation: + +.. rst-class:: classref-method -- :ref:`Vector2` **get_camera_screen_center** **(** **)** const +:ref:`float` **get_screen_rotation**\ (\ ) |const| :ref:`🔗` -Returns the location of the ``Camera2D``'s screen-center, relative to the origin. +Returns the current screen rotation from this camera's point of view. + +\ **Note:** The screen rotation can be different from :ref:`Node2D.global_rotation` if the camera is rotating smoothly due to :ref:`rotation_smoothing_enabled`. + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_method_get_drag_margin: +.. _class_Camera2D_method_get_target_position: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_target_position**\ (\ ) |const| :ref:`🔗` -- :ref:`float` **get_drag_margin** **(** :ref:`Margin` margin **)** const +Returns this camera's target position, in global coordinates. -Returns the specified margin. See also :ref:`drag_margin_bottom`, :ref:`drag_margin_top`, :ref:`drag_margin_left`, and :ref:`drag_margin_right`. +\ **Note:** The returned value is not the same as :ref:`Node2D.global_position`, as it is affected by the drag properties. It is also not the same as the current position if :ref:`position_smoothing_enabled` is ``true`` (see :ref:`get_screen_center_position()`). + +.. rst-class:: classref-item-separator ---- -.. _class_Camera2D_method_get_limit: +.. _class_Camera2D_method_is_current: + +.. rst-class:: classref-method -- :ref:`int` **get_limit** **(** :ref:`Margin` margin **)** const +:ref:`bool` **is_current**\ (\ ) |const| :ref:`🔗` -Returns the specified camera limit. See also :ref:`limit_bottom`, :ref:`limit_top`, :ref:`limit_left`, and :ref:`limit_right`. +Returns ``true`` if this **Camera2D** is the active camera (see :ref:`Viewport.get_camera_2d()`). + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_method_make_current: -- void **make_current** **(** **)** +.. rst-class:: classref-method + +|void| **make_current**\ (\ ) :ref:`🔗` + +Forces this **Camera2D** to become the current active one. :ref:`enabled` must be ``true``. -Make this the current 2D camera for the scene (viewport and layer), in case there are many cameras in the scene. +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_method_reset_smoothing: -- void **reset_smoothing** **(** **)** +.. rst-class:: classref-method + +|void| **reset_smoothing**\ (\ ) :ref:`🔗` Sets the camera's position immediately to its current smoothing destination. -This has no effect if smoothing is disabled. +This method has no effect if :ref:`position_smoothing_enabled` is ``false``. + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_method_set_drag_margin: -- void **set_drag_margin** **(** :ref:`Margin` margin, :ref:`float` drag_margin **)** +.. rst-class:: classref-method + +|void| **set_drag_margin**\ (\ margin\: :ref:`Side`, drag_margin\: :ref:`float`\ ) :ref:`🔗` -Sets the specified margin. See also :ref:`drag_margin_bottom`, :ref:`drag_margin_top`, :ref:`drag_margin_left`, and :ref:`drag_margin_right`. +Sets the specified :ref:`Side`'s margin. See also :ref:`drag_bottom_margin`, :ref:`drag_top_margin`, :ref:`drag_left_margin`, and :ref:`drag_right_margin`. + +.. rst-class:: classref-item-separator ---- .. _class_Camera2D_method_set_limit: -- void **set_limit** **(** :ref:`Margin` margin, :ref:`int` limit **)** +.. rst-class:: classref-method + +|void| **set_limit**\ (\ margin\: :ref:`Side`, limit\: :ref:`int`\ ) :ref:`🔗` -Sets the specified camera limit. See also :ref:`limit_bottom`, :ref:`limit_top`, :ref:`limit_left`, and :ref:`limit_right`. +Sets the camera limit for the specified :ref:`Side`. See also :ref:`limit_bottom`, :ref:`limit_top`, :ref:`limit_left`, and :ref:`limit_right`. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_camera3d.rst b/classes/class_camera3d.rst new file mode 100644 index 00000000000..a29482fd75b --- /dev/null +++ b/classes/class_camera3d.rst @@ -0,0 +1,756 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Camera3D.xml. + +.. _class_Camera3D: + +Camera3D +======== + +**Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +**Inherited By:** :ref:`XRCamera3D` + +Camera node, displays from a point of view. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**Camera3D** is a special node that displays what is visible from its current location. Cameras register themselves in the nearest :ref:`Viewport` node (when ascending the tree). Only one camera can be active per viewport. If no viewport is available ascending the tree, the camera will register in the global viewport. In other words, a camera just provides 3D display capabilities to a :ref:`Viewport`, and, without one, a scene registered in that :ref:`Viewport` (or higher viewports) can't be displayed. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`CameraAttributes` | :ref:`attributes` | | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`Compositor` | :ref:`compositor` | | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`int` | :ref:`cull_mask` | ``1048575`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`current` | ``false`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`DopplerTracking` | :ref:`doppler_tracking` | ``0`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`Environment` | :ref:`environment` | | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`far` | ``4000.0`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`fov` | ``75.0`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`Vector2` | :ref:`frustum_offset` | ``Vector2(0, 0)`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`h_offset` | ``0.0`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`KeepAspect` | :ref:`keep_aspect` | ``1`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`near` | ``0.05`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`ProjectionType` | :ref:`projection` | ``0`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`size` | ``1.0`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + | :ref:`float` | :ref:`v_offset` | ``0.0`` | + +-------------------------------------------------------+-------------------------------------------------------------------+-------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_current`\ (\ enable_next\: :ref:`bool` = true\ ) | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Projection` | :ref:`get_camera_projection`\ (\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_camera_rid`\ (\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform3D` | :ref:`get_camera_transform`\ (\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_cull_mask_value`\ (\ layer_number\: :ref:`int`\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Plane`\] | :ref:`get_frustum`\ (\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_pyramid_shape_rid`\ (\ ) | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_position_behind`\ (\ world_point\: :ref:`Vector3`\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_position_in_frustum`\ (\ world_point\: :ref:`Vector3`\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`make_current`\ (\ ) | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`project_local_ray_normal`\ (\ screen_point\: :ref:`Vector2`\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`project_position`\ (\ screen_point\: :ref:`Vector2`, z_depth\: :ref:`float`\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`project_ray_normal`\ (\ screen_point\: :ref:`Vector2`\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`project_ray_origin`\ (\ screen_point\: :ref:`Vector2`\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_cull_mask_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_frustum`\ (\ size\: :ref:`float`, offset\: :ref:`Vector2`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_orthogonal`\ (\ size\: :ref:`float`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_perspective`\ (\ fov\: :ref:`float`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`unproject_position`\ (\ world_point\: :ref:`Vector3`\ ) |const| | + +--------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_Camera3D_ProjectionType: + +.. rst-class:: classref-enumeration + +enum **ProjectionType**: :ref:`🔗` + +.. _class_Camera3D_constant_PROJECTION_PERSPECTIVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`ProjectionType` **PROJECTION_PERSPECTIVE** = ``0`` + +Perspective projection. Objects on the screen becomes smaller when they are far away. + +.. _class_Camera3D_constant_PROJECTION_ORTHOGONAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`ProjectionType` **PROJECTION_ORTHOGONAL** = ``1`` + +Orthogonal projection, also known as orthographic projection. Objects remain the same size on the screen no matter how far away they are. + +.. _class_Camera3D_constant_PROJECTION_FRUSTUM: + +.. rst-class:: classref-enumeration-constant + +:ref:`ProjectionType` **PROJECTION_FRUSTUM** = ``2`` + +Frustum projection. This mode allows adjusting :ref:`frustum_offset` to create "tilted frustum" effects. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Camera3D_KeepAspect: + +.. rst-class:: classref-enumeration + +enum **KeepAspect**: :ref:`🔗` + +.. _class_Camera3D_constant_KEEP_WIDTH: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeepAspect` **KEEP_WIDTH** = ``0`` + +Preserves the horizontal aspect ratio; also known as Vert- scaling. This is usually the best option for projects running in portrait mode, as taller aspect ratios will benefit from a wider vertical FOV. + +.. _class_Camera3D_constant_KEEP_HEIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`KeepAspect` **KEEP_HEIGHT** = ``1`` + +Preserves the vertical aspect ratio; also known as Hor+ scaling. This is usually the best option for projects running in landscape mode, as wider aspect ratios will automatically benefit from a wider horizontal FOV. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Camera3D_DopplerTracking: + +.. rst-class:: classref-enumeration + +enum **DopplerTracking**: :ref:`🔗` + +.. _class_Camera3D_constant_DOPPLER_TRACKING_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_DISABLED** = ``0`` + +Disables `Doppler effect `__ simulation (default). + +.. _class_Camera3D_constant_DOPPLER_TRACKING_IDLE_STEP: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_IDLE_STEP** = ``1`` + +Simulate `Doppler effect `__ by tracking positions of objects that are changed in ``_process``. Changes in the relative velocity of this camera compared to those objects affect how audio is perceived (changing the audio's :ref:`AudioStreamPlayer3D.pitch_scale`). + +.. _class_Camera3D_constant_DOPPLER_TRACKING_PHYSICS_STEP: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_PHYSICS_STEP** = ``2`` + +Simulate `Doppler effect `__ by tracking positions of objects that are changed in ``_physics_process``. Changes in the relative velocity of this camera compared to those objects affect how audio is perceived (changing the audio's :ref:`AudioStreamPlayer3D.pitch_scale`). + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_Camera3D_property_attributes: + +.. rst-class:: classref-property + +:ref:`CameraAttributes` **attributes** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_attributes**\ (\ value\: :ref:`CameraAttributes`\ ) +- :ref:`CameraAttributes` **get_attributes**\ (\ ) + +The :ref:`CameraAttributes` to use for this camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_compositor: + +.. rst-class:: classref-property + +:ref:`Compositor` **compositor** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_compositor**\ (\ value\: :ref:`Compositor`\ ) +- :ref:`Compositor` **get_compositor**\ (\ ) + +The :ref:`Compositor` to use for this camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_cull_mask: + +.. rst-class:: classref-property + +:ref:`int` **cull_mask** = ``1048575`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_cull_mask**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_cull_mask**\ (\ ) + +The culling mask that describes which :ref:`VisualInstance3D.layers` are rendered by this camera. By default, all 20 user-visible layers are rendered. + +\ **Note:** Since the :ref:`cull_mask` allows for 32 layers to be stored in total, there are an additional 12 layers that are only used internally by the engine and aren't exposed in the editor. Setting :ref:`cull_mask` using a script allows you to toggle those reserved layers, which can be useful for editor plugins. + +To adjust :ref:`cull_mask` more easily using a script, use :ref:`get_cull_mask_value()` and :ref:`set_cull_mask_value()`. + +\ **Note:** :ref:`VoxelGI`, SDFGI and :ref:`LightmapGI` will always take all layers into account to determine what contributes to global illumination. If this is an issue, set :ref:`GeometryInstance3D.gi_mode` to :ref:`GeometryInstance3D.GI_MODE_DISABLED` for meshes and :ref:`Light3D.light_bake_mode` to :ref:`Light3D.BAKE_DISABLED` for lights to exclude them from global illumination. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_current: + +.. rst-class:: classref-property + +:ref:`bool` **current** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_current**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_current**\ (\ ) + +If ``true``, the ancestor :ref:`Viewport` is currently using this camera. + +If multiple cameras are in the scene, one will always be made current. For example, if two **Camera3D** nodes are present in the scene and only one is current, setting one camera's :ref:`current` to ``false`` will cause the other camera to be made current. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_doppler_tracking: + +.. rst-class:: classref-property + +:ref:`DopplerTracking` **doppler_tracking** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_doppler_tracking**\ (\ value\: :ref:`DopplerTracking`\ ) +- :ref:`DopplerTracking` **get_doppler_tracking**\ (\ ) + +If not :ref:`DOPPLER_TRACKING_DISABLED`, this camera will simulate the `Doppler effect `__ for objects changed in particular ``_process`` methods. + +\ **Note:** The Doppler effect will only be heard on :ref:`AudioStreamPlayer3D`\ s if :ref:`AudioStreamPlayer3D.doppler_tracking` is not set to :ref:`AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_environment: + +.. rst-class:: classref-property + +:ref:`Environment` **environment** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_environment**\ (\ value\: :ref:`Environment`\ ) +- :ref:`Environment` **get_environment**\ (\ ) + +The :ref:`Environment` to use for this camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_far: + +.. rst-class:: classref-property + +:ref:`float` **far** = ``4000.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_far**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_far**\ (\ ) + +The distance to the far culling boundary for this camera relative to its local Z axis. Higher values allow the camera to see further away, while decreasing :ref:`far` can improve performance if it results in objects being partially or fully culled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_fov: + +.. rst-class:: classref-property + +:ref:`float` **fov** = ``75.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_fov**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_fov**\ (\ ) + +The camera's field of view angle (in degrees). Only applicable in perspective mode. Since :ref:`keep_aspect` locks one axis, :ref:`fov` sets the other axis' field of view angle. + +For reference, the default vertical field of view value (``75.0``) is equivalent to a horizontal FOV of: + +- ~91.31 degrees in a 4:3 viewport + +- ~101.67 degrees in a 16:10 viewport + +- ~107.51 degrees in a 16:9 viewport + +- ~121.63 degrees in a 21:9 viewport + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_frustum_offset: + +.. rst-class:: classref-property + +:ref:`Vector2` **frustum_offset** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_frustum_offset**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_frustum_offset**\ (\ ) + +The camera's frustum offset. This can be changed from the default to create "tilted frustum" effects such as `Y-shearing `__. + +\ **Note:** Only effective if :ref:`projection` is :ref:`PROJECTION_FRUSTUM`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_h_offset: + +.. rst-class:: classref-property + +:ref:`float` **h_offset** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_h_offset**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_h_offset**\ (\ ) + +The horizontal (X) offset of the camera viewport. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_keep_aspect: + +.. rst-class:: classref-property + +:ref:`KeepAspect` **keep_aspect** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_keep_aspect_mode**\ (\ value\: :ref:`KeepAspect`\ ) +- :ref:`KeepAspect` **get_keep_aspect_mode**\ (\ ) + +The axis to lock during :ref:`fov`/:ref:`size` adjustments. Can be either :ref:`KEEP_WIDTH` or :ref:`KEEP_HEIGHT`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_near: + +.. rst-class:: classref-property + +:ref:`float` **near** = ``0.05`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_near**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_near**\ (\ ) + +The distance to the near culling boundary for this camera relative to its local Z axis. Lower values allow the camera to see objects more up close to its origin, at the cost of lower precision across the *entire* range. Values lower than the default can lead to increased Z-fighting. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_projection: + +.. rst-class:: classref-property + +:ref:`ProjectionType` **projection** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_projection**\ (\ value\: :ref:`ProjectionType`\ ) +- :ref:`ProjectionType` **get_projection**\ (\ ) + +The camera's projection mode. In :ref:`PROJECTION_PERSPECTIVE` mode, objects' Z distance from the camera's local space scales their perceived size. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_size: + +.. rst-class:: classref-property + +:ref:`float` **size** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_size**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_size**\ (\ ) + +The camera's size in meters measured as the diameter of the width or height, depending on :ref:`keep_aspect`. Only applicable in orthogonal and frustum modes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_property_v_offset: + +.. rst-class:: classref-property + +:ref:`float` **v_offset** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_v_offset**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_v_offset**\ (\ ) + +The vertical (Y) offset of the camera viewport. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_Camera3D_method_clear_current: + +.. rst-class:: classref-method + +|void| **clear_current**\ (\ enable_next\: :ref:`bool` = true\ ) :ref:`🔗` + +If this is the current camera, remove it from being current. If ``enable_next`` is ``true``, request to make the next camera current, if any. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_get_camera_projection: + +.. rst-class:: classref-method + +:ref:`Projection` **get_camera_projection**\ (\ ) |const| :ref:`🔗` + +Returns the projection matrix that this camera uses to render to its associated viewport. The camera must be part of the scene tree to function. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_get_camera_rid: + +.. rst-class:: classref-method + +:ref:`RID` **get_camera_rid**\ (\ ) |const| :ref:`🔗` + +Returns the camera's RID from the :ref:`RenderingServer`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_get_camera_transform: + +.. rst-class:: classref-method + +:ref:`Transform3D` **get_camera_transform**\ (\ ) |const| :ref:`🔗` + +Returns the transform of the camera plus the vertical (:ref:`v_offset`) and horizontal (:ref:`h_offset`) offsets; and any other adjustments made to the position and orientation of the camera by subclassed cameras such as :ref:`XRCamera3D`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_get_cull_mask_value: + +.. rst-class:: classref-method + +:ref:`bool` **get_cull_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether or not the specified layer of the :ref:`cull_mask` is enabled, given a ``layer_number`` between 1 and 20. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_get_frustum: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Plane`\] **get_frustum**\ (\ ) |const| :ref:`🔗` + +Returns the camera's frustum planes in world space units as an array of :ref:`Plane`\ s in the following order: near, far, left, top, right, bottom. Not to be confused with :ref:`frustum_offset`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_get_pyramid_shape_rid: + +.. rst-class:: classref-method + +:ref:`RID` **get_pyramid_shape_rid**\ (\ ) :ref:`🔗` + +Returns the RID of a pyramid shape encompassing the camera's view frustum, ignoring the camera's near plane. The tip of the pyramid represents the position of the camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_is_position_behind: + +.. rst-class:: classref-method + +:ref:`bool` **is_position_behind**\ (\ world_point\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given position is behind the camera (the blue part of the linked diagram). `See this diagram `__ for an overview of position query methods. + +\ **Note:** A position which returns ``false`` may still be outside the camera's field of view. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_is_position_in_frustum: + +.. rst-class:: classref-method + +:ref:`bool` **is_position_in_frustum**\ (\ world_point\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given position is inside the camera's frustum (the green part of the linked diagram). `See this diagram `__ for an overview of position query methods. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_make_current: + +.. rst-class:: classref-method + +|void| **make_current**\ (\ ) :ref:`🔗` + +Makes this camera the current camera for the :ref:`Viewport` (see class description). If the camera node is outside the scene tree, it will attempt to become current once it's added. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_project_local_ray_normal: + +.. rst-class:: classref-method + +:ref:`Vector3` **project_local_ray_normal**\ (\ screen_point\: :ref:`Vector2`\ ) |const| :ref:`🔗` + +Returns a normal vector from the screen point location directed along the camera. Orthogonal cameras are normalized. Perspective cameras account for perspective, screen width/height, etc. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_project_position: + +.. rst-class:: classref-method + +:ref:`Vector3` **project_position**\ (\ screen_point\: :ref:`Vector2`, z_depth\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns the 3D point in world space that maps to the given 2D coordinate in the :ref:`Viewport` rectangle on a plane that is the given ``z_depth`` distance into the scene away from the camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_project_ray_normal: + +.. rst-class:: classref-method + +:ref:`Vector3` **project_ray_normal**\ (\ screen_point\: :ref:`Vector2`\ ) |const| :ref:`🔗` + +Returns a normal vector in world space, that is the result of projecting a point on the :ref:`Viewport` rectangle by the inverse camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_project_ray_origin: + +.. rst-class:: classref-method + +:ref:`Vector3` **project_ray_origin**\ (\ screen_point\: :ref:`Vector2`\ ) |const| :ref:`🔗` + +Returns a 3D position in world space, that is the result of projecting a point on the :ref:`Viewport` rectangle by the inverse camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_set_cull_mask_value: + +.. rst-class:: classref-method + +|void| **set_cull_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` + +Based on ``value``, enables or disables the specified layer in the :ref:`cull_mask`, given a ``layer_number`` between 1 and 20. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_set_frustum: + +.. rst-class:: classref-method + +|void| **set_frustum**\ (\ size\: :ref:`float`, offset\: :ref:`Vector2`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) :ref:`🔗` + +Sets the camera projection to frustum mode (see :ref:`PROJECTION_FRUSTUM`), by specifying a ``size``, an ``offset``, and the ``z_near`` and ``z_far`` clip planes in world space units. See also :ref:`frustum_offset`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_set_orthogonal: + +.. rst-class:: classref-method + +|void| **set_orthogonal**\ (\ size\: :ref:`float`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) :ref:`🔗` + +Sets the camera projection to orthogonal mode (see :ref:`PROJECTION_ORTHOGONAL`), by specifying a ``size``, and the ``z_near`` and ``z_far`` clip planes in world space units. + +As a hint, 3D games that look 2D often use this projection, with ``size`` specified in pixels. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_set_perspective: + +.. rst-class:: classref-method + +|void| **set_perspective**\ (\ fov\: :ref:`float`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) :ref:`🔗` + +Sets the camera projection to perspective mode (see :ref:`PROJECTION_PERSPECTIVE`), by specifying a ``fov`` (field of view) angle in degrees, and the ``z_near`` and ``z_far`` clip planes in world space units. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera3D_method_unproject_position: + +.. rst-class:: classref-method + +:ref:`Vector2` **unproject_position**\ (\ world_point\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns the 2D coordinate in the :ref:`Viewport` rectangle that maps to the given 3D point in world space. + +\ **Note:** When using this to position GUI elements over a 3D viewport, use :ref:`is_position_behind()` to prevent them from appearing if the 3D point is behind the camera: + +:: + + # This code block is part of a script that inherits from Node3D. + # `control` is a reference to a node inheriting from Control. + control.visible = not get_viewport().get_camera_3d().is_position_behind(global_transform.origin) + control.position = get_viewport().get_camera_3d().unproject_position(global_transform.origin) + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_cameraattributes.rst b/classes/class_cameraattributes.rst new file mode 100644 index 00000000000..09f3c6dbf60 --- /dev/null +++ b/classes/class_cameraattributes.rst @@ -0,0 +1,154 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CameraAttributes.xml. + +.. _class_CameraAttributes: + +CameraAttributes +================ + +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +**Inherited By:** :ref:`CameraAttributesPhysical`, :ref:`CameraAttributesPractical` + +Parent class for camera settings. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Controls camera-specific attributes such as depth of field and exposure override. + +When used in a :ref:`WorldEnvironment` it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own **CameraAttributes**, including the editor camera. When used in a :ref:`Camera3D` it will override any **CameraAttributes** set in the :ref:`WorldEnvironment`. When used in :ref:`VoxelGI` or :ref:`LightmapGI`, only the exposure settings will be used. + +See also :ref:`Environment` for general 3D environment settings. + +This is a pure virtual class that is inherited by :ref:`CameraAttributesPhysical` and :ref:`CameraAttributesPractical`. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+-------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`auto_exposure_enabled` | ``false`` | + +---------------------------+-------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`auto_exposure_scale` | ``0.4`` | + +---------------------------+-------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`auto_exposure_speed` | ``0.5`` | + +---------------------------+-------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`exposure_multiplier` | ``1.0`` | + +---------------------------+-------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`exposure_sensitivity` | ``100.0`` | + +---------------------------+-------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CameraAttributes_property_auto_exposure_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **auto_exposure_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_exposure_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_auto_exposure_enabled**\ (\ ) + +If ``true``, enables the tonemapping auto exposure mode of the scene renderer. If ``true``, the renderer will automatically determine the exposure setting to adapt to the scene's illumination and the observed light. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributes_property_auto_exposure_scale: + +.. rst-class:: classref-property + +:ref:`float` **auto_exposure_scale** = ``0.4`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_exposure_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_auto_exposure_scale**\ (\ ) + +The scale of the auto exposure effect. Affects the intensity of auto exposure. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributes_property_auto_exposure_speed: + +.. rst-class:: classref-property + +:ref:`float` **auto_exposure_speed** = ``0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_exposure_speed**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_auto_exposure_speed**\ (\ ) + +The speed of the auto exposure effect. Affects the time needed for the camera to perform auto exposure. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributes_property_exposure_multiplier: + +.. rst-class:: classref-property + +:ref:`float` **exposure_multiplier** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_exposure_multiplier**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_exposure_multiplier**\ (\ ) + +Multiplier for the exposure amount. A higher value results in a brighter image. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributes_property_exposure_sensitivity: + +.. rst-class:: classref-property + +:ref:`float` **exposure_sensitivity** = ``100.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_exposure_sensitivity**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_exposure_sensitivity**\ (\ ) + +Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. + +If :ref:`auto_exposure_enabled` is ``true``, this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. + +\ **Note:** Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_cameraattributesphysical.rst b/classes/class_cameraattributesphysical.rst new file mode 100644 index 00000000000..9aee1d44a48 --- /dev/null +++ b/classes/class_cameraattributesphysical.rst @@ -0,0 +1,245 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CameraAttributesPhysical.xml. + +.. _class_CameraAttributesPhysical: + +CameraAttributesPhysical +======================== + +**Inherits:** :ref:`CameraAttributes` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Physically-based camera settings. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**CameraAttributesPhysical** is used to set rendering settings based on a physically-based camera's settings. It is responsible for exposure, auto-exposure, and depth of field. + +When used in a :ref:`WorldEnvironment` it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own :ref:`CameraAttributes`, including the editor camera. When used in a :ref:`Camera3D` it will override any :ref:`CameraAttributes` set in the :ref:`WorldEnvironment` and will override the :ref:`Camera3D`\ s :ref:`Camera3D.far`, :ref:`Camera3D.near`, :ref:`Camera3D.fov`, and :ref:`Camera3D.keep_aspect` properties. When used in :ref:`VoxelGI` or :ref:`LightmapGI`, only the exposure settings will be used. + +The default settings are intended for use in an outdoor environment, tips for settings for use in an indoor environment can be found in each setting's documentation. + +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Physical light and camera units <../tutorials/3d/physical_light_and_camera_units>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`auto_exposure_max_exposure_value` | ``10.0`` | + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`auto_exposure_min_exposure_value` | ``-8.0`` | + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`exposure_aperture` | ``16.0`` | + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`exposure_shutter_speed` | ``100.0`` | + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`frustum_far` | ``4000.0`` | + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`frustum_focal_length` | ``35.0`` | + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`frustum_focus_distance` | ``10.0`` | + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`frustum_near` | ``0.05`` | + +---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_fov`\ (\ ) |const| | + +---------------------------+-----------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CameraAttributesPhysical_property_auto_exposure_max_exposure_value: + +.. rst-class:: classref-property + +:ref:`float` **auto_exposure_max_exposure_value** = ``10.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_exposure_max_exposure_value**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_auto_exposure_max_exposure_value**\ (\ ) + +The maximum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing below a certain brightness, resulting in a cut off point where the scene will remain bright. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPhysical_property_auto_exposure_min_exposure_value: + +.. rst-class:: classref-property + +:ref:`float` **auto_exposure_min_exposure_value** = ``-8.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_exposure_min_exposure_value**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_auto_exposure_min_exposure_value**\ (\ ) + +The minimum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPhysical_property_exposure_aperture: + +.. rst-class:: classref-property + +:ref:`float` **exposure_aperture** = ``16.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_aperture**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_aperture**\ (\ ) + +Size of the aperture of the camera, measured in f-stops. An f-stop is a unitless ratio between the focal length of the camera and the diameter of the aperture. A high aperture setting will result in a smaller aperture which leads to a dimmer image and sharper focus. A low aperture results in a wide aperture which lets in more light resulting in a brighter, less-focused image. Default is appropriate for outdoors at daytime (i.e. for use with a default :ref:`DirectionalLight3D`), for indoor lighting, a value between 2 and 4 is more appropriate. + +Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPhysical_property_exposure_shutter_speed: + +.. rst-class:: classref-property + +:ref:`float` **exposure_shutter_speed** = ``100.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_shutter_speed**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_shutter_speed**\ (\ ) + +Time for shutter to open and close, evaluated as ``1 / shutter_speed`` seconds. A higher value will allow less light (leading to a darker image), while a lower value will allow more light (leading to a brighter image). + +Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPhysical_property_frustum_far: + +.. rst-class:: classref-property + +:ref:`float` **frustum_far** = ``4000.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_far**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_far**\ (\ ) + +Override value for :ref:`Camera3D.far`. Used internally when calculating depth of field. When attached to a :ref:`Camera3D` as its :ref:`Camera3D.attributes`, it will override the :ref:`Camera3D.far` property. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPhysical_property_frustum_focal_length: + +.. rst-class:: classref-property + +:ref:`float` **frustum_focal_length** = ``35.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focal_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_focal_length**\ (\ ) + +Distance between camera lens and camera aperture, measured in millimeters. Controls field of view and depth of field. A larger focal length will result in a smaller field of view and a narrower depth of field meaning fewer objects will be in focus. A smaller focal length will result in a wider field of view and a larger depth of field meaning more objects will be in focus. When attached to a :ref:`Camera3D` as its :ref:`Camera3D.attributes`, it will override the :ref:`Camera3D.fov` property and the :ref:`Camera3D.keep_aspect` property. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPhysical_property_frustum_focus_distance: + +.. rst-class:: classref-property + +:ref:`float` **frustum_focus_distance** = ``10.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_focus_distance**\ (\ ) + +Distance from camera of object that will be in focus, measured in meters. Internally this will be clamped to be at least 1 millimeter larger than :ref:`frustum_focal_length`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPhysical_property_frustum_near: + +.. rst-class:: classref-property + +:ref:`float` **frustum_near** = ``0.05`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_near**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_near**\ (\ ) + +Override value for :ref:`Camera3D.near`. Used internally when calculating depth of field. When attached to a :ref:`Camera3D` as its :ref:`Camera3D.attributes`, it will override the :ref:`Camera3D.near` property. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CameraAttributesPhysical_method_get_fov: + +.. rst-class:: classref-method + +:ref:`float` **get_fov**\ (\ ) |const| :ref:`🔗` + +Returns the vertical field of view that corresponds to the :ref:`frustum_focal_length`. This value is calculated internally whenever :ref:`frustum_focal_length` is changed. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_cameraattributespractical.rst b/classes/class_cameraattributespractical.rst new file mode 100644 index 00000000000..1f9aef6c3cb --- /dev/null +++ b/classes/class_cameraattributespractical.rst @@ -0,0 +1,228 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CameraAttributesPractical.xml. + +.. _class_CameraAttributesPractical: + +CameraAttributesPractical +========================= + +**Inherits:** :ref:`CameraAttributes` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Camera settings in an easy to use format. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Controls camera-specific attributes such as auto-exposure, depth of field, and exposure override. + +When used in a :ref:`WorldEnvironment` it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own :ref:`CameraAttributes`, including the editor camera. When used in a :ref:`Camera3D` it will override any :ref:`CameraAttributes` set in the :ref:`WorldEnvironment`. When used in :ref:`VoxelGI` or :ref:`LightmapGI`, only the exposure settings will be used. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`auto_exposure_max_sensitivity` | ``800.0`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`auto_exposure_min_sensitivity` | ``0.0`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`dof_blur_amount` | ``0.1`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`dof_blur_far_distance` | ``10.0`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`dof_blur_far_enabled` | ``false`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`dof_blur_far_transition` | ``5.0`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`dof_blur_near_distance` | ``2.0`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`dof_blur_near_enabled` | ``false`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`dof_blur_near_transition` | ``1.0`` | + +---------------------------+--------------------------------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CameraAttributesPractical_property_auto_exposure_max_sensitivity: + +.. rst-class:: classref-property + +:ref:`float` **auto_exposure_max_sensitivity** = ``800.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_exposure_max_sensitivity**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_auto_exposure_max_sensitivity**\ (\ ) + +The maximum sensitivity (in ISO) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing below a certain brightness, resulting in a cut off point where the scene will remain bright. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPractical_property_auto_exposure_min_sensitivity: + +.. rst-class:: classref-property + +:ref:`float` **auto_exposure_min_sensitivity** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_exposure_min_sensitivity**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_auto_exposure_min_sensitivity**\ (\ ) + +The minimum sensitivity (in ISO) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPractical_property_dof_blur_amount: + +.. rst-class:: classref-property + +:ref:`float` **dof_blur_amount** = ``0.1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dof_blur_amount**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_dof_blur_amount**\ (\ ) + +Sets the maximum amount of blur. When using physically-based blur amounts, will instead act as a multiplier. High values lead to an increased amount of blurriness, but can be much more expensive to calculate. It is best to keep this as low as possible for a given art style. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPractical_property_dof_blur_far_distance: + +.. rst-class:: classref-property + +:ref:`float` **dof_blur_far_distance** = ``10.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dof_blur_far_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_dof_blur_far_distance**\ (\ ) + +Objects further from the :ref:`Camera3D` by this amount will be blurred by the depth of field effect. Measured in meters. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPractical_property_dof_blur_far_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **dof_blur_far_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dof_blur_far_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_dof_blur_far_enabled**\ (\ ) + +Enables depth of field blur for objects further than :ref:`dof_blur_far_distance`. Strength of blur is controlled by :ref:`dof_blur_amount` and modulated by :ref:`dof_blur_far_transition`. + +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + +\ **Note:** Depth of field blur is not supported on viewports that have a transparent background (where :ref:`Viewport.transparent_bg` is ``true``). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPractical_property_dof_blur_far_transition: + +.. rst-class:: classref-property + +:ref:`float` **dof_blur_far_transition** = ``5.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dof_blur_far_transition**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_dof_blur_far_transition**\ (\ ) + +When positive, distance over which (starting from :ref:`dof_blur_far_distance`) blur effect will scale from 0 to :ref:`dof_blur_amount`. When negative, uses physically-based scaling so depth of field effect will scale from 0 at :ref:`dof_blur_far_distance` and will increase in a physically accurate way as objects get further from the :ref:`Camera3D`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPractical_property_dof_blur_near_distance: + +.. rst-class:: classref-property + +:ref:`float` **dof_blur_near_distance** = ``2.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dof_blur_near_distance**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_dof_blur_near_distance**\ (\ ) + +Objects closer from the :ref:`Camera3D` by this amount will be blurred by the depth of field effect. Measured in meters. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPractical_property_dof_blur_near_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **dof_blur_near_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dof_blur_near_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_dof_blur_near_enabled**\ (\ ) + +Enables depth of field blur for objects closer than :ref:`dof_blur_near_distance`. Strength of blur is controlled by :ref:`dof_blur_amount` and modulated by :ref:`dof_blur_near_transition`. + +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + +\ **Note:** Depth of field blur is not supported on viewports that have a transparent background (where :ref:`Viewport.transparent_bg` is ``true``). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraAttributesPractical_property_dof_blur_near_transition: + +.. rst-class:: classref-property + +:ref:`float` **dof_blur_near_transition** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_dof_blur_near_transition**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_dof_blur_near_transition**\ (\ ) + +When positive, distance over which blur effect will scale from 0 to :ref:`dof_blur_amount`, ending at :ref:`dof_blur_near_distance`. When negative, uses physically-based scaling so depth of field effect will scale from 0 at :ref:`dof_blur_near_distance` and will increase in a physically accurate way as objects get closer to the :ref:`Camera3D`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_cameraeffects.rst b/classes/class_cameraeffects.rst deleted file mode 100644 index 37b3e96be89..00000000000 --- a/classes/class_cameraeffects.rst +++ /dev/null @@ -1,165 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CameraEffects.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_CameraEffects: - -CameraEffects -============= - -**Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` - - - -Properties ----------- - -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`dof_blur_amount` | ``0.1`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`dof_blur_far_distance` | ``10.0`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`dof_blur_far_enabled` | ``false`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`dof_blur_far_transition` | ``5.0`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`dof_blur_near_distance` | ``2.0`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`dof_blur_near_enabled` | ``false`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`dof_blur_near_transition` | ``1.0`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`override_exposure` | ``1.0`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`override_exposure_enable` | ``false`` | -+---------------------------+----------------------------------------------------------------------------------------+-----------+ - -Property Descriptions ---------------------- - -.. _class_CameraEffects_property_dof_blur_amount: - -- :ref:`float` **dof_blur_amount** - -+-----------+----------------------------+ -| *Default* | ``0.1`` | -+-----------+----------------------------+ -| *Setter* | set_dof_blur_amount(value) | -+-----------+----------------------------+ -| *Getter* | get_dof_blur_amount() | -+-----------+----------------------------+ - ----- - -.. _class_CameraEffects_property_dof_blur_far_distance: - -- :ref:`float` **dof_blur_far_distance** - -+-----------+----------------------------------+ -| *Default* | ``10.0`` | -+-----------+----------------------------------+ -| *Setter* | set_dof_blur_far_distance(value) | -+-----------+----------------------------------+ -| *Getter* | get_dof_blur_far_distance() | -+-----------+----------------------------------+ - ----- - -.. _class_CameraEffects_property_dof_blur_far_enabled: - -- :ref:`bool` **dof_blur_far_enabled** - -+-----------+---------------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------------+ -| *Setter* | set_dof_blur_far_enabled(value) | -+-----------+---------------------------------+ -| *Getter* | is_dof_blur_far_enabled() | -+-----------+---------------------------------+ - ----- - -.. _class_CameraEffects_property_dof_blur_far_transition: - -- :ref:`float` **dof_blur_far_transition** - -+-----------+------------------------------------+ -| *Default* | ``5.0`` | -+-----------+------------------------------------+ -| *Setter* | set_dof_blur_far_transition(value) | -+-----------+------------------------------------+ -| *Getter* | get_dof_blur_far_transition() | -+-----------+------------------------------------+ - ----- - -.. _class_CameraEffects_property_dof_blur_near_distance: - -- :ref:`float` **dof_blur_near_distance** - -+-----------+-----------------------------------+ -| *Default* | ``2.0`` | -+-----------+-----------------------------------+ -| *Setter* | set_dof_blur_near_distance(value) | -+-----------+-----------------------------------+ -| *Getter* | get_dof_blur_near_distance() | -+-----------+-----------------------------------+ - ----- - -.. _class_CameraEffects_property_dof_blur_near_enabled: - -- :ref:`bool` **dof_blur_near_enabled** - -+-----------+----------------------------------+ -| *Default* | ``false`` | -+-----------+----------------------------------+ -| *Setter* | set_dof_blur_near_enabled(value) | -+-----------+----------------------------------+ -| *Getter* | is_dof_blur_near_enabled() | -+-----------+----------------------------------+ - ----- - -.. _class_CameraEffects_property_dof_blur_near_transition: - -- :ref:`float` **dof_blur_near_transition** - -+-----------+-------------------------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------------------------+ -| *Setter* | set_dof_blur_near_transition(value) | -+-----------+-------------------------------------+ -| *Getter* | get_dof_blur_near_transition() | -+-----------+-------------------------------------+ - ----- - -.. _class_CameraEffects_property_override_exposure: - -- :ref:`float` **override_exposure** - -+-----------+------------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------------+ -| *Setter* | set_override_exposure(value) | -+-----------+------------------------------+ -| *Getter* | get_override_exposure() | -+-----------+------------------------------+ - ----- - -.. _class_CameraEffects_property_override_exposure_enable: - -- :ref:`bool` **override_exposure_enable** - -+-----------+--------------------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------------------+ -| *Setter* | set_override_exposure_enabled(value) | -+-----------+--------------------------------------+ -| *Getter* | is_override_exposure_enabled() | -+-----------+--------------------------------------+ - diff --git a/classes/class_camerafeed.rst b/classes/class_camerafeed.rst index f58fd081c27..29697e12121 100644 --- a/classes/class_camerafeed.rst +++ b/classes/class_camerafeed.rst @@ -1,22 +1,442 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CameraFeed.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CameraFeed.xml. .. _class_CameraFeed: CameraFeed ========== -**Inherits:** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` A camera feed gives you access to a single physical camera attached to your device. +.. rst-class:: classref-introduction-group + Description ----------- -A camera feed gives you access to a single physical camera attached to your device. When enabled, Godot will start capturing frames from the camera which can then be used. +A camera feed gives you access to a single physical camera attached to your device. When enabled, Godot will start capturing frames from the camera which can then be used. See also :ref:`CameraServer`. + +\ **Note:** Many cameras will return YCbCr images which are split into two textures and need to be combined in a shader. Godot does this automatically for you if you set the environment to show the camera image in the background. + +\ **Note:** This class is currently only implemented on Linux, Android, macOS, and iOS. On other platforms no **CameraFeed**\ s will be available. To get a **CameraFeed** on iOS, the camera plugin from `godot-ios-plugins `__ is required. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ + | :ref:`bool` | :ref:`feed_is_active` | ``false`` | + +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ + | :ref:`Transform2D` | :ref:`feed_transform` | ``Transform2D(1, 0, 0, -1, 0, 1)`` | + +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ + | :ref:`Array` | :ref:`formats` | ``[]`` | + +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_activate_feed`\ (\ ) |virtual| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_deactivate_feed`\ (\ ) |virtual| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FeedDataType` | :ref:`get_datatype`\ (\ ) |const| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_id`\ (\ ) |const| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_name`\ (\ ) |const| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FeedPosition` | :ref:`get_position`\ (\ ) |const| | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_texture_tex_id`\ (\ feed_image_type\: :ref:`FeedImage`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_external`\ (\ width\: :ref:`int`, height\: :ref:`int`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`set_format`\ (\ index\: :ref:`int`, parameters\: :ref:`Dictionary`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_name`\ (\ name\: :ref:`String`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_position`\ (\ position\: :ref:`FeedPosition`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_rgb_image`\ (\ rgb_image\: :ref:`Image`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_ycbcr_image`\ (\ ycbcr_image\: :ref:`Image`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_ycbcr_images`\ (\ y_image\: :ref:`Image`, cbcr_image\: :ref:`Image`\ ) | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_CameraFeed_signal_format_changed: + +.. rst-class:: classref-signal + +**format_changed**\ (\ ) :ref:`🔗` + +Emitted when the format has changed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_signal_frame_changed: + +.. rst-class:: classref-signal + +**frame_changed**\ (\ ) :ref:`🔗` + +Emitted when a new frame is available. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_CameraFeed_FeedDataType: + +.. rst-class:: classref-enumeration + +enum **FeedDataType**: :ref:`🔗` + +.. _class_CameraFeed_constant_FEED_NOIMAGE: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedDataType` **FEED_NOIMAGE** = ``0`` + +No image set for the feed. + +.. _class_CameraFeed_constant_FEED_RGB: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedDataType` **FEED_RGB** = ``1`` + +Feed supplies RGB images. + +.. _class_CameraFeed_constant_FEED_YCBCR: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedDataType` **FEED_YCBCR** = ``2`` + +Feed supplies YCbCr images that need to be converted to RGB. + +.. _class_CameraFeed_constant_FEED_YCBCR_SEP: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedDataType` **FEED_YCBCR_SEP** = ``3`` + +Feed supplies separate Y and CbCr images that need to be combined and converted to RGB. + +.. _class_CameraFeed_constant_FEED_EXTERNAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedDataType` **FEED_EXTERNAL** = ``4`` + +Feed supplies external image. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_CameraFeed_FeedPosition: + +.. rst-class:: classref-enumeration + +enum **FeedPosition**: :ref:`🔗` + +.. _class_CameraFeed_constant_FEED_UNSPECIFIED: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedPosition` **FEED_UNSPECIFIED** = ``0`` + +Unspecified position. + +.. _class_CameraFeed_constant_FEED_FRONT: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedPosition` **FEED_FRONT** = ``1`` + +Camera is mounted at the front of the device. + +.. _class_CameraFeed_constant_FEED_BACK: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedPosition` **FEED_BACK** = ``2`` + +Camera is mounted at the back of the device. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CameraFeed_property_feed_is_active: + +.. rst-class:: classref-property + +:ref:`bool` **feed_is_active** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_active**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_active**\ (\ ) + +If ``true``, the feed is active. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_property_feed_transform: + +.. rst-class:: classref-property + +:ref:`Transform2D` **feed_transform** = ``Transform2D(1, 0, 0, -1, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_transform**\ (\ value\: :ref:`Transform2D`\ ) +- :ref:`Transform2D` **get_transform**\ (\ ) + +The transform applied to the camera's image. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_property_formats: + +.. rst-class:: classref-property + +:ref:`Array` **formats** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`Array` **get_formats**\ (\ ) + +Formats supported by the feed. Each entry is a :ref:`Dictionary` describing format parameters. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CameraFeed_private_method__activate_feed: + +.. rst-class:: classref-method + +:ref:`bool` **_activate_feed**\ (\ ) |virtual| :ref:`🔗` + +Called when the camera feed is activated. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_private_method__deactivate_feed: + +.. rst-class:: classref-method + +|void| **_deactivate_feed**\ (\ ) |virtual| :ref:`🔗` + +Called when the camera feed is deactivated. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_get_datatype: + +.. rst-class:: classref-method + +:ref:`FeedDataType` **get_datatype**\ (\ ) |const| :ref:`🔗` + +Returns feed image data type. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_get_id: + +.. rst-class:: classref-method + +:ref:`int` **get_id**\ (\ ) |const| :ref:`🔗` + +Returns the unique ID for this feed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_get_name: + +.. rst-class:: classref-method + +:ref:`String` **get_name**\ (\ ) |const| :ref:`🔗` + +Returns the camera's name. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_get_position: + +.. rst-class:: classref-method + +:ref:`FeedPosition` **get_position**\ (\ ) |const| :ref:`🔗` + +Returns the position of camera on the device. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_get_texture_tex_id: + +.. rst-class:: classref-method + +:ref:`int` **get_texture_tex_id**\ (\ feed_image_type\: :ref:`FeedImage`\ ) :ref:`🔗` + +Returns the texture backend ID (usable by some external libraries that need a handle to a texture to write data). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_external: + +.. rst-class:: classref-method + +|void| **set_external**\ (\ width\: :ref:`int`, height\: :ref:`int`\ ) :ref:`🔗` + +Sets the feed as external feed provided by another library. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_format: + +.. rst-class:: classref-method + +:ref:`bool` **set_format**\ (\ index\: :ref:`int`, parameters\: :ref:`Dictionary`\ ) :ref:`🔗` + +Sets the feed format parameters for the given ``index`` in the :ref:`formats` array. Returns ``true`` on success. By default, the YUYV encoded stream is transformed to :ref:`FEED_RGB`. The YUYV encoded stream output format can be changed by setting ``parameters``'s ``output`` entry to one of the following: + +- ``"separate"`` will result in :ref:`FEED_YCBCR_SEP`; + +- ``"grayscale"`` will result in desaturated :ref:`FEED_RGB`; + +- ``"copy"`` will result in :ref:`FEED_YCBCR`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_name: + +.. rst-class:: classref-method + +|void| **set_name**\ (\ name\: :ref:`String`\ ) :ref:`🔗` + +Sets the camera's name. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_position: + +.. rst-class:: classref-method + +|void| **set_position**\ (\ position\: :ref:`FeedPosition`\ ) :ref:`🔗` + +Sets the position of this camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_rgb_image: + +.. rst-class:: classref-method + +|void| **set_rgb_image**\ (\ rgb_image\: :ref:`Image`\ ) :ref:`🔗` + +Sets RGB image for this feed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_ycbcr_image: + +.. rst-class:: classref-method + +|void| **set_ycbcr_image**\ (\ ycbcr_image\: :ref:`Image`\ ) :ref:`🔗` + +Sets YCbCr image for this feed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_ycbcr_images: + +.. rst-class:: classref-method + +|void| **set_ycbcr_images**\ (\ y_image\: :ref:`Image`, cbcr_image\: :ref:`Image`\ ) :ref:`🔗` -**Note:** Many cameras will return YCbCr images which are split into two textures and need to be combined in a shader. Godot does this automatically for you if you set the environment to show the camera image in the background. +Sets Y and CbCr images for this feed. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_cameraserver.rst b/classes/class_cameraserver.rst index 258655537ca..8172be2d4e7 100644 --- a/classes/class_cameraserver.rst +++ b/classes/class_cameraserver.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CameraServer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CameraServer.xml. .. _class_CameraServer: @@ -13,106 +14,261 @@ CameraServer Server keeping track of different cameras accessible in Godot. +.. rst-class:: classref-introduction-group + Description ----------- -The ``CameraServer`` keeps track of different cameras accessible in Godot. These are external cameras such as webcams or the cameras on your phone. +The **CameraServer** keeps track of different cameras accessible in Godot. These are external cameras such as webcams or the cameras on your phone. It is notably used to provide AR modules with a video feed from the camera. +\ **Note:** This class is currently only implemented on Linux, Android, macOS, and iOS. On other platforms no :ref:`CameraFeed`\ s will be available. To get a :ref:`CameraFeed` on iOS, the camera plugin from `godot-ios-plugins `__ is required. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+-----------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`monitoring_feeds` | ``false`` | + +-------------------------+-----------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group + Methods ------- -+-------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_feed` **(** :ref:`CameraFeed` feed **)** | -+-------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`feeds` **(** **)** | -+-------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| :ref:`CameraFeed` | :ref:`get_feed` **(** :ref:`int` index **)** | -+-------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_feed_count` **(** **)** | -+-------------------------------------+----------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_feed` **(** :ref:`CameraFeed` feed **)** | -+-------------------------------------+----------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_feed`\ (\ feed\: :ref:`CameraFeed`\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`CameraFeed`\] | :ref:`feeds`\ (\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+ + | :ref:`CameraFeed` | :ref:`get_feed`\ (\ index\: :ref:`int`\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_feed_count`\ (\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_feed`\ (\ feed\: :ref:`CameraFeed`\ ) | + +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_CameraServer_signal_camera_feed_added: -- **camera_feed_added** **(** :ref:`int` id **)** +.. rst-class:: classref-signal + +**camera_feed_added**\ (\ id\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`CameraFeed` is added (e.g. a webcam is plugged in). -Emitted when a :ref:`CameraFeed` is added (e.g. webcam is plugged in). +.. rst-class:: classref-item-separator ---- .. _class_CameraServer_signal_camera_feed_removed: -- **camera_feed_removed** **(** :ref:`int` id **)** +.. rst-class:: classref-signal + +**camera_feed_removed**\ (\ id\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a :ref:`CameraFeed` is removed (e.g. a webcam is unplugged). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraServer_signal_camera_feeds_updated: + +.. rst-class:: classref-signal + +**camera_feeds_updated**\ (\ ) :ref:`🔗` + +Emitted when camera feeds are updated. -Emitted when a :ref:`CameraFeed` is removed (e.g. webcam is unplugged). +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_CameraServer_FeedImage: +.. rst-class:: classref-enumeration + +enum **FeedImage**: :ref:`🔗` + .. _class_CameraServer_constant_FEED_RGBA_IMAGE: +.. rst-class:: classref-enumeration-constant + +:ref:`FeedImage` **FEED_RGBA_IMAGE** = ``0`` + +The RGBA camera image. + .. _class_CameraServer_constant_FEED_YCBCR_IMAGE: +.. rst-class:: classref-enumeration-constant + +:ref:`FeedImage` **FEED_YCBCR_IMAGE** = ``0`` + +The `YCbCr `__ camera image. + .. _class_CameraServer_constant_FEED_Y_IMAGE: +.. rst-class:: classref-enumeration-constant + +:ref:`FeedImage` **FEED_Y_IMAGE** = ``0`` + +The Y component camera image. + .. _class_CameraServer_constant_FEED_CBCR_IMAGE: -enum **FeedImage**: +.. rst-class:: classref-enumeration-constant + +:ref:`FeedImage` **FEED_CBCR_IMAGE** = ``1`` + +The CbCr component camera image. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CameraServer_property_monitoring_feeds: + +.. rst-class:: classref-property + +:ref:`bool` **monitoring_feeds** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_monitoring_feeds**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_monitoring_feeds**\ (\ ) + +If ``true``, the server is actively monitoring available camera feeds. + +This has a performance cost, so only set it to ``true`` when you're actively accessing the camera. + +\ **Note:** After setting it to ``true``, you can receive updated camera feeds through the :ref:`camera_feeds_updated` signal. + + +.. tabs:: -- **FEED_RGBA_IMAGE** = **0** --- The RGBA camera image. + .. code-tab:: gdscript -- **FEED_YCBCR_IMAGE** = **0** --- The YCbCr camera image. + func _ready(): + CameraServer.camera_feeds_updated.connect(_on_camera_feeds_updated) + CameraServer.monitoring_feeds = true -- **FEED_Y_IMAGE** = **0** --- The Y component camera image. + func _on_camera_feeds_updated(): + var feeds = CameraServer.feeds() -- **FEED_CBCR_IMAGE** = **1** --- The CbCr component camera image. + .. code-tab:: csharp + + public override void _Ready() + { + CameraServer.CameraFeedsUpdated += OnCameraFeedsUpdated; + CameraServer.MonitoringFeeds = true; + } + + void OnCameraFeedsUpdated() + { + var feeds = CameraServer.Feeds(); + } + + + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_CameraServer_method_add_feed: -- void **add_feed** **(** :ref:`CameraFeed` feed **)** +.. rst-class:: classref-method + +|void| **add_feed**\ (\ feed\: :ref:`CameraFeed`\ ) :ref:`🔗` -Adds a camera feed to the camera server. +Adds the camera ``feed`` to the camera server. + +.. rst-class:: classref-item-separator ---- .. _class_CameraServer_method_feeds: -- :ref:`Array` **feeds** **(** **)** +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`CameraFeed`\] **feeds**\ (\ ) :ref:`🔗` Returns an array of :ref:`CameraFeed`\ s. +.. rst-class:: classref-item-separator + ---- .. _class_CameraServer_method_get_feed: -- :ref:`CameraFeed` **get_feed** **(** :ref:`int` index **)** +.. rst-class:: classref-method + +:ref:`CameraFeed` **get_feed**\ (\ index\: :ref:`int`\ ) :ref:`🔗` -Returns the :ref:`CameraFeed` with this id. +Returns the :ref:`CameraFeed` corresponding to the camera with the given ``index``. + +.. rst-class:: classref-item-separator ---- .. _class_CameraServer_method_get_feed_count: -- :ref:`int` **get_feed_count** **(** **)** +.. rst-class:: classref-method + +:ref:`int` **get_feed_count**\ (\ ) :ref:`🔗` Returns the number of :ref:`CameraFeed`\ s registered. +.. rst-class:: classref-item-separator + ---- .. _class_CameraServer_method_remove_feed: -- void **remove_feed** **(** :ref:`CameraFeed` feed **)** +.. rst-class:: classref-method + +|void| **remove_feed**\ (\ feed\: :ref:`CameraFeed`\ ) :ref:`🔗` -Removes a :ref:`CameraFeed`. +Removes the specified camera ``feed``. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_cameratexture.rst b/classes/class_cameratexture.rst index 830345d138d..74291b04ce8 100644 --- a/classes/class_cameratexture.rst +++ b/classes/class_cameratexture.rst @@ -1,82 +1,108 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CameraTexture.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CameraTexture.xml. .. _class_CameraTexture: CameraTexture ============= -**Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Texture provided by a :ref:`CameraFeed`. +.. rst-class:: classref-introduction-group + Description ----------- This texture gives access to the camera texture provided by a :ref:`CameraFeed`. -**Note:** Many cameras supply YCbCr images which need to be converted in a shader. +\ **Note:** Many cameras supply YCbCr images which need to be converted in a shader. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------+------------------------------------------------------------------------+-----------+ -| :ref:`int` | :ref:`camera_feed_id` | ``0`` | -+-----------------------------------------------+------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`camera_is_active` | ``false`` | -+-----------------------------------------------+------------------------------------------------------------------------+-----------+ -| :ref:`FeedImage` | :ref:`which_feed` | ``0`` | -+-----------------------------------------------+------------------------------------------------------------------------+-----------+ +.. table:: + :widths: auto + + +-----------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`camera_feed_id` | ``0`` | + +-----------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`camera_is_active` | ``false`` | + +-----------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | resource_local_to_scene | ``false`` (overrides :ref:`Resource`) | + +-----------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`FeedImage` | :ref:`which_feed` | ``0`` | + +-----------------------------------------------+------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_CameraTexture_property_camera_feed_id: -- :ref:`int` **camera_feed_id** +.. rst-class:: classref-property + +:ref:`int` **camera_feed_id** = ``0`` :ref:`🔗` -+-----------+---------------------------+ -| *Default* | ``0`` | -+-----------+---------------------------+ -| *Setter* | set_camera_feed_id(value) | -+-----------+---------------------------+ -| *Getter* | get_camera_feed_id() | -+-----------+---------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_camera_feed_id**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_camera_feed_id**\ (\ ) The ID of the :ref:`CameraFeed` for which we want to display the image. +.. rst-class:: classref-item-separator + ---- .. _class_CameraTexture_property_camera_is_active: -- :ref:`bool` **camera_is_active** +.. rst-class:: classref-property + +:ref:`bool` **camera_is_active** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+--------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------+ -| *Setter* | set_camera_active(value) | -+-----------+--------------------------+ -| *Getter* | get_camera_active() | -+-----------+--------------------------+ +- |void| **set_camera_active**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_camera_active**\ (\ ) Convenience property that gives access to the active property of the :ref:`CameraFeed`. +.. rst-class:: classref-item-separator + ---- .. _class_CameraTexture_property_which_feed: -- :ref:`FeedImage` **which_feed** +.. rst-class:: classref-property + +:ref:`FeedImage` **which_feed** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_which_feed(value) | -+-----------+-----------------------+ -| *Getter* | get_which_feed() | -+-----------+-----------------------+ +- |void| **set_which_feed**\ (\ value\: :ref:`FeedImage`\ ) +- :ref:`FeedImage` **get_which_feed**\ (\ ) Which image within the :ref:`CameraFeed` we want access to, important if the camera image is split in a Y and CbCr component. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_canvasgroup.rst b/classes/class_canvasgroup.rst new file mode 100644 index 00000000000..950c94569f4 --- /dev/null +++ b/classes/class_canvasgroup.rst @@ -0,0 +1,125 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CanvasGroup.xml. + +.. _class_CanvasGroup: + +CanvasGroup +=========== + +**Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` + +Merges several 2D nodes into a single draw operation. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Child :ref:`CanvasItem` nodes of a **CanvasGroup** are drawn as a single object. It allows to e.g. draw overlapping translucent 2D nodes without blending (set :ref:`CanvasItem.self_modulate` property of **CanvasGroup** to achieve this effect). + +\ **Note:** The **CanvasGroup** uses a custom shader to read from the backbuffer to draw its children. Assigning a :ref:`Material` to the **CanvasGroup** overrides the builtin shader. To duplicate the behavior of the builtin shader in a custom :ref:`Shader` use the following: + +:: + + shader_type canvas_item; + render_mode unshaded; + + uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest; + + void fragment() { + vec4 c = textureLod(screen_texture, SCREEN_UV, 0.0); + + if (c.a > 0.0001) { + c.rgb /= c.a; + } + + COLOR *= c; + } + +\ **Note:** Since **CanvasGroup** and :ref:`CanvasItem.clip_children` both utilize the backbuffer, children of a **CanvasGroup** who have their :ref:`CanvasItem.clip_children` set to anything other than :ref:`CanvasItem.CLIP_CHILDREN_DISABLED` will not function correctly. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+--------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`clear_margin` | ``10.0`` | + +---------------------------+--------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`fit_margin` | ``10.0`` | + +---------------------------+--------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`use_mipmaps` | ``false`` | + +---------------------------+--------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CanvasGroup_property_clear_margin: + +.. rst-class:: classref-property + +:ref:`float` **clear_margin** = ``10.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_clear_margin**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_clear_margin**\ (\ ) + +Sets the size of the margin used to expand the clearing rect of this **CanvasGroup**. This expands the area of the backbuffer that will be used by the **CanvasGroup**. A smaller margin will reduce the area of the backbuffer used which can increase performance, however if :ref:`use_mipmaps` is enabled, a small margin may result in mipmap errors at the edge of the **CanvasGroup**. Accordingly, this should be left as small as possible, but should be increased if artifacts appear along the edges of the canvas group. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasGroup_property_fit_margin: + +.. rst-class:: classref-property + +:ref:`float` **fit_margin** = ``10.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_fit_margin**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_fit_margin**\ (\ ) + +Sets the size of a margin used to expand the drawable rect of this **CanvasGroup**. The size of the **CanvasGroup** is determined by fitting a rect around its children then expanding that rect by :ref:`fit_margin`. This increases both the backbuffer area used and the area covered by the **CanvasGroup** both of which can reduce performance. This should be kept as small as possible and should only be expanded when an increased size is needed (e.g. for custom shader effects). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasGroup_property_use_mipmaps: + +.. rst-class:: classref-property + +:ref:`bool` **use_mipmaps** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_mipmaps**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_using_mipmaps**\ (\ ) + +If ``true``, calculates mipmaps for the backbuffer before drawing the **CanvasGroup** so that mipmaps can be used in a custom :ref:`ShaderMaterial` attached to the **CanvasGroup**. Generating mipmaps has a performance cost so this should not be enabled unless required. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index df2df2f41a6..6c8b473aa6f 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CanvasItem.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CanvasItem.xml. .. _class_CanvasItem: @@ -13,786 +14,1676 @@ CanvasItem **Inherited By:** :ref:`Control`, :ref:`Node2D` -Base class of anything 2D. +Abstract base class for everything in 2D space. + +.. rst-class:: classref-introduction-group Description ----------- -Base class of anything 2D. Canvas items are laid out in a tree; children inherit and extend their parent's transform. ``CanvasItem`` is extended by :ref:`Control` for anything GUI-related, and by :ref:`Node2D` for anything related to the 2D engine. +Abstract base class for everything in 2D space. Canvas items are laid out in a tree; children inherit and extend their parent's transform. **CanvasItem** is extended by :ref:`Control` for GUI-related nodes, and by :ref:`Node2D` for 2D game objects. + +Any **CanvasItem** can draw. For this, :ref:`queue_redraw()` is called by the engine, then :ref:`NOTIFICATION_DRAW` will be received on idle time to request a redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the **CanvasItem** are provided (see ``draw_*`` functions). However, they can only be used inside :ref:`_draw()`, its corresponding :ref:`Object._notification()` or methods connected to the :ref:`draw` signal. -Any ``CanvasItem`` can draw. For this, :ref:`update` must be called, then :ref:`NOTIFICATION_DRAW` will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the ``CanvasItem`` are provided (see ``draw_*`` functions). However, they can only be used inside the :ref:`Object._notification`, signal or :ref:`_draw` virtual functions. +Canvas items are drawn in tree order on their canvas layer. By default, children are on top of their parents, so a root **CanvasItem** will be drawn behind everything. This behavior can be changed on a per-item basis. -Canvas items are drawn in tree order. By default, children are on top of their parents so a root ``CanvasItem`` will be drawn behind everything. This behavior can be changed on a per-item basis. +A **CanvasItem** can be hidden, which will also hide its children. By adjusting various other properties of a **CanvasItem**, you can also modulate its color (via :ref:`modulate` or :ref:`self_modulate`), change its Z-index, blend mode, and more. -A ``CanvasItem`` can also be hidden, which will also hide its children. It provides many ways to change parameters such as modulation (for itself and its children) and self modulation (only for itself), as well as its blend mode. +Note that properties like transform, modulation, and visibility are only propagated to *direct* **CanvasItem** child nodes. If there is a non-**CanvasItem** node in between, like :ref:`Node` or :ref:`AnimationPlayer`, the **CanvasItem** nodes below will have an independent position and :ref:`modulate` chain. See also :ref:`top_level`. -Ultimately, a transform notification can be requested, which will notify the node that its global position changed in case the parent tree changed. +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/2d/2d_transforms` +- :doc:`Viewport and canvas transforms <../tutorials/2d/2d_transforms>` + +- :doc:`Custom drawing in 2D <../tutorials/2d/custom_drawing_in_2d>` + +- `Audio Spectrum Visualizer Demo `__ -- :doc:`../tutorials/2d/custom_drawing_in_2d` +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`light_mask` | ``1`` | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`Material` | :ref:`material` | | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`modulate` | ``Color( 1, 1, 1, 1 )`` | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`self_modulate` | ``Color( 1, 1, 1, 1 )`` | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`show_behind_parent` | ``false`` | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`show_on_top` | | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`TextureFilter` | :ref:`texture_filter` | ``0`` | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`TextureRepeat` | :ref:`texture_repeat` | ``0`` | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`use_parent_material` | ``false`` | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`visible` | ``true`` | -+-----------------------------------------------------+---------------------------------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`ClipChildrenMode` | :ref:`clip_children` | ``0`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`light_mask` | ``1`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`Material` | :ref:`material` | | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`modulate` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`self_modulate` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`show_behind_parent` | ``false`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`TextureFilter` | :ref:`texture_filter` | ``0`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`TextureRepeat` | :ref:`texture_repeat` | ``0`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`top_level` | ``false`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`use_parent_material` | ``false`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`visibility_layer` | ``1`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`visible` | ``true`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`y_sort_enabled` | ``false`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`z_as_relative` | ``true`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`z_index` | ``0`` | + +-----------------------------------------------------------+---------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`_draw` **(** **)** virtual | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_arc` **(** :ref:`Vector2` center, :ref:`float` radius, :ref:`float` start_angle, :ref:`float` end_angle, :ref:`int` point_count, :ref:`Color` color, :ref:`float` width=1.0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`draw_char` **(** :ref:`Font` font, :ref:`Vector2` position, :ref:`String` char, :ref:`String` next, :ref:`Color` modulate=Color( 1, 1, 1, 1 ) **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_circle` **(** :ref:`Vector2` position, :ref:`float` radius, :ref:`Color` color **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_colored_polygon` **(** :ref:`PackedVector2Array` points, :ref:`Color` color, :ref:`PackedVector2Array` uvs=PackedVector2Array( ), :ref:`Texture2D` texture=null, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_line` **(** :ref:`Vector2` from, :ref:`Vector2` to, :ref:`Color` color, :ref:`float` width=1.0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_mesh` **(** :ref:`Mesh` mesh, :ref:`Texture2D` texture, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`Transform2D` transform=Transform2D( 1, 0, 0, 1, 0, 0 ), :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_multiline` **(** :ref:`PackedVector2Array` points, :ref:`Color` color, :ref:`float` width=1.0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_multiline_colors` **(** :ref:`PackedVector2Array` points, :ref:`PackedColorArray` colors, :ref:`float` width=1.0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_multimesh` **(** :ref:`MultiMesh` multimesh, :ref:`Texture2D` texture, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_polygon` **(** :ref:`PackedVector2Array` points, :ref:`PackedColorArray` colors, :ref:`PackedVector2Array` uvs=PackedVector2Array( ), :ref:`Texture2D` texture=null, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_polyline` **(** :ref:`PackedVector2Array` points, :ref:`Color` color, :ref:`float` width=1.0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_polyline_colors` **(** :ref:`PackedVector2Array` points, :ref:`PackedColorArray` colors, :ref:`float` width=1.0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_primitive` **(** :ref:`PackedVector2Array` points, :ref:`PackedColorArray` colors, :ref:`PackedVector2Array` uvs, :ref:`Texture2D` texture=null, :ref:`float` width=1.0, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_rect` **(** :ref:`Rect2` rect, :ref:`Color` color, :ref:`bool` filled=true, :ref:`float` width=1.0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_set_transform` **(** :ref:`Vector2` position, :ref:`float` rotation, :ref:`Vector2` scale **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_set_transform_matrix` **(** :ref:`Transform2D` xform **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_string` **(** :ref:`Font` font, :ref:`Vector2` position, :ref:`String` text, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`int` clip_w=-1 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_style_box` **(** :ref:`StyleBox` style_box, :ref:`Rect2` rect **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_texture` **(** :ref:`Texture2D` texture, :ref:`Vector2` position, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_texture_rect` **(** :ref:`Texture2D` texture, :ref:`Rect2` rect, :ref:`bool` tile, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`bool` transpose=false, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`draw_texture_rect_region` **(** :ref:`Texture2D` texture, :ref:`Rect2` rect, :ref:`Rect2` src_rect, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`bool` transpose=false, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`bool` clip_uv=true, :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`force_update_transform` **(** **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`RID` | :ref:`get_canvas` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`RID` | :ref:`get_canvas_item` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform2D` | :ref:`get_canvas_transform` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_global_mouse_position` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform2D` | :ref:`get_global_transform` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform2D` | :ref:`get_global_transform_with_canvas` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_local_mouse_position` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform2D` | :ref:`get_transform` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Rect2` | :ref:`get_viewport_rect` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform2D` | :ref:`get_viewport_transform` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`World2D` | :ref:`get_world_2d` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`hide` **(** **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_local_transform_notification_enabled` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_set_as_toplevel` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_transform_notification_enabled` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_visible_in_tree` **(** **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`make_canvas_position_local` **(** :ref:`Vector2` screen_point **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`InputEvent` | :ref:`make_input_local` **(** :ref:`InputEvent` event **)** const | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_as_toplevel` **(** :ref:`bool` enable **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_notify_local_transform` **(** :ref:`bool` enable **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_notify_transform` **(** :ref:`bool` enable **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`show` **(** **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`update` **(** **)** | -+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_draw`\ (\ ) |virtual| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_animation_slice`\ (\ animation_length\: :ref:`float`, slice_begin\: :ref:`float`, slice_end\: :ref:`float`, offset\: :ref:`float` = 0.0\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_arc`\ (\ center\: :ref:`Vector2`, radius\: :ref:`float`, start_angle\: :ref:`float`, end_angle\: :ref:`float`, point_count\: :ref:`int`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_char`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_char_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, size\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_circle`\ (\ position\: :ref:`Vector2`, radius\: :ref:`float`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_colored_polygon`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_dashed_line`\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, dash\: :ref:`float` = 2.0, aligned\: :ref:`bool` = true, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_ellipse`\ (\ position\: :ref:`Vector2`, major\: :ref:`float`, minor\: :ref:`float`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_ellipse_arc`\ (\ center\: :ref:`Vector2`, major\: :ref:`float`, minor\: :ref:`float`, start_angle\: :ref:`float`, end_angle\: :ref:`float`, point_count\: :ref:`int`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_end_animation`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_lcd_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_line`\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_mesh`\ (\ mesh\: :ref:`Mesh`, texture\: :ref:`Texture2D`, transform\: :ref:`Transform2D` = Transform2D(1, 0, 0, 1, 0, 0), modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_msdf_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), outline\: :ref:`float` = 0.0, pixel_range\: :ref:`float` = 4.0, scale\: :ref:`float` = 1.0\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multiline`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multiline_colors`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multiline_string`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multiline_string_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multimesh`\ (\ multimesh\: :ref:`MultiMesh`, texture\: :ref:`Texture2D`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_polygon`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_polyline`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_polyline_colors`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_primitive`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array`, texture\: :ref:`Texture2D` = null\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_rect`\ (\ rect\: :ref:`Rect2`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_set_transform`\ (\ position\: :ref:`Vector2`, rotation\: :ref:`float` = 0.0, scale\: :ref:`Vector2` = Vector2(1, 1)\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_set_transform_matrix`\ (\ xform\: :ref:`Transform2D`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_string`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_string_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_style_box`\ (\ style_box\: :ref:`StyleBox`, rect\: :ref:`Rect2`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_texture`\ (\ texture\: :ref:`Texture2D`, position\: :ref:`Vector2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_texture_rect`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, tile\: :ref:`bool`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false, clip_uv\: :ref:`bool` = true\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`force_update_transform`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_canvas`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_canvas_item`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`CanvasLayer` | :ref:`get_canvas_layer_node`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_canvas_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_global_mouse_position`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_global_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_global_transform_with_canvas`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get_instance_shader_parameter`\ (\ name\: :ref:`StringName`\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_local_mouse_position`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_screen_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Rect2` | :ref:`get_viewport_rect`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_viewport_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_visibility_layer_bit`\ (\ layer\: :ref:`int`\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`World2D` | :ref:`get_world_2d`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`hide`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_local_transform_notification_enabled`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_transform_notification_enabled`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_visible_in_tree`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`make_canvas_position_local`\ (\ viewport_point\: :ref:`Vector2`\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`InputEvent` | :ref:`make_input_local`\ (\ event\: :ref:`InputEvent`\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`move_to_front`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`queue_redraw`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_instance_shader_parameter`\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_notify_local_transform`\ (\ enable\: :ref:`bool`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_notify_transform`\ (\ enable\: :ref:`bool`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_visibility_layer_bit`\ (\ layer\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`show`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_CanvasItem_signal_draw: -- **draw** **(** **)** +.. rst-class:: classref-signal + +**draw**\ (\ ) :ref:`🔗` -Emitted when the ``CanvasItem`` must redraw. This can only be connected realtime, as deferred will not allow drawing. +Emitted when the **CanvasItem** must redraw, *after* the related :ref:`NOTIFICATION_DRAW` notification, and *before* :ref:`_draw()` is called. + +\ **Note:** Deferred connections do not allow drawing through the ``draw_*`` methods. + +.. rst-class:: classref-item-separator ---- -.. _class_CanvasItem_signal_hide: +.. _class_CanvasItem_signal_hidden: + +.. rst-class:: classref-signal + +**hidden**\ (\ ) :ref:`🔗` -- **hide** **(** **)** +Emitted when this node becomes hidden, i.e. it's no longer visible in the tree (see :ref:`is_visible_in_tree()`). -Emitted when becoming hidden. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_signal_item_rect_changed: -- **item_rect_changed** **(** **)** +.. rst-class:: classref-signal -Emitted when the item rect has changed. +**item_rect_changed**\ (\ ) :ref:`🔗` + +Emitted when the **CanvasItem**'s boundaries (position or size) change, or when an action took place that may have affected these boundaries (e.g. changing :ref:`Sprite2D.texture`). + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_signal_visibility_changed: -- **visibility_changed** **(** **)** +.. rst-class:: classref-signal + +**visibility_changed**\ (\ ) :ref:`🔗` -Emitted when the visibility (hidden/visible) changes. +Emitted when the **CanvasItem**'s visibility changes, either because its own :ref:`visible` property changed or because its visibility in the tree changed (see :ref:`is_visible_in_tree()`). + +This signal is emitted *after* the related :ref:`NOTIFICATION_VISIBILITY_CHANGED` notification. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_CanvasItem_TextureFilter: +.. rst-class:: classref-enumeration + +enum **TextureFilter**: :ref:`🔗` + .. _class_CanvasItem_constant_TEXTURE_FILTER_PARENT_NODE: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_PARENT_NODE** = ``0`` + +The **CanvasItem** will inherit the filter from its parent. + .. _class_CanvasItem_constant_TEXTURE_FILTER_NEAREST: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_NEAREST** = ``1`` + +The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). + .. _class_CanvasItem_constant_TEXTURE_FILTER_LINEAR: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_LINEAR** = ``2`` + +The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). + .. _class_CanvasItem_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = ``3`` + +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. + .. _class_CanvasItem_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureFilter` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = ``4`` + +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look smooth from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. + .. _class_CanvasItem_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC: -.. _class_CanvasItem_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC: +.. rst-class:: classref-enumeration-constant -.. _class_CanvasItem_constant_TEXTURE_FILTER_MAX: +:ref:`TextureFilter` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = ``5`` -enum **TextureFilter**: +The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. -- **TEXTURE_FILTER_PARENT_NODE** = **0** --- The ``CanvasItem`` will inherit the filter from its parent. +\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`TEXTURE_FILTER_NEAREST_WITH_MIPMAPS` is usually more appropriate in this case. -- **TEXTURE_FILTER_NEAREST** = **1** --- The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering. Useful for pixel art. +.. _class_CanvasItem_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC: -- **TEXTURE_FILTER_LINEAR** = **2** --- The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. +.. rst-class:: classref-enumeration-constant -- **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = **3** +:ref:`TextureFilter` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = ``6`` -- **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = **4** +The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. + +\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`TEXTURE_FILTER_LINEAR_WITH_MIPMAPS` is usually more appropriate in this case. + +.. _class_CanvasItem_constant_TEXTURE_FILTER_MAX: -- **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = **5** +.. rst-class:: classref-enumeration-constant -- **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = **6** +:ref:`TextureFilter` **TEXTURE_FILTER_MAX** = ``7`` -- **TEXTURE_FILTER_MAX** = **7** --- Represents the size of the :ref:`TextureFilter` enum. +Represents the size of the :ref:`TextureFilter` enum. + +.. rst-class:: classref-item-separator ---- .. _enum_CanvasItem_TextureRepeat: +.. rst-class:: classref-enumeration + +enum **TextureRepeat**: :ref:`🔗` + .. _class_CanvasItem_constant_TEXTURE_REPEAT_PARENT_NODE: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureRepeat` **TEXTURE_REPEAT_PARENT_NODE** = ``0`` + +The **CanvasItem** will inherit the filter from its parent. + .. _class_CanvasItem_constant_TEXTURE_REPEAT_DISABLED: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureRepeat` **TEXTURE_REPEAT_DISABLED** = ``1`` + +The texture does not repeat. Sampling the texture outside its extents will result in "stretching" of the edge pixels. You can avoid this by ensuring a 1-pixel fully transparent border on each side of the texture. + .. _class_CanvasItem_constant_TEXTURE_REPEAT_ENABLED: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureRepeat` **TEXTURE_REPEAT_ENABLED** = ``2`` + +The texture repeats when exceeding the texture's size. + .. _class_CanvasItem_constant_TEXTURE_REPEAT_MIRROR: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureRepeat` **TEXTURE_REPEAT_MIRROR** = ``3`` + +The texture repeats when the exceeding the texture's size in a "2×2 tiled mode". Repeated textures at even positions are mirrored. + .. _class_CanvasItem_constant_TEXTURE_REPEAT_MAX: -enum **TextureRepeat**: +.. rst-class:: classref-enumeration-constant + +:ref:`TextureRepeat` **TEXTURE_REPEAT_MAX** = ``4`` + +Represents the size of the :ref:`TextureRepeat` enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_CanvasItem_ClipChildrenMode: + +.. rst-class:: classref-enumeration + +enum **ClipChildrenMode**: :ref:`🔗` + +.. _class_CanvasItem_constant_CLIP_CHILDREN_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`ClipChildrenMode` **CLIP_CHILDREN_DISABLED** = ``0`` + +Children are drawn over this node and are not clipped. + +.. _class_CanvasItem_constant_CLIP_CHILDREN_ONLY: + +.. rst-class:: classref-enumeration-constant -- **TEXTURE_REPEAT_PARENT_NODE** = **0** --- The ``CanvasItem`` will inherit the filter from its parent. +:ref:`ClipChildrenMode` **CLIP_CHILDREN_ONLY** = ``1`` -- **TEXTURE_REPEAT_DISABLED** = **1** --- Texture will not repeat. +This node is used as a mask and is **not** drawn. The mask is based on this node's alpha channel: Opaque pixels are kept, transparent pixels are discarded, and semi-transparent pixels are blended in according to their opacity. Children are clipped to this node's drawn area. -- **TEXTURE_REPEAT_ENABLED** = **2** --- Texture will repeat normally. +.. _class_CanvasItem_constant_CLIP_CHILDREN_AND_DRAW: -- **TEXTURE_REPEAT_MIRROR** = **3** --- Texture will repeat in a 2x2 tiled mode, where elements at even positions are mirrored. +.. rst-class:: classref-enumeration-constant -- **TEXTURE_REPEAT_MAX** = **4** --- Represents the size of the :ref:`TextureRepeat` enum. +:ref:`ClipChildrenMode` **CLIP_CHILDREN_AND_DRAW** = ``2`` + +This node is used as a mask and is also drawn. The mask is based on this node's alpha channel: Opaque pixels are kept, transparent pixels are discarded, and semi-transparent pixels are blended in according to their opacity. Children are clipped to the parent's drawn area. + +.. _class_CanvasItem_constant_CLIP_CHILDREN_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`ClipChildrenMode` **CLIP_CHILDREN_MAX** = ``3`` + +Represents the size of the :ref:`ClipChildrenMode` enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Constants --------- .. _class_CanvasItem_constant_NOTIFICATION_TRANSFORM_CHANGED: +.. rst-class:: classref-constant + +**NOTIFICATION_TRANSFORM_CHANGED** = ``2000`` :ref:`🔗` + +Notification received when this node's global transform changes, if :ref:`is_transform_notification_enabled()` is ``true``. See also :ref:`set_notify_transform()` and :ref:`get_transform()`. + +\ **Note:** Many canvas items such as :ref:`Camera2D` or :ref:`CollisionObject2D` automatically enable this in order to function correctly. + +.. _class_CanvasItem_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED: + +.. rst-class:: classref-constant + +**NOTIFICATION_LOCAL_TRANSFORM_CHANGED** = ``35`` :ref:`🔗` + +Notification received when this node's transform changes, if :ref:`is_local_transform_notification_enabled()` is ``true``. This is not received when a parent :ref:`Node2D`'s transform changes. See also :ref:`set_notify_local_transform()`. + +\ **Note:** Many canvas items such as :ref:`Camera2D` or :ref:`CollisionShape2D` automatically enable this in order to function correctly. + .. _class_CanvasItem_constant_NOTIFICATION_DRAW: +.. rst-class:: classref-constant + +**NOTIFICATION_DRAW** = ``30`` :ref:`🔗` + +The **CanvasItem** is requested to draw (see :ref:`_draw()`). + .. _class_CanvasItem_constant_NOTIFICATION_VISIBILITY_CHANGED: +.. rst-class:: classref-constant + +**NOTIFICATION_VISIBILITY_CHANGED** = ``31`` :ref:`🔗` + +Notification received when this node's visibility changes (see :ref:`visible` and :ref:`is_visible_in_tree()`). + +This notification is received *before* the related :ref:`visibility_changed` signal. + .. _class_CanvasItem_constant_NOTIFICATION_ENTER_CANVAS: +.. rst-class:: classref-constant + +**NOTIFICATION_ENTER_CANVAS** = ``32`` :ref:`🔗` + +The **CanvasItem** has entered the canvas. + .. _class_CanvasItem_constant_NOTIFICATION_EXIT_CANVAS: -- **NOTIFICATION_TRANSFORM_CHANGED** = **2000** --- The ``CanvasItem``'s transform has changed. This notification is only received if enabled by :ref:`set_notify_transform` or :ref:`set_notify_local_transform`. +.. rst-class:: classref-constant + +**NOTIFICATION_EXIT_CANVAS** = ``33`` :ref:`🔗` + +The **CanvasItem** has exited the canvas. -- **NOTIFICATION_DRAW** = **30** --- The ``CanvasItem`` is requested to draw. +.. _class_CanvasItem_constant_NOTIFICATION_WORLD_2D_CHANGED: -- **NOTIFICATION_VISIBILITY_CHANGED** = **31** --- The ``CanvasItem``'s visibility has changed. +.. rst-class:: classref-constant -- **NOTIFICATION_ENTER_CANVAS** = **32** --- The ``CanvasItem`` has entered the canvas. +**NOTIFICATION_WORLD_2D_CHANGED** = ``36`` :ref:`🔗` -- **NOTIFICATION_EXIT_CANVAS** = **33** --- The ``CanvasItem`` has exited the canvas. +Notification received when this **CanvasItem** is registered to a new :ref:`World2D` (see :ref:`get_world_2d()`). + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- +.. _class_CanvasItem_property_clip_children: + +.. rst-class:: classref-property + +:ref:`ClipChildrenMode` **clip_children** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_clip_children_mode**\ (\ value\: :ref:`ClipChildrenMode`\ ) +- :ref:`ClipChildrenMode` **get_clip_children_mode**\ (\ ) + +The mode in which this node clips its children, acting as a mask. + +\ **Note:** Clipping nodes cannot be nested or placed within a :ref:`CanvasGroup`. If an ancestor of this node clips its children or is a :ref:`CanvasGroup`, then this node's clip mode should be set to :ref:`CLIP_CHILDREN_DISABLED` to avoid unexpected behavior. + +.. rst-class:: classref-item-separator + +---- + .. _class_CanvasItem_property_light_mask: -- :ref:`int` **light_mask** +.. rst-class:: classref-property -+-----------+-----------------------+ -| *Default* | ``1`` | -+-----------+-----------------------+ -| *Setter* | set_light_mask(value) | -+-----------+-----------------------+ -| *Getter* | get_light_mask() | -+-----------+-----------------------+ +:ref:`int` **light_mask** = ``1`` :ref:`🔗` -The rendering layers in which this ``CanvasItem`` responds to :ref:`Light2D` nodes. +.. rst-class:: classref-property-setget + +- |void| **set_light_mask**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_light_mask**\ (\ ) + +The rendering layers in which this **CanvasItem** responds to :ref:`Light2D` nodes. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_property_material: -- :ref:`Material` **material** +.. rst-class:: classref-property + +:ref:`Material` **material** :ref:`🔗` -+----------+---------------------+ -| *Setter* | set_material(value) | -+----------+---------------------+ -| *Getter* | get_material() | -+----------+---------------------+ +.. rst-class:: classref-property-setget -The material applied to textures on this ``CanvasItem``. +- |void| **set_material**\ (\ value\: :ref:`Material`\ ) +- :ref:`Material` **get_material**\ (\ ) + +The material applied to this **CanvasItem**. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_property_modulate: -- :ref:`Color` **modulate** +.. rst-class:: classref-property + +:ref:`Color` **modulate** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``Color( 1, 1, 1, 1 )`` | -+-----------+-------------------------+ -| *Setter* | set_modulate(value) | -+-----------+-------------------------+ -| *Getter* | get_modulate() | -+-----------+-------------------------+ +- |void| **set_modulate**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_modulate**\ (\ ) -The color applied to textures on this ``CanvasItem``. +The color applied to this **CanvasItem**. This property does affect child **CanvasItem**\ s, unlike :ref:`self_modulate` which only affects the node itself. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_property_self_modulate: -- :ref:`Color` **self_modulate** +.. rst-class:: classref-property + +:ref:`Color` **self_modulate** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_self_modulate**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_self_modulate**\ (\ ) -+-----------+--------------------------+ -| *Default* | ``Color( 1, 1, 1, 1 )`` | -+-----------+--------------------------+ -| *Setter* | set_self_modulate(value) | -+-----------+--------------------------+ -| *Getter* | get_self_modulate() | -+-----------+--------------------------+ +The color applied to this **CanvasItem**. This property does **not** affect child **CanvasItem**\ s, unlike :ref:`modulate` which affects both the node itself and its children. -The color applied to textures on this ``CanvasItem``. This is not inherited by children ``CanvasItem``\ s. +\ **Note:** Internal children are also not affected by this property (see the ``include_internal`` parameter in :ref:`Node.add_child()`). For built-in nodes this includes sliders in :ref:`ColorPicker`, and the tab bar in :ref:`TabContainer`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_property_show_behind_parent: -- :ref:`bool` **show_behind_parent** - -+-----------+---------------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------------+ -| *Setter* | set_draw_behind_parent(value) | -+-----------+---------------------------------+ -| *Getter* | is_draw_behind_parent_enabled() | -+-----------+---------------------------------+ +.. rst-class:: classref-property -If ``true``, the object draws behind its parent. +:ref:`bool` **show_behind_parent** = ``false`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_CanvasItem_property_show_on_top: +- |void| **set_draw_behind_parent**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_draw_behind_parent_enabled**\ (\ ) -- :ref:`bool` **show_on_top** +If ``true``, this node draws behind its parent. -If ``true``, the object draws on top of its parent. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_property_texture_filter: -- :ref:`TextureFilter` **texture_filter** +.. rst-class:: classref-property -+-----------+---------------------------+ -| *Default* | ``0`` | -+-----------+---------------------------+ -| *Setter* | set_texture_filter(value) | -+-----------+---------------------------+ -| *Getter* | get_texture_filter() | -+-----------+---------------------------+ +:ref:`TextureFilter` **texture_filter** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture_filter**\ (\ value\: :ref:`TextureFilter`\ ) +- :ref:`TextureFilter` **get_texture_filter**\ (\ ) + +The filtering mode used to render this **CanvasItem**'s texture(s). + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_property_texture_repeat: -- :ref:`TextureRepeat` **texture_repeat** +.. rst-class:: classref-property + +:ref:`TextureRepeat` **texture_repeat** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture_repeat**\ (\ value\: :ref:`TextureRepeat`\ ) +- :ref:`TextureRepeat` **get_texture_repeat**\ (\ ) + +The repeating mode used to render this **CanvasItem**'s texture(s). It affects what happens when the texture is sampled outside its extents, for example by setting a :ref:`Sprite2D.region_rect` that is larger than the texture or assigning :ref:`Polygon2D` UV points outside the texture. -+-----------+---------------------------+ -| *Default* | ``0`` | -+-----------+---------------------------+ -| *Setter* | set_texture_repeat(value) | -+-----------+---------------------------+ -| *Getter* | get_texture_repeat() | -+-----------+---------------------------+ +\ **Note:** :ref:`TextureRect` is not affected by :ref:`texture_repeat`, as it uses its own texture repeating implementation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_property_top_level: + +.. rst-class:: classref-property + +:ref:`bool` **top_level** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_as_top_level**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_set_as_top_level**\ (\ ) + +If ``true``, this **CanvasItem** will *not* inherit its transform from parent **CanvasItem**\ s. Its draw order will also be changed to make it draw on top of other **CanvasItem**\ s that do not have :ref:`top_level` set to ``true``. The **CanvasItem** will effectively act as if it was placed as a child of a bare :ref:`Node`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_property_use_parent_material: -- :ref:`bool` **use_parent_material** +.. rst-class:: classref-property + +:ref:`bool` **use_parent_material** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_parent_material**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_use_parent_material**\ (\ ) + +If ``true``, the parent **CanvasItem**'s :ref:`material` is used as this node's material. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_property_visibility_layer: + +.. rst-class:: classref-property + +:ref:`int` **visibility_layer** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_visibility_layer**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_visibility_layer**\ (\ ) -+-----------+--------------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------------+ -| *Setter* | set_use_parent_material(value) | -+-----------+--------------------------------+ -| *Getter* | get_use_parent_material() | -+-----------+--------------------------------+ +The rendering layer in which this **CanvasItem** is rendered by :ref:`Viewport` nodes. A :ref:`Viewport` will render a **CanvasItem** if it and all its parents share a layer with the :ref:`Viewport`'s canvas cull mask. -If ``true``, the parent ``CanvasItem``'s :ref:`material` property is used as this one's material. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_property_visible: -- :ref:`bool` **visible** +.. rst-class:: classref-property + +:ref:`bool` **visible** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_visible**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_visible**\ (\ ) + +If ``true``, this **CanvasItem** may be drawn. Whether this **CanvasItem** is actually drawn depends on the visibility of all of its **CanvasItem** ancestors. In other words: this **CanvasItem** will be drawn when :ref:`is_visible_in_tree()` returns ``true`` and all **CanvasItem** ancestors share at least one :ref:`visibility_layer` with this **CanvasItem**. + +\ **Note:** For controls that inherit :ref:`Popup`, the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_property_y_sort_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **y_sort_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_y_sort_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_y_sort_enabled**\ (\ ) + +If ``true``, this and child **CanvasItem** nodes with a higher Y position are rendered in front of nodes with a lower Y position. If ``false``, this and child **CanvasItem** nodes are rendered normally in scene tree order. -+-----------+--------------------+ -| *Default* | ``true`` | -+-----------+--------------------+ -| *Setter* | set_visible(value) | -+-----------+--------------------+ -| *Getter* | is_visible() | -+-----------+--------------------+ +With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc.) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree. -If ``true``, this ``CanvasItem`` is drawn. For controls that inherit :ref:`Popup`, the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. +Nodes sort relative to each other only if they are on the same :ref:`z_index`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_property_z_as_relative: + +.. rst-class:: classref-property + +:ref:`bool` **z_as_relative** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_z_as_relative**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_z_relative**\ (\ ) + +If ``true``, this node's final Z index is relative to its parent's Z index. + +For example, if :ref:`z_index` is ``2`` and its parent's final Z index is ``3``, then this node's final Z index will be ``5`` (``2 + 3``). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_property_z_index: + +.. rst-class:: classref-property + +:ref:`int` **z_index** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_z_index**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_z_index**\ (\ ) + +The order in which this node is drawn. A node with a higher Z index will display in front of others. Must be between :ref:`RenderingServer.CANVAS_ITEM_Z_MIN` and :ref:`RenderingServer.CANVAS_ITEM_Z_MAX` (inclusive). + +\ **Note:** The Z index does **not** affect the order in which **CanvasItem** nodes are processed or the way input events are handled. This is especially important to keep in mind for :ref:`Control` nodes. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_CanvasItem_method__draw: +.. _class_CanvasItem_private_method__draw: + +.. rst-class:: classref-method + +|void| **_draw**\ (\ ) |virtual| :ref:`🔗` + +Called when **CanvasItem** has been requested to redraw (after :ref:`queue_redraw()` is called, either manually or by the engine). -- void **_draw** **(** **)** virtual +Corresponds to the :ref:`NOTIFICATION_DRAW` notification in :ref:`Object._notification()`. -Overridable function called by the engine (if defined) to draw the canvas item. +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_animation_slice: + +.. rst-class:: classref-method + +|void| **draw_animation_slice**\ (\ animation_length\: :ref:`float`, slice_begin\: :ref:`float`, slice_end\: :ref:`float`, offset\: :ref:`float` = 0.0\ ) :ref:`🔗` + +Subsequent drawing commands will be ignored unless they fall within the specified animation slice. This is a faster way to implement animations that loop on background rather than redrawing constantly. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_arc: -- void **draw_arc** **(** :ref:`Vector2` center, :ref:`float` radius, :ref:`float` start_angle, :ref:`float` end_angle, :ref:`int` point_count, :ref:`Color` color, :ref:`float` width=1.0 **)** +.. rst-class:: classref-method + +|void| **draw_arc**\ (\ center\: :ref:`Vector2`, radius\: :ref:`float`, start_angle\: :ref:`float`, end_angle\: :ref:`float`, point_count\: :ref:`int`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws an unfilled arc between the given angles with a uniform ``color`` and ``width`` and optional antialiasing (supported only for positive ``width``). The larger the value of ``point_count``, the smoother the curve. ``center`` is defined in local space. For elliptical arcs, see :ref:`draw_ellipse_arc()`. See also :ref:`draw_circle()`. + +If ``width`` is negative, it will be ignored and the arc will be drawn using :ref:`RenderingServer.PRIMITIVE_LINE_STRIP`. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +The arc is drawn from ``start_angle`` towards the value of ``end_angle`` so in clockwise direction if ``start_angle < end_angle`` and counter-clockwise otherwise. Passing the same angles but in reversed order will produce the same arc. If absolute difference of ``start_angle`` and ``end_angle`` is greater than :ref:`@GDScript.TAU` radians, then a full circle arc is drawn (i.e. arc will not overlap itself). -Draws an arc between the given angles. The larger the value of ``point_count``, the smoother the curve. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_char: -- :ref:`float` **draw_char** **(** :ref:`Font` font, :ref:`Vector2` position, :ref:`String` char, :ref:`String` next, :ref:`Color` modulate=Color( 1, 1, 1, 1 ) **)** +.. rst-class:: classref-method -Draws a string character using a custom font. Returns the advance, depending on the character width and kerning with an optional next character. +|void| **draw_char**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` + +Draws a string first character using a custom font. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. ``pos`` is defined in local space. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_char_outline: + +.. rst-class:: classref-method + +|void| **draw_char_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, size\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` + +Draws a string first character outline using a custom font. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. ``pos`` is defined in local space. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_circle: -- void **draw_circle** **(** :ref:`Vector2` position, :ref:`float` radius, :ref:`Color` color **)** +.. rst-class:: classref-method + +|void| **draw_circle**\ (\ position\: :ref:`Vector2`, radius\: :ref:`float`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws a circle, with ``position`` defined in local space. See also :ref:`draw_ellipse()`, :ref:`draw_arc()`, :ref:`draw_polyline()`, and :ref:`draw_polygon()`. + +If ``filled`` is ``true``, the circle will be filled with the ``color`` specified. If ``filled`` is ``false``, the circle will be drawn as a stroke with the ``color`` and ``width`` specified. + +If ``width`` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +If ``antialiased`` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. -Draws a colored circle. +\ **Note:** ``width`` is only effective if ``filled`` is ``false``. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_colored_polygon: -- void **draw_colored_polygon** **(** :ref:`PackedVector2Array` points, :ref:`Color` color, :ref:`PackedVector2Array` uvs=PackedVector2Array( ), :ref:`Texture2D` texture=null, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** +.. rst-class:: classref-method + +|void| **draw_colored_polygon**\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) :ref:`🔗` + +Draws a colored polygon of any number of points, convex or concave. The points in the ``points`` array are defined in local space. Unlike :ref:`draw_polygon()`, a single color must be specified for the whole polygon. + +\ **Note:** If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with :ref:`Geometry2D.triangulate_polygon()` and using :ref:`draw_mesh()`, :ref:`draw_multimesh()`, or :ref:`RenderingServer.canvas_item_add_triangle_array()`. -Draws a colored polygon of any amount of points, convex or concave. +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_dashed_line: + +.. rst-class:: classref-method + +|void| **draw_dashed_line**\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, dash\: :ref:`float` = 2.0, aligned\: :ref:`bool` = true, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws a dashed line from a 2D point to another, with a given color and width. The ``from`` and ``to`` positions are defined in local space. See also :ref:`draw_line()`, :ref:`draw_multiline()`, and :ref:`draw_polyline()`. + +If ``width`` is negative, then a two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the line parts will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +\ ``dash`` is the length of each dash in pixels, with the gap between each dash being the same length. If ``aligned`` is ``true``, the length of the first and last dashes may be shortened or lengthened to allow the line to begin and end at the precise points defined by ``from`` and ``to``. Both ends are always symmetrical when ``aligned`` is ``true``. If ``aligned`` is ``false``, all dashes will have the same length, but the line may appear incomplete at the end due to the dash length not dividing evenly into the line length. Only full dashes are drawn when ``aligned`` is ``false``. + +If ``antialiased`` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. + +\ **Note:** ``antialiased`` is only effective if ``width`` is greater than ``0.0``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_ellipse: + +.. rst-class:: classref-method + +|void| **draw_ellipse**\ (\ position\: :ref:`Vector2`, major\: :ref:`float`, minor\: :ref:`float`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws an ellipse with semi-major axis ``major`` and semi-minor axis ``minor``. See also :ref:`draw_circle()`, :ref:`draw_ellipse_arc()`, :ref:`draw_polyline()`, and :ref:`draw_polygon()`. + +If ``filled`` is ``true``, the ellipse will be filled with the ``color`` specified. If ``filled`` is ``false``, the ellipse will be drawn as a stroke with the ``color`` and ``width`` specified. + +If ``width`` is negative, then two-point primitives will be drawn instead of four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +If ``antialiased`` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. + +\ **Note:** ``width`` is only effective if ``filled`` is ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_ellipse_arc: + +.. rst-class:: classref-method + +|void| **draw_ellipse_arc**\ (\ center\: :ref:`Vector2`, major\: :ref:`float`, minor\: :ref:`float`, start_angle\: :ref:`float`, end_angle\: :ref:`float`, point_count\: :ref:`int`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws an unfilled elliptical arc between the given angles with a uniform ``color`` and ``width`` and optional antialiasing (supported only for positive ``width``). The larger the value of ``point_count``, the smoother the curve. For circular arcs, see :ref:`draw_arc()`. See also :ref:`draw_ellipse()`. + +If ``width`` is negative, it will be ignored and the arc will be drawn using :ref:`RenderingServer.PRIMITIVE_LINE_STRIP`. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +The arc is drawn from ``start_angle`` towards the value of ``end_angle`` so in clockwise direction if ``start_angle < end_angle`` and counter-clockwise otherwise. Passing the same angles but in reversed order will produce the same arc. If absolute difference of ``start_angle`` and ``end_angle`` is greater than :ref:`@GDScript.TAU` radians, then a full ellipse is drawn (i.e. arc will not overlap itself). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_end_animation: + +.. rst-class:: classref-method + +|void| **draw_end_animation**\ (\ ) :ref:`🔗` + +After submitting all animations slices via :ref:`draw_animation_slice()`, this function can be used to revert drawing to its default state (all subsequent drawing commands will be visible). If you don't care about this particular use case, usage of this function after submitting the slices is not required. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_lcd_texture_rect_region: + +.. rst-class:: classref-method + +|void| **draw_lcd_texture_rect_region**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) :ref:`🔗` + +Draws a textured rectangle region of the font texture with LCD subpixel anti-aliasing at a given position, optionally modulated by a color. The ``rect`` is defined in local space. + +Texture is drawn using the following blend operation, blend mode of the :ref:`CanvasItemMaterial` is ignored: + +:: + + dst.r = texture.r * modulate.r * modulate.a + dst.r * (1.0 - texture.r * modulate.a); + dst.g = texture.g * modulate.g * modulate.a + dst.g * (1.0 - texture.g * modulate.a); + dst.b = texture.b * modulate.b * modulate.a + dst.b * (1.0 - texture.b * modulate.a); + dst.a = modulate.a + dst.a * (1.0 - modulate.a); + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_line: -- void **draw_line** **(** :ref:`Vector2` from, :ref:`Vector2` to, :ref:`Color` color, :ref:`float` width=1.0 **)** +.. rst-class:: classref-method -Draws a line from a 2D point to another, with a given color and width. +|void| **draw_line**\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. The ``from`` and ``to`` positions are defined in local space. See also :ref:`draw_dashed_line()`, :ref:`draw_multiline()`, and :ref:`draw_polyline()`. + +If ``width`` is negative, then a two-point primitive will be drawn instead of a four-point one. This means that when the CanvasItem is scaled, the line will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_mesh: -- void **draw_mesh** **(** :ref:`Mesh` mesh, :ref:`Texture2D` texture, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`Transform2D` transform=Transform2D( 1, 0, 0, 1, 0, 0 ), :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** +.. rst-class:: classref-method + +|void| **draw_mesh**\ (\ mesh\: :ref:`Mesh`, texture\: :ref:`Texture2D`, transform\: :ref:`Transform2D` = Transform2D(1, 0, 0, 1, 0, 0), modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) :ref:`🔗` + +Draws a :ref:`Mesh` in 2D, using the provided texture. See :ref:`MeshInstance2D` for related documentation. The ``transform`` is defined in local space. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_msdf_texture_rect_region: + +.. rst-class:: classref-method + +|void| **draw_msdf_texture_rect_region**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), outline\: :ref:`float` = 0.0, pixel_range\: :ref:`float` = 4.0, scale\: :ref:`float` = 1.0\ ) :ref:`🔗` + +Draws a textured rectangle region of the multichannel signed distance field texture at a given position, optionally modulated by a color. The ``rect`` is defined in local space. See :ref:`FontFile.multichannel_signed_distance_field` for more information and caveats about MSDF font rendering. + +If ``outline`` is positive, each alpha channel value of pixel in region is set to maximum value of true distance in the ``outline`` radius. + +Value of the ``pixel_range`` should the same that was used during distance field texture generation. -Draws a :ref:`Mesh` in 2D, using the provided texture. See :ref:`MeshInstance2D` for related documentation. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_multiline: -- void **draw_multiline** **(** :ref:`PackedVector2Array` points, :ref:`Color` color, :ref:`float` width=1.0 **)** +.. rst-class:: classref-method -Draws multiple, parallel lines with a uniform ``color``. +|void| **draw_multiline**\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws multiple disconnected lines with a uniform ``width`` and ``color``. Each line is defined by two consecutive points from ``points`` array in local space, i.e. i-th segment consists of ``points[2 * i]``, ``points[2 * i + 1]`` endpoints. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line()` calls. To draw interconnected lines, use :ref:`draw_polyline()` instead. + +If ``width`` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +\ **Note:** ``antialiased`` is only effective if ``width`` is greater than ``0.0``. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_multiline_colors: -- void **draw_multiline_colors** **(** :ref:`PackedVector2Array` points, :ref:`PackedColorArray` colors, :ref:`float` width=1.0 **)** +.. rst-class:: classref-method + +|void| **draw_multiline_colors**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws multiple disconnected lines with a uniform ``width`` and segment-by-segment coloring. Each segment is defined by two consecutive points from ``points`` array in local space and a corresponding color from ``colors`` array, i.e. i-th segment consists of ``points[2 * i]``, ``points[2 * i + 1]`` endpoints and has ``colors[i]`` color. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line()` calls. To draw interconnected lines, use :ref:`draw_polyline_colors()` instead. + +If ``width`` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +\ **Note:** ``antialiased`` is only effective if ``width`` is greater than ``0.0``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_multiline_string: + +.. rst-class:: classref-method + +|void| **draw_multiline_string**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` + +Breaks ``text`` into lines and draws it using the specified ``font`` at the ``pos`` in local space (top-left corner). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. -Draws multiple, parallel lines with a uniform ``width`` and segment-by-segment coloring. Colors assigned to line segments match by index between ``points`` and ``colors``. +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_multiline_string_outline: + +.. rst-class:: classref-method + +|void| **draw_multiline_string_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` + +Breaks ``text`` to the lines and draws text outline using the specified ``font`` at the ``pos`` in local space (top-left corner). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_multimesh: -- void **draw_multimesh** **(** :ref:`MultiMesh` multimesh, :ref:`Texture2D` texture, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** +.. rst-class:: classref-method + +|void| **draw_multimesh**\ (\ multimesh\: :ref:`MultiMesh`, texture\: :ref:`Texture2D`\ ) :ref:`🔗` Draws a :ref:`MultiMesh` in 2D with the provided texture. See :ref:`MultiMeshInstance2D` for related documentation. +.. rst-class:: classref-item-separator + ---- .. _class_CanvasItem_method_draw_polygon: -- void **draw_polygon** **(** :ref:`PackedVector2Array` points, :ref:`PackedColorArray` colors, :ref:`PackedVector2Array` uvs=PackedVector2Array( ), :ref:`Texture2D` texture=null, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** +.. rst-class:: classref-method + +|void| **draw_polygon**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) :ref:`🔗` + +Draws a solid polygon of any number of points, convex or concave. Unlike :ref:`draw_colored_polygon()`, each point's color can be changed individually. The ``points`` array is defined in local space. See also :ref:`draw_polyline()` and :ref:`draw_polyline_colors()`. If you need more flexibility (such as being able to use bones), use :ref:`RenderingServer.canvas_item_add_triangle_array()` instead. + +\ **Note:** If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with :ref:`Geometry2D.triangulate_polygon()` and using :ref:`draw_mesh()`, :ref:`draw_multimesh()`, or :ref:`RenderingServer.canvas_item_add_triangle_array()`. -Draws a polygon of any amount of points, convex or concave. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_polyline: -- void **draw_polyline** **(** :ref:`PackedVector2Array` points, :ref:`Color` color, :ref:`float` width=1.0 **)** +.. rst-class:: classref-method + +|void| **draw_polyline**\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws interconnected line segments with a uniform ``color`` and ``width`` and optional antialiasing (supported only for positive ``width``). The ``points`` array is defined in local space. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line()` calls. To draw disconnected lines, use :ref:`draw_multiline()` instead. See also :ref:`draw_polygon()`. + +If ``width`` is negative, it will be ignored and the polyline will be drawn using :ref:`RenderingServer.PRIMITIVE_LINE_STRIP`. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. -Draws interconnected line segments with a uniform ``color`` and ``width``. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_polyline_colors: -- void **draw_polyline_colors** **(** :ref:`PackedVector2Array` points, :ref:`PackedColorArray` colors, :ref:`float` width=1.0 **)** +.. rst-class:: classref-method -Draws interconnected line segments with a uniform ``width`` and segment-by-segment coloring. Colors assigned to line segments match by index between ``points`` and ``colors``. +|void| **draw_polyline_colors**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws interconnected line segments with a uniform ``width``, point-by-point coloring, and optional antialiasing (supported only for positive ``width``). Colors assigned to line points match by index between ``points`` and ``colors``, i.e. each line segment is filled with a gradient between the colors of the endpoints. The ``points`` array is defined in local space. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line()` calls. To draw disconnected lines, use :ref:`draw_multiline_colors()` instead. See also :ref:`draw_polygon()`. + +If ``width`` is negative, it will be ignored and the polyline will be drawn using :ref:`RenderingServer.PRIMITIVE_LINE_STRIP`. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_primitive: -- void **draw_primitive** **(** :ref:`PackedVector2Array` points, :ref:`PackedColorArray` colors, :ref:`PackedVector2Array` uvs, :ref:`Texture2D` texture=null, :ref:`float` width=1.0, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** +.. rst-class:: classref-method + +|void| **draw_primitive**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array`, texture\: :ref:`Texture2D` = null\ ) :ref:`🔗` -Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for a triangle, and 4 points for a quad. +Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for a triangle, and 4 points for a quad. If 0 points or more than 4 points are specified, nothing will be drawn and an error message will be printed. The ``points`` array is defined in local space. See also :ref:`draw_line()`, :ref:`draw_polyline()`, :ref:`draw_polygon()`, and :ref:`draw_rect()`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_rect: -- void **draw_rect** **(** :ref:`Rect2` rect, :ref:`Color` color, :ref:`bool` filled=true, :ref:`float` width=1.0 **)** +.. rst-class:: classref-method + +|void| **draw_rect**\ (\ rect\: :ref:`Rect2`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws a rectangle. If ``filled`` is ``true``, the rectangle will be filled with the ``color`` specified. If ``filled`` is ``false``, the rectangle will be drawn as a stroke with the ``color`` and ``width`` specified. The ``rect`` is specified in local space. See also :ref:`draw_texture_rect()`. + +If ``width`` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. -Draws a rectangle. If ``filled`` is ``true``, the rectangle will be filled with the ``color`` specified. If ``filled`` is ``false``, the rectangle will be drawn as a stroke with the ``color`` and ``width`` specified. +If ``antialiased`` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. -**Note:** ``width`` is only effective if ``filled`` is ``false``. +\ **Note:** ``width`` is only effective if ``filled`` is ``false``. + +\ **Note:** Unfilled rectangles drawn with a negative ``width`` may not display perfectly. For example, corners may be missing or brighter due to overlapping lines (for a translucent ``color``). + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_set_transform: -- void **draw_set_transform** **(** :ref:`Vector2` position, :ref:`float` rotation, :ref:`Vector2` scale **)** +.. rst-class:: classref-method + +|void| **draw_set_transform**\ (\ position\: :ref:`Vector2`, rotation\: :ref:`float` = 0.0, scale\: :ref:`Vector2` = Vector2(1, 1)\ ) :ref:`🔗` + +Sets a custom local transform for drawing via components. Anything drawn afterwards will be transformed by this. -Sets a custom transform for drawing via components. Anything drawn afterwards will be transformed by this. +\ **Note:** :ref:`FontFile.oversampling` does *not* take ``scale`` into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling :ref:`ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field` (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, :ref:`SystemFont.multichannel_signed_distance_field` can be enabled in the inspector. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_set_transform_matrix: -- void **draw_set_transform_matrix** **(** :ref:`Transform2D` xform **)** +.. rst-class:: classref-method + +|void| **draw_set_transform_matrix**\ (\ xform\: :ref:`Transform2D`\ ) :ref:`🔗` + +Sets a custom local transform for drawing via matrix. Anything drawn afterwards will be transformed by this. -Sets a custom transform for drawing via matrix. Anything drawn afterwards will be transformed by this. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_string: -- void **draw_string** **(** :ref:`Font` font, :ref:`Vector2` position, :ref:`String` text, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`int` clip_w=-1 **)** +.. rst-class:: classref-method -Draws a string using a custom font. +|void| **draw_string**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` + +Draws ``text`` using the specified ``font`` at the ``pos`` in local space (bottom-left corner using the baseline of the font). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. + +\ **Example:** Draw "Hello world", using the project's default font: + + +.. tabs:: + + .. code-tab:: gdscript + + # If using this method in a script that redraws constantly, move the + # `default_font` declaration to a member variable assigned in `_ready()` + # so the Control is only created once. + var default_font = ThemeDB.fallback_font + var default_font_size = ThemeDB.fallback_font_size + draw_string(default_font, Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, default_font_size) + + .. code-tab:: csharp + + // If using this method in a script that redraws constantly, move the + // `default_font` declaration to a member variable assigned in `_Ready()` + // so the Control is only created once. + Font defaultFont = ThemeDB.FallbackFont; + int defaultFontSize = ThemeDB.FallbackFontSize; + DrawString(defaultFont, new Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, defaultFontSize); + + + +See also :ref:`Font.draw_string()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_draw_string_outline: + +.. rst-class:: classref-method + +|void| **draw_string_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` + +Draws ``text`` outline using the specified ``font`` at the ``pos`` in local space (bottom-left corner using the baseline of the font). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_style_box: -- void **draw_style_box** **(** :ref:`StyleBox` style_box, :ref:`Rect2` rect **)** +.. rst-class:: classref-method + +|void| **draw_style_box**\ (\ style_box\: :ref:`StyleBox`, rect\: :ref:`Rect2`\ ) :ref:`🔗` -Draws a styled rectangle. +Draws a styled rectangle. The ``rect`` is defined in local space. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_texture: -- void **draw_texture** **(** :ref:`Texture2D` texture, :ref:`Vector2` position, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** +.. rst-class:: classref-method + +|void| **draw_texture**\ (\ texture\: :ref:`Texture2D`, position\: :ref:`Vector2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) :ref:`🔗` -Draws a texture at a given position. +Draws a texture at a given position. The ``position`` is defined in local space. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_texture_rect: -- void **draw_texture_rect** **(** :ref:`Texture2D` texture, :ref:`Rect2` rect, :ref:`bool` tile, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`bool` transpose=false, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** +.. rst-class:: classref-method + +|void| **draw_texture_rect**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, tile\: :ref:`bool`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false\ ) :ref:`🔗` -Draws a textured rectangle at a given position, optionally modulated by a color. If ``transpose`` is ``true``, the texture will have its X and Y coordinates swapped. +Draws a textured rectangle at a given position, optionally modulated by a color. The ``rect`` is defined in local space. If ``transpose`` is ``true``, the texture will have its X and Y coordinates swapped. See also :ref:`draw_rect()` and :ref:`draw_texture_rect_region()`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_draw_texture_rect_region: -- void **draw_texture_rect_region** **(** :ref:`Texture2D` texture, :ref:`Rect2` rect, :ref:`Rect2` src_rect, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`bool` transpose=false, :ref:`Texture2D` normal_map=null, :ref:`Texture2D` specular_map=null, :ref:`Color` specular_shininess=Color( 1, 1, 1, 1 ), :ref:`bool` clip_uv=true, :ref:`TextureFilter` texture_filter=0, :ref:`TextureRepeat` texture_repeat=0 **)** +.. rst-class:: classref-method + +|void| **draw_texture_rect_region**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false, clip_uv\: :ref:`bool` = true\ ) :ref:`🔗` -Draws a textured rectangle region at a given position, optionally modulated by a color. If ``transpose`` is ``true``, the texture will have its X and Y coordinates swapped. +Draws a textured rectangle from a texture's region (specified by ``src_rect``) at a given position in local space, optionally modulated by a color. If ``transpose`` is ``true``, the texture will have its X and Y coordinates swapped. See also :ref:`draw_texture_rect()`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_force_update_transform: -- void **force_update_transform** **(** **)** +.. rst-class:: classref-method + +|void| **force_update_transform**\ (\ ) :ref:`🔗` + +Forces the node's transform to update. Fails if the node is not inside the tree. See also :ref:`get_transform()`. -Forces the transform to update. Transform changes in physics are not instant for performance reasons. Transforms are accumulated and then set. Use this if you need an up-to-date transform when doing physics operations. +\ **Note:** For performance reasons, transform changes are usually accumulated and applied *once* at the end of the frame. The update propagates through **CanvasItem** children, as well. Therefore, use this method only when you need an up-to-date transform (such as during physics operations). + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_canvas: -- :ref:`RID` **get_canvas** **(** **)** const +.. rst-class:: classref-method + +:ref:`RID` **get_canvas**\ (\ ) |const| :ref:`🔗` -Returns the :ref:`RID` of the :ref:`World2D` canvas where this item is in. +Returns the :ref:`RID` of the :ref:`World2D` canvas where this node is registered to, used by the :ref:`RenderingServer`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_canvas_item: -- :ref:`RID` **get_canvas_item** **(** **)** const +.. rst-class:: classref-method + +:ref:`RID` **get_canvas_item**\ (\ ) |const| :ref:`🔗` -Returns the canvas item RID used by :ref:`VisualServer` for this item. +Returns the internal canvas item :ref:`RID` used by the :ref:`RenderingServer` for this node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_get_canvas_layer_node: + +.. rst-class:: classref-method + +:ref:`CanvasLayer` **get_canvas_layer_node**\ (\ ) |const| :ref:`🔗` + +Returns the :ref:`CanvasLayer` that contains this node, or ``null`` if the node is not in any :ref:`CanvasLayer`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_canvas_transform: -- :ref:`Transform2D` **get_canvas_transform** **(** **)** const +.. rst-class:: classref-method -Returns the transform matrix of this item's canvas. +:ref:`Transform2D` **get_canvas_transform**\ (\ ) |const| :ref:`🔗` + +Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport's coordinate system. See also :ref:`Node.get_viewport()`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_global_mouse_position: -- :ref:`Vector2` **get_global_mouse_position** **(** **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **get_global_mouse_position**\ (\ ) |const| :ref:`🔗` -Returns the global position of the mouse. +Returns mouse cursor's global position relative to the :ref:`CanvasLayer` that contains this node. + +\ **Note:** For screen-space coordinates (e.g. when using a non-embedded :ref:`Popup`), you can use :ref:`DisplayServer.mouse_get_position()`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_global_transform: -- :ref:`Transform2D` **get_global_transform** **(** **)** const +.. rst-class:: classref-method + +:ref:`Transform2D` **get_global_transform**\ (\ ) |const| :ref:`🔗` + +Returns the global transform matrix of this item, i.e. the combined transform up to the topmost **CanvasItem** node. The topmost item is a **CanvasItem** that either has no parent, has non-**CanvasItem** parent or it has :ref:`top_level` enabled. -Returns the global transform matrix of this item. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_global_transform_with_canvas: -- :ref:`Transform2D` **get_global_transform_with_canvas** **(** **)** const +.. rst-class:: classref-method -Returns the global transform matrix of this item in relation to the canvas. +:ref:`Transform2D` **get_global_transform_with_canvas**\ (\ ) |const| :ref:`🔗` + +Returns the transform from the local coordinate system of this **CanvasItem** to the :ref:`Viewport`\ s coordinate system. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_get_instance_shader_parameter: + +.. rst-class:: classref-method + +:ref:`Variant` **get_instance_shader_parameter**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Get the value of a shader parameter as set on this instance. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_local_mouse_position: -- :ref:`Vector2` **get_local_mouse_position** **(** **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **get_local_mouse_position**\ (\ ) |const| :ref:`🔗` + +Returns the mouse's position in this **CanvasItem** using the local coordinate system of this **CanvasItem**. -Returns the mouse position relative to this item's position. +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_get_screen_transform: + +.. rst-class:: classref-method + +:ref:`Transform2D` **get_screen_transform**\ (\ ) |const| :ref:`🔗` + +Returns the transform of this **CanvasItem** in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins. + +Equals to :ref:`get_global_transform()` if the window is embedded (see :ref:`Viewport.gui_embed_subwindows`). + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_transform: -- :ref:`Transform2D` **get_transform** **(** **)** const +.. rst-class:: classref-method + +:ref:`Transform2D` **get_transform**\ (\ ) |const| :ref:`🔗` -Returns the transform matrix of this item. +Returns the transform matrix of this **CanvasItem**. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_viewport_rect: -- :ref:`Rect2` **get_viewport_rect** **(** **)** const +.. rst-class:: classref-method + +:ref:`Rect2` **get_viewport_rect**\ (\ ) |const| :ref:`🔗` -Returns the viewport's boundaries as a :ref:`Rect2`. +Returns this node's viewport boundaries as a :ref:`Rect2`. See also :ref:`Node.get_viewport()`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_get_viewport_transform: -- :ref:`Transform2D` **get_viewport_transform** **(** **)** const +.. rst-class:: classref-method + +:ref:`Transform2D` **get_viewport_transform**\ (\ ) |const| :ref:`🔗` + +Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport embedder's coordinate system. See also :ref:`Viewport.get_final_transform()` and :ref:`Node.get_viewport()`. -Returns this item's transform in relation to the viewport. +.. rst-class:: classref-item-separator ---- -.. _class_CanvasItem_method_get_world_2d: +.. _class_CanvasItem_method_get_visibility_layer_bit: + +.. rst-class:: classref-method -- :ref:`World2D` **get_world_2d** **(** **)** const +:ref:`bool` **get_visibility_layer_bit**\ (\ layer\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the :ref:`World2D` where this item is in. +Returns ``true`` if the layer at the given index is set in :ref:`visibility_layer`. + +.. rst-class:: classref-item-separator ---- -.. _class_CanvasItem_method_hide: +.. _class_CanvasItem_method_get_world_2d: + +.. rst-class:: classref-method + +:ref:`World2D` **get_world_2d**\ (\ ) |const| :ref:`🔗` + +Returns the :ref:`World2D` this node is registered to. -- void **hide** **(** **)** +Usually, this is the same as this node's viewport (see :ref:`Node.get_viewport()` and :ref:`Viewport.find_world_2d()`). -Hide the ``CanvasItem`` if it's currently visible. +.. rst-class:: classref-item-separator ---- -.. _class_CanvasItem_method_is_local_transform_notification_enabled: +.. _class_CanvasItem_method_hide: + +.. rst-class:: classref-method + +|void| **hide**\ (\ ) :ref:`🔗` -- :ref:`bool` **is_local_transform_notification_enabled** **(** **)** const +Hide the **CanvasItem** if it's currently visible. This is equivalent to setting :ref:`visible` to ``false``. -Returns ``true`` if local transform notifications are communicated to children. +.. rst-class:: classref-item-separator ---- -.. _class_CanvasItem_method_is_set_as_toplevel: +.. _class_CanvasItem_method_is_local_transform_notification_enabled: + +.. rst-class:: classref-method + +:ref:`bool` **is_local_transform_notification_enabled**\ (\ ) |const| :ref:`🔗` -- :ref:`bool` **is_set_as_toplevel** **(** **)** const +Returns ``true`` if the node receives :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED` whenever its local transform changes. This is enabled with :ref:`set_notify_local_transform()`. -Returns ``true`` if the node is set as top-level. See :ref:`set_as_toplevel`. +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_is_transform_notification_enabled: -- :ref:`bool` **is_transform_notification_enabled** **(** **)** const +.. rst-class:: classref-method -Returns ``true`` if global transform notifications are communicated to children. +:ref:`bool` **is_transform_notification_enabled**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the node receives :ref:`NOTIFICATION_TRANSFORM_CHANGED` whenever its global transform changes. This is enabled with :ref:`set_notify_transform()`. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_is_visible_in_tree: -- :ref:`bool` **is_visible_in_tree** **(** **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_visible_in_tree**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the node is present in the :ref:`SceneTree`, its :ref:`visible` property is ``true`` and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see :ref:`_draw()`). -Returns ``true`` if the node is present in the :ref:`SceneTree`, its :ref:`visible` property is ``true`` and its inherited visibility is also ``true``. +Visibility is checked only in parent nodes that inherit from **CanvasItem**, :ref:`CanvasLayer`, and :ref:`Window`. If the parent is of any other type (such as :ref:`Node`, :ref:`AnimationPlayer`, or :ref:`Node3D`), it is assumed to be visible. + +\ **Note:** This method does not take :ref:`visibility_layer` into account, so even if this method returns ``true``, the node might end up not being rendered. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_make_canvas_position_local: -- :ref:`Vector2` **make_canvas_position_local** **(** :ref:`Vector2` screen_point **)** const +.. rst-class:: classref-method + +:ref:`Vector2` **make_canvas_position_local**\ (\ viewport_point\: :ref:`Vector2`\ ) |const| :ref:`🔗` -Assigns ``screen_point`` as this node's new local transform. +Transforms ``viewport_point`` from the viewport's coordinates to this node's local coordinates. + +For the opposite operation, use :ref:`get_global_transform_with_canvas()`. + +:: + + var viewport_point = get_global_transform_with_canvas() * local_point + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_make_input_local: -- :ref:`InputEvent` **make_input_local** **(** :ref:`InputEvent` event **)** const +.. rst-class:: classref-method + +:ref:`InputEvent` **make_input_local**\ (\ event\: :ref:`InputEvent`\ ) |const| :ref:`🔗` + +Returns a copy of the given ``event`` with its coordinates converted from global space to this **CanvasItem**'s local space. If not possible, returns the same :ref:`InputEvent` unchanged. + +.. rst-class:: classref-item-separator -Transformations issued by ``event``'s inputs are applied in local space instead of global space. +---- + +.. _class_CanvasItem_method_move_to_front: + +.. rst-class:: classref-method + +|void| **move_to_front**\ (\ ) :ref:`🔗` + +Moves this node below its siblings, usually causing the node to draw on top of its siblings. Does nothing if this node does not have a parent. See also :ref:`Node.move_child()`. + +.. rst-class:: classref-item-separator ---- -.. _class_CanvasItem_method_set_as_toplevel: +.. _class_CanvasItem_method_queue_redraw: + +.. rst-class:: classref-method + +|void| **queue_redraw**\ (\ ) :ref:`🔗` -- void **set_as_toplevel** **(** :ref:`bool` enable **)** +Queues the **CanvasItem** to redraw. During idle time, if **CanvasItem** is visible, :ref:`NOTIFICATION_DRAW` is sent and :ref:`_draw()` is called. This only occurs **once** per frame, even if this method has been called multiple times. -If ``enable`` is ``true``, the node won't inherit its transform from parent canvas items. +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_set_instance_shader_parameter: + +.. rst-class:: classref-method + +|void| **set_instance_shader_parameter**\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) :ref:`🔗` + +Set the value of a shader uniform for this instance only (`per-instance uniform <../tutorials/shaders/shader_reference/shading_language.html#per-instance-uniforms>`__). See also :ref:`ShaderMaterial.set_shader_parameter()` to assign a uniform on all instances using the same :ref:`ShaderMaterial`. + +\ **Note:** For a shader uniform to be assignable on a per-instance basis, it *must* be defined with ``instance uniform ...`` rather than ``uniform ...`` in the shader code. + +\ **Note:** ``name`` is case-sensitive and must match the name of the uniform in the code exactly (not the capitalized name in the inspector). + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_set_notify_local_transform: -- void **set_notify_local_transform** **(** :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_notify_local_transform**\ (\ enable\: :ref:`bool`\ ) :ref:`🔗` + +If ``true``, the node will receive :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED` whenever its local transform changes. -If ``enable`` is ``true``, children will be updated with local transform data. +\ **Note:** Many canvas items such as :ref:`Bone2D` or :ref:`CollisionShape2D` automatically enable this in order to function correctly. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItem_method_set_notify_transform: -- void **set_notify_transform** **(** :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **set_notify_transform**\ (\ enable\: :ref:`bool`\ ) :ref:`🔗` + +If ``true``, the node will receive :ref:`NOTIFICATION_TRANSFORM_CHANGED` whenever global transform changes. -If ``enable`` is ``true``, children will be updated with global transform data. +\ **Note:** Many canvas items such as :ref:`Camera2D` or :ref:`Light2D` automatically enable this in order to function correctly. + +.. rst-class:: classref-item-separator ---- -.. _class_CanvasItem_method_show: +.. _class_CanvasItem_method_set_visibility_layer_bit: + +.. rst-class:: classref-method + +|void| **set_visibility_layer_bit**\ (\ layer\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` -- void **show** **(** **)** +Set/clear individual bits on the rendering visibility layer. This simplifies editing this **CanvasItem**'s visibility layer. -Show the ``CanvasItem`` if it's currently hidden. For controls that inherit :ref:`Popup`, the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. +.. rst-class:: classref-item-separator ---- -.. _class_CanvasItem_method_update: +.. _class_CanvasItem_method_show: + +.. rst-class:: classref-method + +|void| **show**\ (\ ) :ref:`🔗` -- void **update** **(** **)** +Show the **CanvasItem** if it's currently hidden. This is equivalent to setting :ref:`visible` to ``true``. -Queue the ``CanvasItem`` for update. :ref:`NOTIFICATION_DRAW` will be called on idle time to request redraw. +\ **Note:** For controls that inherit :ref:`Popup`, the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_canvasitemmaterial.rst b/classes/class_canvasitemmaterial.rst index 293007af08e..39d8b0a79bf 100644 --- a/classes/class_canvasitemmaterial.rst +++ b/classes/class_canvasitemmaterial.rst @@ -1,181 +1,258 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CanvasItemMaterial.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CanvasItemMaterial.xml. .. _class_CanvasItemMaterial: CanvasItemMaterial ================== -**Inherits:** :ref:`Material` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Material` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` A material for :ref:`CanvasItem`\ s. +.. rst-class:: classref-introduction-group + Description ----------- -``CanvasItemMaterial``\ s provide a means of modifying the textures associated with a CanvasItem. They specialize in describing blend and lighting behaviors for textures. Use a :ref:`ShaderMaterial` to more fully customize a material's interactions with a :ref:`CanvasItem`. +**CanvasItemMaterial**\ s provide a means of modifying the textures associated with a CanvasItem. They specialize in describing blend and lighting behaviors for textures. Use a :ref:`ShaderMaterial` to more fully customize a material's interactions with a :ref:`CanvasItem`. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`BlendMode` | :ref:`blend_mode` | ``0`` | -+-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`LightMode` | :ref:`light_mode` | ``0`` | -+-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`int` | :ref:`particles_anim_h_frames` | | -+-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`particles_anim_loop` | | -+-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`int` | :ref:`particles_anim_v_frames` | | -+-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`particles_animation` | ``false`` | -+-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ +.. table:: + :widths: auto + + +-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ + | :ref:`BlendMode` | :ref:`blend_mode` | ``0`` | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ + | :ref:`LightMode` | :ref:`light_mode` | ``0`` | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`particles_anim_h_frames` | | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`particles_anim_loop` | | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`particles_anim_v_frames` | | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`particles_animation` | ``false`` | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_CanvasItemMaterial_BlendMode: +.. rst-class:: classref-enumeration + +enum **BlendMode**: :ref:`🔗` + .. _class_CanvasItemMaterial_constant_BLEND_MODE_MIX: +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_MIX** = ``0`` + +Mix blending mode. Colors are assumed to be independent of the alpha (opacity) value. + .. _class_CanvasItemMaterial_constant_BLEND_MODE_ADD: +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_ADD** = ``1`` + +Additive blending mode. + .. _class_CanvasItemMaterial_constant_BLEND_MODE_SUB: +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_SUB** = ``2`` + +Subtractive blending mode. + .. _class_CanvasItemMaterial_constant_BLEND_MODE_MUL: -.. _class_CanvasItemMaterial_constant_BLEND_MODE_PREMULT_ALPHA: +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_MUL** = ``3`` -enum **BlendMode**: +Multiplicative blending mode. -- **BLEND_MODE_MIX** = **0** --- Mix blending mode. Colors are assumed to be independent of the alpha (opacity) value. +.. _class_CanvasItemMaterial_constant_BLEND_MODE_PREMULT_ALPHA: -- **BLEND_MODE_ADD** = **1** --- Additive blending mode. +.. rst-class:: classref-enumeration-constant -- **BLEND_MODE_SUB** = **2** --- Subtractive blending mode. +:ref:`BlendMode` **BLEND_MODE_PREMULT_ALPHA** = ``4`` -- **BLEND_MODE_MUL** = **3** --- Multiplicative blending mode. +Mix blending mode. Colors are assumed to be premultiplied by the alpha (opacity) value. -- **BLEND_MODE_PREMULT_ALPHA** = **4** --- Mix blending mode. Colors are assumed to be premultiplied by the alpha (opacity) value. +.. rst-class:: classref-item-separator ---- .. _enum_CanvasItemMaterial_LightMode: +.. rst-class:: classref-enumeration + +enum **LightMode**: :ref:`🔗` + .. _class_CanvasItemMaterial_constant_LIGHT_MODE_NORMAL: +.. rst-class:: classref-enumeration-constant + +:ref:`LightMode` **LIGHT_MODE_NORMAL** = ``0`` + +Render the material using both light and non-light sensitive material properties. + .. _class_CanvasItemMaterial_constant_LIGHT_MODE_UNSHADED: +.. rst-class:: classref-enumeration-constant + +:ref:`LightMode` **LIGHT_MODE_UNSHADED** = ``1`` + +Render the material as if there were no light. + .. _class_CanvasItemMaterial_constant_LIGHT_MODE_LIGHT_ONLY: -enum **LightMode**: +.. rst-class:: classref-enumeration-constant -- **LIGHT_MODE_NORMAL** = **0** --- Render the material using both light and non-light sensitive material properties. +:ref:`LightMode` **LIGHT_MODE_LIGHT_ONLY** = ``2`` -- **LIGHT_MODE_UNSHADED** = **1** --- Render the material as if there were no light. +Render the material as if there were only light. + +.. rst-class:: classref-section-separator + +---- -- **LIGHT_MODE_LIGHT_ONLY** = **2** --- Render the material as if there were only light. +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_CanvasItemMaterial_property_blend_mode: -- :ref:`BlendMode` **blend_mode** +.. rst-class:: classref-property -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_blend_mode(value) | -+-----------+-----------------------+ -| *Getter* | get_blend_mode() | -+-----------+-----------------------+ +:ref:`BlendMode` **blend_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_blend_mode**\ (\ value\: :ref:`BlendMode`\ ) +- :ref:`BlendMode` **get_blend_mode**\ (\ ) The manner in which a material's rendering is applied to underlying textures. +.. rst-class:: classref-item-separator + ---- .. _class_CanvasItemMaterial_property_light_mode: -- :ref:`LightMode` **light_mode** +.. rst-class:: classref-property -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_light_mode(value) | -+-----------+-----------------------+ -| *Getter* | get_light_mode() | -+-----------+-----------------------+ +:ref:`LightMode` **light_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_light_mode**\ (\ value\: :ref:`LightMode`\ ) +- :ref:`LightMode` **get_light_mode**\ (\ ) The manner in which material reacts to lighting. +.. rst-class:: classref-item-separator + ---- .. _class_CanvasItemMaterial_property_particles_anim_h_frames: -- :ref:`int` **particles_anim_h_frames** +.. rst-class:: classref-property -+----------+------------------------------------+ -| *Setter* | set_particles_anim_h_frames(value) | -+----------+------------------------------------+ -| *Getter* | get_particles_anim_h_frames() | -+----------+------------------------------------+ +:ref:`int` **particles_anim_h_frames** :ref:`🔗` -The number of columns in the spritesheet assigned as :ref:`Texture2D` for a :ref:`Particles2D` or :ref:`CPUParticles2D`. +.. rst-class:: classref-property-setget -**Note:** This property is only used and visible in the editor if :ref:`particles_animation` is ``true``. +- |void| **set_particles_anim_h_frames**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_particles_anim_h_frames**\ (\ ) + +The number of columns in the spritesheet assigned as :ref:`Texture2D` for a :ref:`GPUParticles2D` or :ref:`CPUParticles2D`. + +\ **Note:** This property is only used and visible in the editor if :ref:`particles_animation` is ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItemMaterial_property_particles_anim_loop: -- :ref:`bool` **particles_anim_loop** +.. rst-class:: classref-property -+----------+--------------------------------+ -| *Setter* | set_particles_anim_loop(value) | -+----------+--------------------------------+ -| *Getter* | get_particles_anim_loop() | -+----------+--------------------------------+ +:ref:`bool` **particles_anim_loop** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_particles_anim_loop**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_particles_anim_loop**\ (\ ) If ``true``, the particles animation will loop. -**Note:** This property is only used and visible in the editor if :ref:`particles_animation` is ``true``. +\ **Note:** This property is only used and visible in the editor if :ref:`particles_animation` is ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItemMaterial_property_particles_anim_v_frames: -- :ref:`int` **particles_anim_v_frames** +.. rst-class:: classref-property -+----------+------------------------------------+ -| *Setter* | set_particles_anim_v_frames(value) | -+----------+------------------------------------+ -| *Getter* | get_particles_anim_v_frames() | -+----------+------------------------------------+ +:ref:`int` **particles_anim_v_frames** :ref:`🔗` -The number of rows in the spritesheet assigned as :ref:`Texture2D` for a :ref:`Particles2D` or :ref:`CPUParticles2D`. +.. rst-class:: classref-property-setget -**Note:** This property is only used and visible in the editor if :ref:`particles_animation` is ``true``. +- |void| **set_particles_anim_v_frames**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_particles_anim_v_frames**\ (\ ) + +The number of rows in the spritesheet assigned as :ref:`Texture2D` for a :ref:`GPUParticles2D` or :ref:`CPUParticles2D`. + +\ **Note:** This property is only used and visible in the editor if :ref:`particles_animation` is ``true``. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasItemMaterial_property_particles_animation: -- :ref:`bool` **particles_animation** +.. rst-class:: classref-property + +:ref:`bool` **particles_animation** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+--------------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------------+ -| *Setter* | set_particles_animation(value) | -+-----------+--------------------------------+ -| *Getter* | get_particles_animation() | -+-----------+--------------------------------+ +- |void| **set_particles_animation**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_particles_animation**\ (\ ) -If ``true``, enable spritesheet-based animation features when assigned to :ref:`Particles2D` and :ref:`CPUParticles2D` nodes. The :ref:`ParticlesMaterial.anim_speed` or :ref:`CPUParticles2D.anim_speed` should also be set to a positive value for the animation to play. +If ``true``, enable spritesheet-based animation features when assigned to :ref:`GPUParticles2D` and :ref:`CPUParticles2D` nodes. The :ref:`ParticleProcessMaterial.anim_speed_max` or :ref:`CPUParticles2D.anim_speed_max` should also be set to a positive value for the animation to play. This property (and other ``particles_anim_*`` properties that depend on it) has no effect on other types of nodes. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_canvaslayer.rst b/classes/class_canvaslayer.rst index fff1109e3f5..81144a77d62 100644 --- a/classes/class_canvaslayer.rst +++ b/classes/class_canvaslayer.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CanvasLayer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CanvasLayer.xml. .. _class_CanvasLayer: @@ -13,199 +14,320 @@ CanvasLayer **Inherited By:** :ref:`ParallaxBackground` -Canvas drawing layer. +A node used for independent rendering of objects within a 2D scene. + +.. rst-class:: classref-introduction-group Description ----------- -Canvas drawing layer. :ref:`CanvasItem` nodes that are direct or indirect children of a ``CanvasLayer`` will be drawn in that layer. The layer is a numeric index that defines the draw order. The default 2D scene renders with index 0, so a ``CanvasLayer`` with index -1 will be drawn below, and one with index 1 will be drawn above. This is very useful for HUDs (in layer 1+ or above), or backgrounds (in layer -1 or below). +:ref:`CanvasItem`-derived nodes that are direct or indirect children of a **CanvasLayer** will be drawn in that layer. The layer is a numeric index that defines the draw order. The default 2D scene renders with index ``0``, so a **CanvasLayer** with index ``-1`` will be drawn below, and a **CanvasLayer** with index ``1`` will be drawn above. This order will hold regardless of the :ref:`CanvasItem.z_index` of the nodes within each layer. + +\ **CanvasLayer**\ s can be hidden and they can also optionally follow the viewport. This makes them useful for HUDs like health bar overlays (on layers ``1`` and higher) or backgrounds (on layers ``-1`` and lower). + +\ **Note:** Embedded :ref:`Window`\ s are placed on layer ``1024``. :ref:`CanvasItem`\ s on layers ``1025`` and higher appear in front of embedded windows. + +\ **Note:** Each **CanvasLayer** is drawn on one specific :ref:`Viewport` and cannot be shared between multiple :ref:`Viewport`\ s, see :ref:`custom_viewport`. When using multiple :ref:`Viewport`\ s, for example in a split-screen game, you need to create an individual **CanvasLayer** for each :ref:`Viewport` you want it to be drawn on. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/2d/2d_transforms` +- :doc:`Viewport and canvas transforms <../tutorials/2d/2d_transforms>` + +- :doc:`Canvas layers <../tutorials/2d/canvas_layers>` -- :doc:`../tutorials/2d/canvas_layers` +- `2D Dodge The Creeps Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`Node` | :ref:`custom_viewport` | | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`bool` | :ref:`follow_viewport_enable` | ``false`` | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`float` | :ref:`follow_viewport_scale` | ``1.0`` | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`int` | :ref:`layer` | ``1`` | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`Vector2` | :ref:`offset` | ``Vector2( 0, 0 )`` | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`float` | :ref:`rotation` | ``0.0`` | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`float` | :ref:`rotation_degrees` | ``0.0`` | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`Vector2` | :ref:`scale` | ``Vector2( 1, 1 )`` | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ -| :ref:`Transform2D` | :ref:`transform` | ``Transform2D( 1, 0, 0, 1, 0, 0 )`` | -+---------------------------------------+----------------------------------------------------------------------------------+-------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Node` | :ref:`custom_viewport` | | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`bool` | :ref:`follow_viewport_enabled` | ``false`` | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`float` | :ref:`follow_viewport_scale` | ``1.0`` | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`int` | :ref:`layer` | ``1`` | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Vector2` | :ref:`offset` | ``Vector2(0, 0)`` | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`float` | :ref:`rotation` | ``0.0`` | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Vector2` | :ref:`scale` | ``Vector2(1, 1)`` | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Transform2D` | :ref:`transform` | ``Transform2D(1, 0, 0, 1, 0, 0)`` | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`bool` | :ref:`visible` | ``true`` | + +---------------------------------------+------------------------------------------------------------------------------------+-----------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------+--------------------------------------------------------------------------+ -| :ref:`RID` | :ref:`get_canvas` **(** **)** const | -+-----------------------+--------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_canvas`\ (\ ) |const| | + +---------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_final_transform`\ (\ ) |const| | + +---------------------------------------+----------------------------------------------------------------------------------------+ + | |void| | :ref:`hide`\ (\ ) | + +---------------------------------------+----------------------------------------------------------------------------------------+ + | |void| | :ref:`show`\ (\ ) | + +---------------------------------------+----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_CanvasLayer_signal_visibility_changed: + +.. rst-class:: classref-signal + +**visibility_changed**\ (\ ) :ref:`🔗` + +Emitted when visibility of the layer is changed. See :ref:`visible`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_CanvasLayer_property_custom_viewport: -- :ref:`Node` **custom_viewport** +.. rst-class:: classref-property -+----------+----------------------------+ -| *Setter* | set_custom_viewport(value) | -+----------+----------------------------+ -| *Getter* | get_custom_viewport() | -+----------+----------------------------+ +:ref:`Node` **custom_viewport** :ref:`🔗` -The custom :ref:`Viewport` node assigned to the ``CanvasLayer``. If ``null``, uses the default viewport instead. +.. rst-class:: classref-property-setget + +- |void| **set_custom_viewport**\ (\ value\: :ref:`Node`\ ) +- :ref:`Node` **get_custom_viewport**\ (\ ) + +The custom :ref:`Viewport` node assigned to the **CanvasLayer**. If ``null``, uses the default viewport instead. + +.. rst-class:: classref-item-separator ---- -.. _class_CanvasLayer_property_follow_viewport_enable: +.. _class_CanvasLayer_property_follow_viewport_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **follow_viewport_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`bool` **follow_viewport_enable** +- |void| **set_follow_viewport**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_following_viewport**\ (\ ) -+-----------+----------------------------+ -| *Default* | ``false`` | -+-----------+----------------------------+ -| *Setter* | set_follow_viewport(value) | -+-----------+----------------------------+ -| *Getter* | is_following_viewport() | -+-----------+----------------------------+ +If enabled, the **CanvasLayer** maintains its position in world space. If disabled, the **CanvasLayer** stays in a fixed position on the screen. -Sets the layer to follow the viewport in order to simulate a pseudo 3D effect. +Together with :ref:`follow_viewport_scale`, this can be used for a pseudo-3D effect. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasLayer_property_follow_viewport_scale: -- :ref:`float` **follow_viewport_scale** +.. rst-class:: classref-property + +:ref:`float` **follow_viewport_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------------------+ -| *Default* | ``1.0`` | -+-----------+----------------------------------+ -| *Setter* | set_follow_viewport_scale(value) | -+-----------+----------------------------------+ -| *Getter* | get_follow_viewport_scale() | -+-----------+----------------------------------+ +- |void| **set_follow_viewport_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_follow_viewport_scale**\ (\ ) -Scales the layer when using :ref:`follow_viewport_enable`. Layers moving into the foreground should have increasing scales, while layers moving into the background should have decreasing scales. +Scales the layer when using :ref:`follow_viewport_enabled`. Layers moving into the foreground should have increasing scales, while layers moving into the background should have decreasing scales. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasLayer_property_layer: -- :ref:`int` **layer** +.. rst-class:: classref-property + +:ref:`int` **layer** = ``1`` :ref:`🔗` -+-----------+------------------+ -| *Default* | ``1`` | -+-----------+------------------+ -| *Setter* | set_layer(value) | -+-----------+------------------+ -| *Getter* | get_layer() | -+-----------+------------------+ +.. rst-class:: classref-property-setget -Layer index for draw order. Lower values are drawn first. +- |void| **set_layer**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_layer**\ (\ ) + +Layer index for draw order. Lower values are drawn behind higher values. + +\ **Note:** If multiple CanvasLayers have the same layer index, :ref:`CanvasItem` children of one CanvasLayer are drawn behind the :ref:`CanvasItem` children of the other CanvasLayer. Which CanvasLayer is drawn in front is non-deterministic. + +\ **Note:** The layer index should be between :ref:`RenderingServer.CANVAS_LAYER_MIN` and :ref:`RenderingServer.CANVAS_LAYER_MAX` (inclusive). Any other value will wrap around. + +.. rst-class:: classref-item-separator ---- .. _class_CanvasLayer_property_offset: -- :ref:`Vector2` **offset** +.. rst-class:: classref-property + +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` -+-----------+---------------------+ -| *Default* | ``Vector2( 0, 0 )`` | -+-----------+---------------------+ -| *Setter* | set_offset(value) | -+-----------+---------------------+ -| *Getter* | get_offset() | -+-----------+---------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_offset**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_offset**\ (\ ) The layer's base offset. +.. rst-class:: classref-item-separator + ---- .. _class_CanvasLayer_property_rotation: -- :ref:`float` **rotation** - -+-----------+---------------------+ -| *Default* | ``0.0`` | -+-----------+---------------------+ -| *Setter* | set_rotation(value) | -+-----------+---------------------+ -| *Getter* | get_rotation() | -+-----------+---------------------+ - -The layer's rotation in radians. +.. rst-class:: classref-property ----- +:ref:`float` **rotation** = ``0.0`` :ref:`🔗` -.. _class_CanvasLayer_property_rotation_degrees: +.. rst-class:: classref-property-setget -- :ref:`float` **rotation_degrees** +- |void| **set_rotation**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_rotation**\ (\ ) -+-----------+-----------------------------+ -| *Default* | ``0.0`` | -+-----------+-----------------------------+ -| *Setter* | set_rotation_degrees(value) | -+-----------+-----------------------------+ -| *Getter* | get_rotation_degrees() | -+-----------+-----------------------------+ +The layer's rotation in radians. -The layer's rotation in degrees. +.. rst-class:: classref-item-separator ---- .. _class_CanvasLayer_property_scale: -- :ref:`Vector2` **scale** +.. rst-class:: classref-property + +:ref:`Vector2` **scale** = ``Vector2(1, 1)`` :ref:`🔗` -+-----------+---------------------+ -| *Default* | ``Vector2( 1, 1 )`` | -+-----------+---------------------+ -| *Setter* | set_scale(value) | -+-----------+---------------------+ -| *Getter* | get_scale() | -+-----------+---------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_scale**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_scale**\ (\ ) The layer's scale. +.. rst-class:: classref-item-separator + ---- .. _class_CanvasLayer_property_transform: -- :ref:`Transform2D` **transform** +.. rst-class:: classref-property + +:ref:`Transform2D` **transform** = ``Transform2D(1, 0, 0, 1, 0, 0)`` :ref:`🔗` -+-----------+-------------------------------------+ -| *Default* | ``Transform2D( 1, 0, 0, 1, 0, 0 )`` | -+-----------+-------------------------------------+ -| *Setter* | set_transform(value) | -+-----------+-------------------------------------+ -| *Getter* | get_transform() | -+-----------+-------------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_transform**\ (\ value\: :ref:`Transform2D`\ ) +- :ref:`Transform2D` **get_transform**\ (\ ) The layer's transform. +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasLayer_property_visible: + +.. rst-class:: classref-property + +:ref:`bool` **visible** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_visible**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_visible**\ (\ ) + +If ``false``, any :ref:`CanvasItem` under this **CanvasLayer** will be hidden. + +Unlike :ref:`CanvasItem.visible`, visibility of a **CanvasLayer** isn't propagated to underlying layers. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- .. _class_CanvasLayer_method_get_canvas: -- :ref:`RID` **get_canvas** **(** **)** const +.. rst-class:: classref-method + +:ref:`RID` **get_canvas**\ (\ ) |const| :ref:`🔗` Returns the RID of the canvas used by this layer. +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasLayer_method_get_final_transform: + +.. rst-class:: classref-method + +:ref:`Transform2D` **get_final_transform**\ (\ ) |const| :ref:`🔗` + +Returns the transform from the **CanvasLayer**\ s coordinate system to the :ref:`Viewport`\ s coordinate system. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasLayer_method_hide: + +.. rst-class:: classref-method + +|void| **hide**\ (\ ) :ref:`🔗` + +Hides any :ref:`CanvasItem` under this **CanvasLayer**. This is equivalent to setting :ref:`visible` to ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasLayer_method_show: + +.. rst-class:: classref-method + +|void| **show**\ (\ ) :ref:`🔗` + +Shows any :ref:`CanvasItem` under this **CanvasLayer**. This is equivalent to setting :ref:`visible` to ``true``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_canvasmodulate.rst b/classes/class_canvasmodulate.rst index a659d6120eb..56d42164049 100644 --- a/classes/class_canvasmodulate.rst +++ b/classes/class_canvasmodulate.rst @@ -1,8 +1,12 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CanvasModulate.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. meta:: + :keywords: color + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CanvasModulate.xml. .. _class_CanvasModulate: @@ -11,34 +15,62 @@ CanvasModulate **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Tint the entire canvas. +A node that applies a color tint to a canvas. + +.. rst-class:: classref-introduction-group Description ----------- -``CanvasModulate`` tints the canvas elements using its assigned :ref:`color`. +**CanvasModulate** applies a color tint to all nodes on a canvas. Only one can be used to tint a canvas, but :ref:`CanvasLayer`\ s can be used to render things independently. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`2D lights and shadows <../tutorials/2d/2d_lights_and_shadows>` + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+---------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`color` | ``Color( 1, 1, 1, 1 )`` | -+---------------------------+---------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +---------------------------+---------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`color` | ``Color(1, 1, 1, 1)`` | + +---------------------------+---------------------------------------------------+-----------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_CanvasModulate_property_color: -- :ref:`Color` **color** +.. rst-class:: classref-property + +:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``Color( 1, 1, 1, 1 )`` | -+-----------+-------------------------+ -| *Setter* | set_color(value) | -+-----------+-------------------------+ -| *Getter* | get_color() | -+-----------+-------------------------+ +- |void| **set_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_color**\ (\ ) The tint color to apply. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_canvastexture.rst b/classes/class_canvastexture.rst new file mode 100644 index 00000000000..f387c6583ec --- /dev/null +++ b/classes/class_canvastexture.rst @@ -0,0 +1,193 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CanvasTexture.xml. + +.. _class_CanvasTexture: + +CanvasTexture +============= + +**Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Texture with optional normal and specular maps for use in 2D rendering. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**CanvasTexture** is an alternative to :ref:`ImageTexture` for 2D rendering. It allows using normal maps and specular maps in any node that inherits from :ref:`CanvasItem`. **CanvasTexture** also allows overriding the texture's filter and repeat mode independently of the node's properties (or the project settings). + +\ **Note:** **CanvasTexture** cannot be used in 3D. It will not display correctly when applied to any :ref:`VisualInstance3D`, such as :ref:`Sprite3D` or :ref:`Decal`. For physically-based materials in 3D, use :ref:`BaseMaterial3D` instead. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`2D Lights and Shadows <../tutorials/2d/2d_lights_and_shadows>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`diffuse_texture` | | + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`normal_texture` | | + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | resource_local_to_scene | ``false`` (overrides :ref:`Resource`) | + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`specular_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`specular_shininess` | ``1.0`` | + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`specular_texture` | | + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`TextureFilter` | :ref:`texture_filter` | ``0`` | + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`TextureRepeat` | :ref:`texture_repeat` | ``0`` | + +-----------------------------------------------------+----------------------------------------------------------------------------+----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CanvasTexture_property_diffuse_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **diffuse_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_diffuse_texture**\ (\ value\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_diffuse_texture**\ (\ ) + +The diffuse (color) texture to use. This is the main texture you want to set in most cases. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasTexture_property_normal_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **normal_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_normal_texture**\ (\ value\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_normal_texture**\ (\ ) + +The normal map texture to use. Only has a visible effect if :ref:`Light2D`\ s are affecting this **CanvasTexture**. + +\ **Note:** Godot expects the normal map to use X+, Y+, and Z+ coordinates. See `this page `__ for a comparison of normal map coordinates expected by popular engines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasTexture_property_specular_color: + +.. rst-class:: classref-property + +:ref:`Color` **specular_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_specular_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_specular_color**\ (\ ) + +The multiplier for specular reflection colors. The :ref:`Light2D`'s color is also taken into account when determining the reflection color. Only has a visible effect if :ref:`Light2D`\ s are affecting this **CanvasTexture**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasTexture_property_specular_shininess: + +.. rst-class:: classref-property + +:ref:`float` **specular_shininess** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_specular_shininess**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_specular_shininess**\ (\ ) + +The specular exponent for :ref:`Light2D` specular reflections. Higher values result in a more glossy/"wet" look, with reflections becoming more localized and less visible overall. The default value of ``1.0`` disables specular reflections entirely. Only has a visible effect if :ref:`Light2D`\ s are affecting this **CanvasTexture**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasTexture_property_specular_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **specular_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_specular_texture**\ (\ value\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_specular_texture**\ (\ ) + +The specular map to use for :ref:`Light2D` specular reflections. This should be a grayscale or colored texture, with brighter areas resulting in a higher :ref:`specular_shininess` value. Using a colored :ref:`specular_texture` allows controlling specular shininess on a per-channel basis. Only has a visible effect if :ref:`Light2D`\ s are affecting this **CanvasTexture**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasTexture_property_texture_filter: + +.. rst-class:: classref-property + +:ref:`TextureFilter` **texture_filter** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture_filter**\ (\ value\: :ref:`TextureFilter`\ ) +- :ref:`TextureFilter` **get_texture_filter**\ (\ ) + +The texture filtering mode to use when drawing this **CanvasTexture**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasTexture_property_texture_repeat: + +.. rst-class:: classref-property + +:ref:`TextureRepeat` **texture_repeat** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture_repeat**\ (\ value\: :ref:`TextureRepeat`\ ) +- :ref:`TextureRepeat` **get_texture_repeat**\ (\ ) + +The texture repeat mode to use when drawing this **CanvasTexture**. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_capsulemesh.rst b/classes/class_capsulemesh.rst index 60cc04a9d75..0d0078c6c84 100644 --- a/classes/class_capsulemesh.rst +++ b/classes/class_capsulemesh.rst @@ -1,98 +1,127 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CapsuleMesh.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CapsuleMesh.xml. .. _class_CapsuleMesh: CapsuleMesh =========== -**Inherits:** :ref:`PrimitiveMesh` **<** :ref:`Mesh` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`PrimitiveMesh` **<** :ref:`Mesh` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Class representing a capsule-shaped :ref:`PrimitiveMesh`. +.. rst-class:: classref-introduction-group + Description ----------- Class representing a capsule-shaped :ref:`PrimitiveMesh`. +.. rst-class:: classref-reftable-group + Properties ---------- -+---------------------------+--------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`mid_height` | ``1.0`` | -+---------------------------+--------------------------------------------------------------------+---------+ -| :ref:`int` | :ref:`radial_segments` | ``64`` | -+---------------------------+--------------------------------------------------------------------+---------+ -| :ref:`float` | :ref:`radius` | ``1.0`` | -+---------------------------+--------------------------------------------------------------------+---------+ -| :ref:`int` | :ref:`rings` | ``8`` | -+---------------------------+--------------------------------------------------------------------+---------+ +.. table:: + :widths: auto + + +---------------------------+--------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`height` | ``2.0`` | + +---------------------------+--------------------------------------------------------------------+---------+ + | :ref:`int` | :ref:`radial_segments` | ``64`` | + +---------------------------+--------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`radius` | ``0.5`` | + +---------------------------+--------------------------------------------------------------------+---------+ + | :ref:`int` | :ref:`rings` | ``8`` | + +---------------------------+--------------------------------------------------------------------+---------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- -.. _class_CapsuleMesh_property_mid_height: +.. _class_CapsuleMesh_property_height: + +.. rst-class:: classref-property + +:ref:`float` **height** = ``2.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`float` **mid_height** +- |void| **set_height**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_height**\ (\ ) -+-----------+-----------------------+ -| *Default* | ``1.0`` | -+-----------+-----------------------+ -| *Setter* | set_mid_height(value) | -+-----------+-----------------------+ -| *Getter* | get_mid_height() | -+-----------+-----------------------+ +Total height of the capsule mesh (including the hemispherical ends). -Height of the capsule mesh from the center point. +\ **Note:** The :ref:`height` of a capsule must be at least twice its :ref:`radius`. Otherwise, the capsule becomes a circle. If the :ref:`height` is less than twice the :ref:`radius`, the properties adjust to a valid value. + +.. rst-class:: classref-item-separator ---- .. _class_CapsuleMesh_property_radial_segments: -- :ref:`int` **radial_segments** +.. rst-class:: classref-property + +:ref:`int` **radial_segments** = ``64`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------------+ -| *Default* | ``64`` | -+-----------+----------------------------+ -| *Setter* | set_radial_segments(value) | -+-----------+----------------------------+ -| *Getter* | get_radial_segments() | -+-----------+----------------------------+ +- |void| **set_radial_segments**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_radial_segments**\ (\ ) Number of radial segments on the capsule mesh. +.. rst-class:: classref-item-separator + ---- .. _class_CapsuleMesh_property_radius: -- :ref:`float` **radius** +.. rst-class:: classref-property + +:ref:`float` **radius** = ``0.5`` :ref:`🔗` -+-----------+-------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------+ -| *Setter* | set_radius(value) | -+-----------+-------------------+ -| *Getter* | get_radius() | -+-----------+-------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_radius**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_radius**\ (\ ) Radius of the capsule mesh. +\ **Note:** The :ref:`radius` of a capsule cannot be greater than half of its :ref:`height`. Otherwise, the capsule becomes a circle. If the :ref:`radius` is greater than half of the :ref:`height`, the properties adjust to a valid value. + +.. rst-class:: classref-item-separator + ---- .. _class_CapsuleMesh_property_rings: -- :ref:`int` **rings** +.. rst-class:: classref-property + +:ref:`int` **rings** = ``8`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+------------------+ -| *Default* | ``8`` | -+-----------+------------------+ -| *Setter* | set_rings(value) | -+-----------+------------------+ -| *Getter* | get_rings() | -+-----------+------------------+ +- |void| **set_rings**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_rings**\ (\ ) Number of rings along the height of the capsule. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_capsuleshape.rst b/classes/class_capsuleshape.rst deleted file mode 100644 index 313f5a8c2f6..00000000000 --- a/classes/class_capsuleshape.rst +++ /dev/null @@ -1,62 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CapsuleShape.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_CapsuleShape: - -CapsuleShape -============ - -**Inherits:** :ref:`Shape` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` - -Capsule shape for collisions. - -Description ------------ - -Capsule shape for collisions. - -Properties ----------- - -+---------------------------+---------------------------------------------------+---------+ -| :ref:`float` | :ref:`height` | ``1.0`` | -+---------------------------+---------------------------------------------------+---------+ -| :ref:`float` | :ref:`radius` | ``1.0`` | -+---------------------------+---------------------------------------------------+---------+ - -Property Descriptions ---------------------- - -.. _class_CapsuleShape_property_height: - -- :ref:`float` **height** - -+-----------+-------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------+ -| *Setter* | set_height(value) | -+-----------+-------------------+ -| *Getter* | get_height() | -+-----------+-------------------+ - -The capsule's height. - ----- - -.. _class_CapsuleShape_property_radius: - -- :ref:`float` **radius** - -+-----------+-------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------+ -| *Setter* | set_radius(value) | -+-----------+-------------------+ -| *Getter* | get_radius() | -+-----------+-------------------+ - -The capsule's radius. - diff --git a/classes/class_capsuleshape2d.rst b/classes/class_capsuleshape2d.rst index cf5962aaf03..a28e551347e 100644 --- a/classes/class_capsuleshape2d.rst +++ b/classes/class_capsuleshape2d.rst @@ -1,62 +1,110 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CapsuleShape2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CapsuleShape2D.xml. .. _class_CapsuleShape2D: CapsuleShape2D ============== -**Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Capsule shape for 2D collisions. +A 2D capsule shape used for physics collision. + +.. rst-class:: classref-introduction-group Description ----------- -Capsule shape for 2D collisions. +A 2D capsule shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape2D`. + +\ **Performance:** **CapsuleShape2D** is fast to check collisions against, but it is slower than :ref:`RectangleShape2D` and :ref:`CircleShape2D`. + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+-----------------------------------------------------+----------+ -| :ref:`float` | :ref:`height` | ``20.0`` | -+---------------------------+-----------------------------------------------------+----------+ -| :ref:`float` | :ref:`radius` | ``10.0`` | -+---------------------------+-----------------------------------------------------+----------+ +.. table:: + :widths: auto + + +---------------------------+-------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`height` | ``30.0`` | + +---------------------------+-------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`mid_height` | | + +---------------------------+-------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`radius` | ``10.0`` | + +---------------------------+-------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_CapsuleShape2D_property_height: -- :ref:`float` **height** +.. rst-class:: classref-property + +:ref:`float` **height** = ``30.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_height**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_height**\ (\ ) + +The capsule's full height, including the semicircles. -+-----------+-------------------+ -| *Default* | ``20.0`` | -+-----------+-------------------+ -| *Setter* | set_height(value) | -+-----------+-------------------+ -| *Getter* | get_height() | -+-----------+-------------------+ +\ **Note:** The :ref:`height` of a capsule must be at least twice its :ref:`radius`. Otherwise, the capsule becomes a circle. If the :ref:`height` is less than twice the :ref:`radius`, the properties adjust to a valid value. -The capsule's height. +.. rst-class:: classref-item-separator + +---- + +.. _class_CapsuleShape2D_property_mid_height: + +.. rst-class:: classref-property + +:ref:`float` **mid_height** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mid_height**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_mid_height**\ (\ ) + +The capsule's height, excluding the semicircles. This is the height of the central rectangular part in the middle of the capsule, and is the distance between the centers of the two semicircles. This is a wrapper for :ref:`height`. + +.. rst-class:: classref-item-separator ---- .. _class_CapsuleShape2D_property_radius: -- :ref:`float` **radius** +.. rst-class:: classref-property + +:ref:`float` **radius** = ``10.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------+ -| *Default* | ``10.0`` | -+-----------+-------------------+ -| *Setter* | set_radius(value) | -+-----------+-------------------+ -| *Getter* | get_radius() | -+-----------+-------------------+ +- |void| **set_radius**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_radius**\ (\ ) The capsule's radius. +\ **Note:** The :ref:`radius` of a capsule cannot be greater than half of its :ref:`height`. Otherwise, the capsule becomes a circle. If the :ref:`radius` is greater than half of the :ref:`height`, the properties adjust to a valid value. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_capsuleshape3d.rst b/classes/class_capsuleshape3d.rst new file mode 100644 index 00000000000..c651da28a0d --- /dev/null +++ b/classes/class_capsuleshape3d.rst @@ -0,0 +1,117 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CapsuleShape3D.xml. + +.. _class_CapsuleShape3D: + +CapsuleShape3D +============== + +**Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +A 3D capsule shape used for physics collision. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A 3D capsule shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. + +\ **Performance:** **CapsuleShape3D** is fast to check collisions against. It is faster than :ref:`CylinderShape3D`, but slower than :ref:`SphereShape3D` and :ref:`BoxShape3D`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `3D Physics Tests Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+-------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`height` | ``2.0`` | + +---------------------------+-------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`mid_height` | | + +---------------------------+-------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`radius` | ``0.5`` | + +---------------------------+-------------------------------------------------------------+---------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CapsuleShape3D_property_height: + +.. rst-class:: classref-property + +:ref:`float` **height** = ``2.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_height**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_height**\ (\ ) + +The capsule's full height, including the hemispheres. + +\ **Note:** The :ref:`height` of a capsule must be at least twice its :ref:`radius`. Otherwise, the capsule becomes a sphere. If the :ref:`height` is less than twice the :ref:`radius`, the properties adjust to a valid value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CapsuleShape3D_property_mid_height: + +.. rst-class:: classref-property + +:ref:`float` **mid_height** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mid_height**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_mid_height**\ (\ ) + +The capsule's height, excluding the hemispheres. This is the height of the central cylindrical part in the middle of the capsule, and is the distance between the centers of the two hemispheres. This is a wrapper for :ref:`height`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CapsuleShape3D_property_radius: + +.. rst-class:: classref-property + +:ref:`float` **radius** = ``0.5`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_radius**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_radius**\ (\ ) + +The capsule's radius. + +\ **Note:** The :ref:`radius` of a capsule cannot be greater than half of its :ref:`height`. Otherwise, the capsule becomes a sphere. If the :ref:`radius` is greater than half of the :ref:`height`, the properties adjust to a valid value. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_ccdik3d.rst b/classes/class_ccdik3d.rst new file mode 100644 index 00000000000..508cae57150 --- /dev/null +++ b/classes/class_ccdik3d.rst @@ -0,0 +1,36 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CCDIK3D.xml. + +.. _class_CCDIK3D: + +CCDIK3D +======= + +**Inherits:** :ref:`IterateIK3D` **<** :ref:`ChainIK3D` **<** :ref:`IKModifier3D` **<** :ref:`SkeletonModifier3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +Rotation based cyclic coordinate descent inverse kinematics solver. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**CCDIK3D** is rotation based IK, enabling fast and effective tracking even with large joint rotations. It's especially suitable for chains with limitations, providing smoother and more stable target tracking compared to :ref:`FABRIK3D`. + +The resulting twist around the forward vector will always be kept from the previous pose. + +\ **Note:** When the target is close to the root, it can cause unnatural movement, including joint flips and oscillations. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_centercontainer.rst b/classes/class_centercontainer.rst index 635f7dbb959..a4139a5ef6c 100644 --- a/classes/class_centercontainer.rst +++ b/classes/class_centercontainer.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CenterContainer.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CenterContainer.xml. .. _class_CenterContainer: @@ -11,34 +12,62 @@ CenterContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Keeps children controls centered. +A container that keeps child controls in its center. + +.. rst-class:: classref-introduction-group Description ----------- -CenterContainer keeps children controls centered. This container keeps all children to their minimum size, in the center. +**CenterContainer** is a container that keeps all of its child controls in its center at their minimum size. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------+------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`use_top_left` | ``false`` | -+-------------------------+------------------------------------------------------------------+-----------+ +.. table:: + :widths: auto + + +-------------------------+------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`use_top_left` | ``false`` | + +-------------------------+------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_CenterContainer_property_use_top_left: -- :ref:`bool` **use_top_left** +.. rst-class:: classref-property + +:ref:`bool` **use_top_left** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``false`` | -+-----------+-------------------------+ -| *Setter* | set_use_top_left(value) | -+-----------+-------------------------+ -| *Getter* | is_using_top_left() | -+-----------+-------------------------+ +- |void| **set_use_top_left**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_using_top_left**\ (\ ) -If ``true``, centers children relative to the ``CenterContainer``'s top left corner. +If ``true``, centers children relative to the **CenterContainer**'s top left corner. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_chainik3d.rst b/classes/class_chainik3d.rst new file mode 100644 index 00000000000..2e13bc3cba6 --- /dev/null +++ b/classes/class_chainik3d.rst @@ -0,0 +1,291 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ChainIK3D.xml. + +.. _class_ChainIK3D: + +ChainIK3D +========= + +**Inherits:** :ref:`IKModifier3D` **<** :ref:`SkeletonModifier3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +**Inherited By:** :ref:`IterateIK3D`, :ref:`SplineIK3D` + +A :ref:`SkeletonModifier3D` to apply inverse kinematics to bone chains containing an arbitrary number of bones. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Base class of :ref:`SkeletonModifier3D` that automatically generates a joint list from the bones between the root bone and the end bone. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_end_bone`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`BoneDirection` | :ref:`get_end_bone_direction`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_end_bone_length`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_end_bone_name`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_joint_bone`\ (\ index\: :ref:`int`, joint\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_joint_bone_name`\ (\ index\: :ref:`int`, joint\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_joint_count`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_root_bone`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_root_bone_name`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_end_bone_extended`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_end_bone`\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_end_bone_direction`\ (\ index\: :ref:`int`, bone_direction\: :ref:`BoneDirection`\ ) | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_end_bone_length`\ (\ index\: :ref:`int`, length\: :ref:`float`\ ) | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_end_bone_name`\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_extend_end_bone`\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_root_bone`\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_root_bone_name`\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) | + +-------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_ChainIK3D_method_get_end_bone: + +.. rst-class:: classref-method + +:ref:`int` **get_end_bone**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the end bone index of the bone chain. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_get_end_bone_direction: + +.. rst-class:: classref-method + +:ref:`BoneDirection` **get_end_bone_direction**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the tail direction of the end bone of the bone chain when :ref:`is_end_bone_extended()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_get_end_bone_length: + +.. rst-class:: classref-method + +:ref:`float` **get_end_bone_length**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the end bone tail length of the bone chain when :ref:`is_end_bone_extended()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_get_end_bone_name: + +.. rst-class:: classref-method + +:ref:`String` **get_end_bone_name**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the end bone name of the bone chain. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_get_joint_bone: + +.. rst-class:: classref-method + +:ref:`int` **get_joint_bone**\ (\ index\: :ref:`int`, joint\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the bone index at ``joint`` in the bone chain's joint list. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_get_joint_bone_name: + +.. rst-class:: classref-method + +:ref:`String` **get_joint_bone_name**\ (\ index\: :ref:`int`, joint\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the bone name at ``joint`` in the bone chain's joint list. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_get_joint_count: + +.. rst-class:: classref-method + +:ref:`int` **get_joint_count**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the joint count of the bone chain's joint list. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_get_root_bone: + +.. rst-class:: classref-method + +:ref:`int` **get_root_bone**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the root bone index of the bone chain. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_get_root_bone_name: + +.. rst-class:: classref-method + +:ref:`String` **get_root_bone_name**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the root bone name of the bone chain. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_is_end_bone_extended: + +.. rst-class:: classref-method + +:ref:`bool` **is_end_bone_extended**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the end bone is extended to have a tail. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_set_end_bone: + +.. rst-class:: classref-method + +|void| **set_end_bone**\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) :ref:`🔗` + +Sets the end bone index of the bone chain. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_set_end_bone_direction: + +.. rst-class:: classref-method + +|void| **set_end_bone_direction**\ (\ index\: :ref:`int`, bone_direction\: :ref:`BoneDirection`\ ) :ref:`🔗` + +Sets the end bone tail direction of the bone chain when :ref:`is_end_bone_extended()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_set_end_bone_length: + +.. rst-class:: classref-method + +|void| **set_end_bone_length**\ (\ index\: :ref:`int`, length\: :ref:`float`\ ) :ref:`🔗` + +Sets the end bone tail length of the bone chain when :ref:`is_end_bone_extended()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_set_end_bone_name: + +.. rst-class:: classref-method + +|void| **set_end_bone_name**\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) :ref:`🔗` + +Sets the end bone name of the bone chain. + +\ **Note:** The end bone must be the root bone or a child of the root bone. If they are the same, the tail must be extended by :ref:`set_extend_end_bone()` to modify the bone. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_set_extend_end_bone: + +.. rst-class:: classref-method + +|void| **set_extend_end_bone**\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` + +If ``enabled`` is ``true``, the end bone is extended to have a tail. + +The extended tail config is allocated to the last element in the joint list. In other words, if you set ``enabled`` to ``false``, the config of the last element in the joint list has no effect in the simulated result. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_set_root_bone: + +.. rst-class:: classref-method + +|void| **set_root_bone**\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) :ref:`🔗` + +Sets the root bone index of the bone chain. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ChainIK3D_method_set_root_bone_name: + +.. rst-class:: classref-method + +|void| **set_root_bone_name**\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) :ref:`🔗` + +Sets the root bone name of the bone chain. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_characterbody2d.rst b/classes/class_characterbody2d.rst new file mode 100644 index 00000000000..4855d1b665a --- /dev/null +++ b/classes/class_characterbody2d.rst @@ -0,0 +1,732 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CharacterBody2D.xml. + +.. _class_CharacterBody2D: + +CharacterBody2D +=============== + +**Inherits:** :ref:`PhysicsBody2D` **<** :ref:`CollisionObject2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` + +A 2D physics body specialized for characters moved by script. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**CharacterBody2D** is a specialized class for physics bodies that are meant to be user-controlled. They are not affected by physics at all, but they affect other physics bodies in their path. They are mainly used to provide high-level API to move objects with wall and slope detection (:ref:`move_and_slide()` method) in addition to the general collision detection provided by :ref:`PhysicsBody2D.move_and_collide()`. This makes it useful for highly configurable physics bodies that must move in specific ways and collide with the world, as is often the case with user-controlled characters. + +For game objects that don't require complex movement or collision detection, such as moving platforms, :ref:`AnimatableBody2D` is simpler to configure. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- :doc:`Troubleshooting physics issues <../tutorials/physics/troubleshooting_physics_issues>` + +- :doc:`Kinematic character (2D) <../tutorials/physics/kinematic_character_2d>` + +- :doc:`Using CharacterBody2D <../tutorials/physics/using_character_body_2d>` + +- `2D Kinematic Character Demo `__ + +- `2D Platformer Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`floor_block_on_wall` | ``true`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`floor_constant_speed` | ``false`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`float` | :ref:`floor_max_angle` | ``0.7853982`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`float` | :ref:`floor_snap_length` | ``1.0`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`floor_stop_on_slope` | ``true`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`int` | :ref:`max_slides` | ``4`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`MotionMode` | :ref:`motion_mode` | ``0`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`int` | :ref:`platform_floor_layers` | ``4294967295`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`PlatformOnLeave` | :ref:`platform_on_leave` | ``0`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`int` | :ref:`platform_wall_layers` | ``0`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`float` | :ref:`safe_margin` | ``0.08`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`slide_on_ceiling` | ``true`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`Vector2` | :ref:`up_direction` | ``Vector2(0, -1)`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`Vector2` | :ref:`velocity` | ``Vector2(0, 0)`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + | :ref:`float` | :ref:`wall_min_slide_angle` | ``0.2617994`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`apply_floor_snap`\ (\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_floor_angle`\ (\ up_direction\: :ref:`Vector2` = Vector2(0, -1)\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_floor_normal`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_last_motion`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`KinematicCollision2D` | :ref:`get_last_slide_collision`\ (\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_platform_velocity`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_position_delta`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_real_velocity`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`KinematicCollision2D` | :ref:`get_slide_collision`\ (\ slide_idx\: :ref:`int`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_slide_collision_count`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_wall_normal`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_ceiling`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_ceiling_only`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_floor`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_floor_only`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_wall`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_wall_only`\ (\ ) |const| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`move_and_slide`\ (\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_CharacterBody2D_MotionMode: + +.. rst-class:: classref-enumeration + +enum **MotionMode**: :ref:`🔗` + +.. _class_CharacterBody2D_constant_MOTION_MODE_GROUNDED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MotionMode` **MOTION_MODE_GROUNDED** = ``0`` + +Apply when notions of walls, ceiling and floor are relevant. In this mode the body motion will react to slopes (acceleration/slowdown). This mode is suitable for sided games like platformers. + +.. _class_CharacterBody2D_constant_MOTION_MODE_FLOATING: + +.. rst-class:: classref-enumeration-constant + +:ref:`MotionMode` **MOTION_MODE_FLOATING** = ``1`` + +Apply when there is no notion of floor or ceiling. All collisions will be reported as ``on_wall``. In this mode, when you slide, the speed will always be constant. This mode is suitable for top-down games. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_CharacterBody2D_PlatformOnLeave: + +.. rst-class:: classref-enumeration + +enum **PlatformOnLeave**: :ref:`🔗` + +.. _class_CharacterBody2D_constant_PLATFORM_ON_LEAVE_ADD_VELOCITY: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlatformOnLeave` **PLATFORM_ON_LEAVE_ADD_VELOCITY** = ``0`` + +Add the last platform velocity to the :ref:`velocity` when you leave a moving platform. + +.. _class_CharacterBody2D_constant_PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlatformOnLeave` **PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY** = ``1`` + +Add the last platform velocity to the :ref:`velocity` when you leave a moving platform, but any downward motion is ignored. It's useful to keep full jump height even when the platform is moving down. + +.. _class_CharacterBody2D_constant_PLATFORM_ON_LEAVE_DO_NOTHING: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlatformOnLeave` **PLATFORM_ON_LEAVE_DO_NOTHING** = ``2`` + +Do nothing when leaving a platform. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CharacterBody2D_property_floor_block_on_wall: + +.. rst-class:: classref-property + +:ref:`bool` **floor_block_on_wall** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_block_on_wall_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_floor_block_on_wall_enabled**\ (\ ) + +If ``true``, the body will be able to move on the floor only. This option avoids to be able to walk on walls, it will however allow to slide down along them. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_floor_constant_speed: + +.. rst-class:: classref-property + +:ref:`bool` **floor_constant_speed** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_constant_speed_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_floor_constant_speed_enabled**\ (\ ) + +If ``false`` (by default), the body will move faster on downward slopes and slower on upward slopes. + +If ``true``, the body will always move at the same speed on the ground no matter the slope. Note that you need to use :ref:`floor_snap_length` to stick along a downward slope at constant speed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_floor_max_angle: + +.. rst-class:: classref-property + +:ref:`float` **floor_max_angle** = ``0.7853982`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_max_angle**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_floor_max_angle**\ (\ ) + +Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling :ref:`move_and_slide()`. The default value equals 45 degrees. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_floor_snap_length: + +.. rst-class:: classref-property + +:ref:`float` **floor_snap_length** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_snap_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_floor_snap_length**\ (\ ) + +Sets a snapping distance. When set to a value different from ``0.0``, the body is kept attached to slopes when calling :ref:`move_and_slide()`. The snapping vector is determined by the given distance along the opposite direction of the :ref:`up_direction`. + +As long as the snapping vector is in contact with the ground and the body moves against :ref:`up_direction`, the body will remain attached to the surface. Snapping is not applied if the body moves along :ref:`up_direction`, meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use :ref:`apply_floor_snap()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_floor_stop_on_slope: + +.. rst-class:: classref-property + +:ref:`bool` **floor_stop_on_slope** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_stop_on_slope_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_floor_stop_on_slope_enabled**\ (\ ) + +If ``true``, the body will not slide on slopes when calling :ref:`move_and_slide()` when the body is standing still. + +If ``false``, the body will slide on floor's slopes when :ref:`velocity` applies a downward force. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_max_slides: + +.. rst-class:: classref-property + +:ref:`int` **max_slides** = ``4`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_max_slides**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_max_slides**\ (\ ) + +Maximum number of times the body can change direction before it stops when calling :ref:`move_and_slide()`. Must be greater than zero. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_motion_mode: + +.. rst-class:: classref-property + +:ref:`MotionMode` **motion_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_motion_mode**\ (\ value\: :ref:`MotionMode`\ ) +- :ref:`MotionMode` **get_motion_mode**\ (\ ) + +Sets the motion mode which defines the behavior of :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_platform_floor_layers: + +.. rst-class:: classref-property + +:ref:`int` **platform_floor_layers** = ``4294967295`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_platform_floor_layers**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_platform_floor_layers**\ (\ ) + +Collision layers that will be included for detecting floor bodies that will act as moving platforms to be followed by the **CharacterBody2D**. By default, all floor bodies are detected and propagate their velocity. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_platform_on_leave: + +.. rst-class:: classref-property + +:ref:`PlatformOnLeave` **platform_on_leave** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_platform_on_leave**\ (\ value\: :ref:`PlatformOnLeave`\ ) +- :ref:`PlatformOnLeave` **get_platform_on_leave**\ (\ ) + +Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_platform_wall_layers: + +.. rst-class:: classref-property + +:ref:`int` **platform_wall_layers** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_platform_wall_layers**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_platform_wall_layers**\ (\ ) + +Collision layers that will be included for detecting wall bodies that will act as moving platforms to be followed by the **CharacterBody2D**. By default, all wall bodies are ignored. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_safe_margin: + +.. rst-class:: classref-property + +:ref:`float` **safe_margin** = ``0.08`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_safe_margin**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_safe_margin**\ (\ ) + +Extra margin used for collision recovery when calling :ref:`move_and_slide()`. + +If the body is at least this close to another body, it will consider them to be colliding and will be pushed away before performing the actual motion. + +A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors. + +A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of character bodies. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_slide_on_ceiling: + +.. rst-class:: classref-property + +:ref:`bool` **slide_on_ceiling** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_slide_on_ceiling_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_slide_on_ceiling_enabled**\ (\ ) + +If ``true``, during a jump against the ceiling, the body will slide, if ``false`` it will be stopped and will fall vertically. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_up_direction: + +.. rst-class:: classref-property + +:ref:`Vector2` **up_direction** = ``Vector2(0, -1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_up_direction**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_up_direction**\ (\ ) + +Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling :ref:`move_and_slide()`. Defaults to :ref:`Vector2.UP`. As the vector will be normalized it can't be equal to :ref:`Vector2.ZERO`, if you want all collisions to be reported as walls, consider using :ref:`MOTION_MODE_FLOATING` as :ref:`motion_mode`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_velocity: + +.. rst-class:: classref-property + +:ref:`Vector2` **velocity** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_velocity**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_velocity**\ (\ ) + +Current velocity vector in pixels per second, used and modified during calls to :ref:`move_and_slide()`. + +\ **Note:** A common mistake is setting this property to the desired velocity multiplied by ``delta``, which produces a motion vector in pixels. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_property_wall_min_slide_angle: + +.. rst-class:: classref-property + +:ref:`float` **wall_min_slide_angle** = ``0.2617994`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_wall_min_slide_angle**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_wall_min_slide_angle**\ (\ ) + +Minimum angle (in radians) where the body is allowed to slide when it encounters a wall. The default value equals 15 degrees. This property only affects movement when :ref:`motion_mode` is :ref:`MOTION_MODE_FLOATING`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CharacterBody2D_method_apply_floor_snap: + +.. rst-class:: classref-method + +|void| **apply_floor_snap**\ (\ ) :ref:`🔗` + +Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when :ref:`is_on_floor()` returns ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_floor_angle: + +.. rst-class:: classref-method + +:ref:`float` **get_floor_angle**\ (\ up_direction\: :ref:`Vector2` = Vector2(0, -1)\ ) |const| :ref:`🔗` + +Returns the floor's collision angle at the last collision point according to ``up_direction``, which is :ref:`Vector2.UP` by default. This value is always positive and only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_floor()` returns ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_floor_normal: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_floor_normal**\ (\ ) |const| :ref:`🔗` + +Returns the collision normal of the floor at the last collision point. Only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_floor()` returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_last_motion: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_last_motion**\ (\ ) |const| :ref:`🔗` + +Returns the last motion applied to the **CharacterBody2D** during the last call to :ref:`move_and_slide()`. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_last_slide_collision: + +.. rst-class:: classref-method + +:ref:`KinematicCollision2D` **get_last_slide_collision**\ (\ ) :ref:`🔗` + +Returns a :ref:`KinematicCollision2D` if a collision occurred. The returned value contains information about the latest collision that occurred during the last call to :ref:`move_and_slide()`. Returns ``null`` if no collision occurred. See also :ref:`get_slide_collision()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_platform_velocity: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_platform_velocity**\ (\ ) |const| :ref:`🔗` + +Returns the linear velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_position_delta: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_position_delta**\ (\ ) |const| :ref:`🔗` + +Returns the travel (position delta) that occurred during the last call to :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_real_velocity: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_real_velocity**\ (\ ) |const| :ref:`🔗` + +Returns the current real velocity since the last call to :ref:`move_and_slide()`. For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to :ref:`velocity` which returns the requested velocity. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_slide_collision: + +.. rst-class:: classref-method + +:ref:`KinematicCollision2D` **get_slide_collision**\ (\ slide_idx\: :ref:`int`\ ) :ref:`🔗` + +Returns a :ref:`KinematicCollision2D`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide()`. Since the body can collide several times in a single call to :ref:`move_and_slide()`, you must specify the index of the collision in the range 0 to (:ref:`get_slide_collision_count()` - 1). See also :ref:`get_last_slide_collision()`. + +\ **Example:** Iterate through the collisions with a ``for`` loop: + + +.. tabs:: + + .. code-tab:: gdscript + + for i in get_slide_collision_count(): + var collision = get_slide_collision(i) + print("Collided with: ", collision.get_collider().name) + + .. code-tab:: csharp + + for (int i = 0; i < GetSlideCollisionCount(); i++) + { + KinematicCollision2D collision = GetSlideCollision(i); + GD.Print("Collided with: ", (collision.GetCollider() as Node).Name); + } + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_slide_collision_count: + +.. rst-class:: classref-method + +:ref:`int` **get_slide_collision_count**\ (\ ) |const| :ref:`🔗` + +Returns the number of times the body collided and changed direction during the last call to :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_get_wall_normal: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_wall_normal**\ (\ ) |const| :ref:`🔗` + +Returns the collision normal of the wall at the last collision point. Only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_wall()` returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_is_on_ceiling: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_ceiling**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided with the ceiling on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_is_on_ceiling_only: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_ceiling_only**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided only with the ceiling on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_is_on_floor: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_floor**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided with the floor on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_is_on_floor_only: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_floor_only**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided only with the floor on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_is_on_wall: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_wall**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided with a wall on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_is_on_wall_only: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_wall_only**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided only with a wall on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody2D_method_move_and_slide: + +.. rst-class:: classref-method + +:ref:`bool` **move_and_slide**\ (\ ) :ref:`🔗` + +Moves the body based on :ref:`velocity`. If the body collides with another, it will slide along the other body (by default only on floor) rather than stop immediately. If the other body is a **CharacterBody2D** or :ref:`RigidBody2D`, it will also be affected by the motion of the other body. You can use this to make moving and rotating platforms, or to make nodes push other nodes. + +This method should be used in :ref:`Node._physics_process()` (or in a method called by :ref:`Node._physics_process()`), as it uses the physics step's ``delta`` value automatically in calculations. Otherwise, the simulation will run at an incorrect speed. + +Modifies :ref:`velocity` if a slide collision occurred. To get the latest collision call :ref:`get_last_slide_collision()`, for detailed information about collisions that occurred, use :ref:`get_slide_collision()`. + +When the body touches a moving platform, the platform's velocity is automatically added to the body motion. If a collision occurs due to the platform's motion, it will always be first in the slide collisions. + +The general behavior and available properties change according to the :ref:`motion_mode`. + +Returns ``true`` if the body collided, otherwise, returns ``false``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_characterbody3d.rst b/classes/class_characterbody3d.rst new file mode 100644 index 00000000000..f98754ca13f --- /dev/null +++ b/classes/class_characterbody3d.rst @@ -0,0 +1,725 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CharacterBody3D.xml. + +.. _class_CharacterBody3D: + +CharacterBody3D +=============== + +**Inherits:** :ref:`PhysicsBody3D` **<** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +A 3D physics body specialized for characters moved by script. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**CharacterBody3D** is a specialized class for physics bodies that are meant to be user-controlled. They are not affected by physics at all, but they affect other physics bodies in their path. They are mainly used to provide high-level API to move objects with wall and slope detection (:ref:`move_and_slide()` method) in addition to the general collision detection provided by :ref:`PhysicsBody3D.move_and_collide()`. This makes it useful for highly configurable physics bodies that must move in specific ways and collide with the world, as is often the case with user-controlled characters. + +For game objects that don't require complex movement or collision detection, such as moving platforms, :ref:`AnimatableBody3D` is simpler to configure. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- :doc:`Troubleshooting physics issues <../tutorials/physics/troubleshooting_physics_issues>` + +- :doc:`Kinematic character (2D) <../tutorials/physics/kinematic_character_2d>` + +- `3D Kinematic Character Demo `__ + +- `3D Platformer Demo `__ + +- `3D Voxel Demo `__ + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`bool` | :ref:`floor_block_on_wall` | ``true`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`bool` | :ref:`floor_constant_speed` | ``false`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`float` | :ref:`floor_max_angle` | ``0.7853982`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`float` | :ref:`floor_snap_length` | ``0.1`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`bool` | :ref:`floor_stop_on_slope` | ``true`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`int` | :ref:`max_slides` | ``6`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`MotionMode` | :ref:`motion_mode` | ``0`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`int` | :ref:`platform_floor_layers` | ``4294967295`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`PlatformOnLeave` | :ref:`platform_on_leave` | ``0`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`int` | :ref:`platform_wall_layers` | ``0`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`float` | :ref:`safe_margin` | ``0.001`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`bool` | :ref:`slide_on_ceiling` | ``true`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`up_direction` | ``Vector3(0, 1, 0)`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`Vector3` | :ref:`velocity` | ``Vector3(0, 0, 0)`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + | :ref:`float` | :ref:`wall_min_slide_angle` | ``0.2617994`` | + +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`apply_floor_snap`\ (\ ) | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_floor_angle`\ (\ up_direction\: :ref:`Vector3` = Vector3(0, 1, 0)\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_floor_normal`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_last_motion`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`KinematicCollision3D` | :ref:`get_last_slide_collision`\ (\ ) | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_platform_angular_velocity`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_platform_velocity`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_position_delta`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_real_velocity`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`KinematicCollision3D` | :ref:`get_slide_collision`\ (\ slide_idx\: :ref:`int`\ ) | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_slide_collision_count`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`get_wall_normal`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_ceiling`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_ceiling_only`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_floor`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_floor_only`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_wall`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_on_wall_only`\ (\ ) |const| | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`move_and_slide`\ (\ ) | + +---------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_CharacterBody3D_MotionMode: + +.. rst-class:: classref-enumeration + +enum **MotionMode**: :ref:`🔗` + +.. _class_CharacterBody3D_constant_MOTION_MODE_GROUNDED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MotionMode` **MOTION_MODE_GROUNDED** = ``0`` + +Apply when notions of walls, ceiling and floor are relevant. In this mode the body motion will react to slopes (acceleration/slowdown). This mode is suitable for grounded games like platformers. + +.. _class_CharacterBody3D_constant_MOTION_MODE_FLOATING: + +.. rst-class:: classref-enumeration-constant + +:ref:`MotionMode` **MOTION_MODE_FLOATING** = ``1`` + +Apply when there is no notion of floor or ceiling. All collisions will be reported as ``on_wall``. In this mode, when you slide, the speed will always be constant. This mode is suitable for games without ground like space games. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_CharacterBody3D_PlatformOnLeave: + +.. rst-class:: classref-enumeration + +enum **PlatformOnLeave**: :ref:`🔗` + +.. _class_CharacterBody3D_constant_PLATFORM_ON_LEAVE_ADD_VELOCITY: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlatformOnLeave` **PLATFORM_ON_LEAVE_ADD_VELOCITY** = ``0`` + +Add the last platform velocity to the :ref:`velocity` when you leave a moving platform. + +.. _class_CharacterBody3D_constant_PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlatformOnLeave` **PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY** = ``1`` + +Add the last platform velocity to the :ref:`velocity` when you leave a moving platform, but any downward motion is ignored. It's useful to keep full jump height even when the platform is moving down. + +.. _class_CharacterBody3D_constant_PLATFORM_ON_LEAVE_DO_NOTHING: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlatformOnLeave` **PLATFORM_ON_LEAVE_DO_NOTHING** = ``2`` + +Do nothing when leaving a platform. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CharacterBody3D_property_floor_block_on_wall: + +.. rst-class:: classref-property + +:ref:`bool` **floor_block_on_wall** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_block_on_wall_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_floor_block_on_wall_enabled**\ (\ ) + +If ``true``, the body will be able to move on the floor only. This option avoids to be able to walk on walls, it will however allow to slide down along them. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_floor_constant_speed: + +.. rst-class:: classref-property + +:ref:`bool` **floor_constant_speed** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_constant_speed_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_floor_constant_speed_enabled**\ (\ ) + +If ``false`` (by default), the body will move faster on downward slopes and slower on upward slopes. + +If ``true``, the body will always move at the same speed on the ground no matter the slope. Note that you need to use :ref:`floor_snap_length` to stick along a downward slope at constant speed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_floor_max_angle: + +.. rst-class:: classref-property + +:ref:`float` **floor_max_angle** = ``0.7853982`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_max_angle**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_floor_max_angle**\ (\ ) + +Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling :ref:`move_and_slide()`. The default value equals 45 degrees. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_floor_snap_length: + +.. rst-class:: classref-property + +:ref:`float` **floor_snap_length** = ``0.1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_snap_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_floor_snap_length**\ (\ ) + +Sets a snapping distance. When set to a value different from ``0.0``, the body is kept attached to slopes when calling :ref:`move_and_slide()`. The snapping vector is determined by the given distance along the opposite direction of the :ref:`up_direction`. + +As long as the snapping vector is in contact with the ground and the body moves against :ref:`up_direction`, the body will remain attached to the surface. Snapping is not applied if the body moves along :ref:`up_direction`, meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use :ref:`apply_floor_snap()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_floor_stop_on_slope: + +.. rst-class:: classref-property + +:ref:`bool` **floor_stop_on_slope** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_floor_stop_on_slope_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_floor_stop_on_slope_enabled**\ (\ ) + +If ``true``, the body will not slide on slopes when calling :ref:`move_and_slide()` when the body is standing still. + +If ``false``, the body will slide on floor's slopes when :ref:`velocity` applies a downward force. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_max_slides: + +.. rst-class:: classref-property + +:ref:`int` **max_slides** = ``6`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_max_slides**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_max_slides**\ (\ ) + +Maximum number of times the body can change direction before it stops when calling :ref:`move_and_slide()`. Must be greater than zero. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_motion_mode: + +.. rst-class:: classref-property + +:ref:`MotionMode` **motion_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_motion_mode**\ (\ value\: :ref:`MotionMode`\ ) +- :ref:`MotionMode` **get_motion_mode**\ (\ ) + +Sets the motion mode which defines the behavior of :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_platform_floor_layers: + +.. rst-class:: classref-property + +:ref:`int` **platform_floor_layers** = ``4294967295`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_platform_floor_layers**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_platform_floor_layers**\ (\ ) + +Collision layers that will be included for detecting floor bodies that will act as moving platforms to be followed by the **CharacterBody3D**. By default, all floor bodies are detected and propagate their velocity. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_platform_on_leave: + +.. rst-class:: classref-property + +:ref:`PlatformOnLeave` **platform_on_leave** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_platform_on_leave**\ (\ value\: :ref:`PlatformOnLeave`\ ) +- :ref:`PlatformOnLeave` **get_platform_on_leave**\ (\ ) + +Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_platform_wall_layers: + +.. rst-class:: classref-property + +:ref:`int` **platform_wall_layers** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_platform_wall_layers**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_platform_wall_layers**\ (\ ) + +Collision layers that will be included for detecting wall bodies that will act as moving platforms to be followed by the **CharacterBody3D**. By default, all wall bodies are ignored. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_safe_margin: + +.. rst-class:: classref-property + +:ref:`float` **safe_margin** = ``0.001`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_safe_margin**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_safe_margin**\ (\ ) + +Extra margin used for collision recovery when calling :ref:`move_and_slide()`. + +If the body is at least this close to another body, it will consider them to be colliding and will be pushed away before performing the actual motion. + +A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors. + +A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of character bodies. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_slide_on_ceiling: + +.. rst-class:: classref-property + +:ref:`bool` **slide_on_ceiling** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_slide_on_ceiling_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_slide_on_ceiling_enabled**\ (\ ) + +If ``true``, during a jump against the ceiling, the body will slide, if ``false`` it will be stopped and will fall vertically. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_up_direction: + +.. rst-class:: classref-property + +:ref:`Vector3` **up_direction** = ``Vector3(0, 1, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_up_direction**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_up_direction**\ (\ ) + +Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling :ref:`move_and_slide()`. Defaults to :ref:`Vector3.UP`. As the vector will be normalized it can't be equal to :ref:`Vector3.ZERO`, if you want all collisions to be reported as walls, consider using :ref:`MOTION_MODE_FLOATING` as :ref:`motion_mode`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_velocity: + +.. rst-class:: classref-property + +:ref:`Vector3` **velocity** = ``Vector3(0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_velocity**\ (\ value\: :ref:`Vector3`\ ) +- :ref:`Vector3` **get_velocity**\ (\ ) + +Current velocity vector (typically meters per second), used and modified during calls to :ref:`move_and_slide()`. + +\ **Note:** A common mistake is setting this property to the desired velocity multiplied by ``delta``, which produces a motion vector (typically in meters). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_property_wall_min_slide_angle: + +.. rst-class:: classref-property + +:ref:`float` **wall_min_slide_angle** = ``0.2617994`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_wall_min_slide_angle**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_wall_min_slide_angle**\ (\ ) + +Minimum angle (in radians) where the body is allowed to slide when it encounters a wall. The default value equals 15 degrees. When :ref:`motion_mode` is :ref:`MOTION_MODE_GROUNDED`, it only affects movement if :ref:`floor_block_on_wall` is ``true``. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CharacterBody3D_method_apply_floor_snap: + +.. rst-class:: classref-method + +|void| **apply_floor_snap**\ (\ ) :ref:`🔗` + +Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when :ref:`is_on_floor()` returns ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_floor_angle: + +.. rst-class:: classref-method + +:ref:`float` **get_floor_angle**\ (\ up_direction\: :ref:`Vector3` = Vector3(0, 1, 0)\ ) |const| :ref:`🔗` + +Returns the floor's collision angle at the last collision point according to ``up_direction``, which is :ref:`Vector3.UP` by default. This value is always positive and only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_floor()` returns ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_floor_normal: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_floor_normal**\ (\ ) |const| :ref:`🔗` + +Returns the collision normal of the floor at the last collision point. Only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_floor()` returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_last_motion: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_last_motion**\ (\ ) |const| :ref:`🔗` + +Returns the last motion applied to the **CharacterBody3D** during the last call to :ref:`move_and_slide()`. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_last_slide_collision: + +.. rst-class:: classref-method + +:ref:`KinematicCollision3D` **get_last_slide_collision**\ (\ ) :ref:`🔗` + +Returns a :ref:`KinematicCollision3D` if a collision occurred. The returned value contains information about the latest collision that occurred during the last call to :ref:`move_and_slide()`. Returns ``null`` if no collision occurred. See also :ref:`get_slide_collision()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_platform_angular_velocity: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_platform_angular_velocity**\ (\ ) |const| :ref:`🔗` + +Returns the angular velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_platform_velocity: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_platform_velocity**\ (\ ) |const| :ref:`🔗` + +Returns the linear velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_position_delta: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_position_delta**\ (\ ) |const| :ref:`🔗` + +Returns the travel (position delta) that occurred during the last call to :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_real_velocity: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_real_velocity**\ (\ ) |const| :ref:`🔗` + +Returns the current real velocity since the last call to :ref:`move_and_slide()`. For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to :ref:`velocity` which returns the requested velocity. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_slide_collision: + +.. rst-class:: classref-method + +:ref:`KinematicCollision3D` **get_slide_collision**\ (\ slide_idx\: :ref:`int`\ ) :ref:`🔗` + +Returns a :ref:`KinematicCollision3D`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide()`. Since the body can collide several times in a single call to :ref:`move_and_slide()`, you must specify the index of the collision in the range 0 to (:ref:`get_slide_collision_count()` - 1). See also :ref:`get_last_slide_collision()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_slide_collision_count: + +.. rst-class:: classref-method + +:ref:`int` **get_slide_collision_count**\ (\ ) |const| :ref:`🔗` + +Returns the number of times the body collided and changed direction during the last call to :ref:`move_and_slide()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_get_wall_normal: + +.. rst-class:: classref-method + +:ref:`Vector3` **get_wall_normal**\ (\ ) |const| :ref:`🔗` + +Returns the collision normal of the wall at the last collision point. Only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_wall()` returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_is_on_ceiling: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_ceiling**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided with the ceiling on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_is_on_ceiling_only: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_ceiling_only**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided only with the ceiling on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_is_on_floor: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_floor**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided with the floor on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_is_on_floor_only: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_floor_only**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided only with the floor on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_is_on_wall: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_wall**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided with a wall on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_is_on_wall_only: + +.. rst-class:: classref-method + +:ref:`bool` **is_on_wall_only**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the body collided only with a wall on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharacterBody3D_method_move_and_slide: + +.. rst-class:: classref-method + +:ref:`bool` **move_and_slide**\ (\ ) :ref:`🔗` + +Moves the body based on :ref:`velocity`. If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a **CharacterBody3D** or :ref:`RigidBody3D`, it will also be affected by the motion of the other body. You can use this to make moving and rotating platforms, or to make nodes push other nodes. + +This method should be used in :ref:`Node._physics_process()` (or in a method called by :ref:`Node._physics_process()`), as it uses the physics step's ``delta`` value automatically in calculations. Otherwise, the simulation will run at an incorrect speed. + +Modifies :ref:`velocity` if a slide collision occurred. To get the latest collision call :ref:`get_last_slide_collision()`, for more detailed information about collisions that occurred, use :ref:`get_slide_collision()`. + +When the body touches a moving platform, the platform's velocity is automatically added to the body motion. If a collision occurs due to the platform's motion, it will always be first in the slide collisions. + +Returns ``true`` if the body collided, otherwise, returns ``false``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_charfxtransform.rst b/classes/class_charfxtransform.rst index 88bb98ac668..90c31ea4d8b 100644 --- a/classes/class_charfxtransform.rst +++ b/classes/class_charfxtransform.rst @@ -1,191 +1,321 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CharFXTransform.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CharFXTransform.xml. .. _class_CharFXTransform: CharFXTransform =============== -**Inherits:** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` Controls how an individual character will be displayed in a :ref:`RichTextEffect`. +.. rst-class:: classref-introduction-group + Description ----------- By setting various properties on this object, you can control how individual characters will be displayed in a :ref:`RichTextEffect`. +.. rst-class:: classref-introduction-group + Tutorials --------- -- :doc:`../tutorials/ui/bbcode_in_richtextlabel` +- :doc:`BBCode in RichTextLabel <../tutorials/ui/bbcode_in_richtextlabel>` -- `https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project `_ +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`absolute_index` | ``0`` | -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`character` | ``0`` | -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`color` | ``Color( 0, 0, 0, 1 )`` | -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ -| :ref:`float` | :ref:`elapsed_time` | ``0.0`` | -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ -| :ref:`Dictionary` | :ref:`env` | ``{}`` | -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ -| :ref:`Vector2` | :ref:`offset` | ``Vector2( 0, 0 )`` | -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ -| :ref:`int` | :ref:`relative_index` | ``0`` | -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`visible` | ``true`` | -+-------------------------------------+----------------------------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`color` | ``Color(0, 0, 0, 1)`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`float` | :ref:`elapsed_time` | ``0.0`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`Dictionary` | :ref:`env` | ``{}`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`RID` | :ref:`font` | ``RID()`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`int` | :ref:`glyph_count` | ``0`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`int` | :ref:`glyph_flags` | ``0`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`int` | :ref:`glyph_index` | ``0`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`Vector2` | :ref:`offset` | ``Vector2(0, 0)`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`bool` | :ref:`outline` | ``false`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`Vector2i` | :ref:`range` | ``Vector2i(0, 0)`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`int` | :ref:`relative_index` | ``0`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`Transform2D` | :ref:`transform` | ``Transform2D(1, 0, 0, 1, 0, 0)`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + | :ref:`bool` | :ref:`visible` | ``true`` | + +---------------------------------------+----------------------------------------------------------------------+-----------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- -.. _class_CharFXTransform_property_absolute_index: +.. _class_CharFXTransform_property_color: + +.. rst-class:: classref-property + +:ref:`Color` **color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget -- :ref:`int` **absolute_index** +- |void| **set_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_color**\ (\ ) -+-----------+---------------------------+ -| *Default* | ``0`` | -+-----------+---------------------------+ -| *Setter* | set_absolute_index(value) | -+-----------+---------------------------+ -| *Getter* | get_absolute_index() | -+-----------+---------------------------+ +The color the character will be drawn with. -The index of the current character (starting from 0). Setting this property won't affect drawing. +.. rst-class:: classref-item-separator ---- -.. _class_CharFXTransform_property_character: +.. _class_CharFXTransform_property_elapsed_time: + +.. rst-class:: classref-property + +:ref:`float` **elapsed_time** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_elapsed_time**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_elapsed_time**\ (\ ) + +The time elapsed since the :ref:`RichTextLabel` was added to the scene tree (in seconds). Time stops when the :ref:`RichTextLabel` is paused (see :ref:`Node.process_mode`). Resets when the text in the :ref:`RichTextLabel` is changed. + +\ **Note:** Time still passes while the :ref:`RichTextLabel` is hidden. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharFXTransform_property_env: + +.. rst-class:: classref-property -- :ref:`int` **character** +:ref:`Dictionary` **env** = ``{}`` :ref:`🔗` -+-----------+----------------------+ -| *Default* | ``0`` | -+-----------+----------------------+ -| *Setter* | set_character(value) | -+-----------+----------------------+ -| *Getter* | get_character() | -+-----------+----------------------+ +.. rst-class:: classref-property-setget -The Unicode codepoint the character will use. This only affects non-whitespace characters. :ref:`@GDScript.ord` can be useful here. For example, the following will replace all characters with asterisks: +- |void| **set_environment**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_environment**\ (\ ) + +Contains the arguments passed in the opening BBCode tag. By default, arguments are strings; if their contents match a type such as :ref:`bool`, :ref:`int` or :ref:`float`, they will be converted automatically. Color codes in the form ``#rrggbb`` or ``#rgb`` will be converted to an opaque :ref:`Color`. String arguments may not contain spaces, even if they're quoted. If present, quotes will also be present in the final string. + +For example, the opening BBCode tag ``[example foo=hello bar=true baz=42 color=#ffffff]`` will map to the following :ref:`Dictionary`: :: - # `char_fx` is the CharFXTransform parameter from `_process_custom_fx()`. - # See the RichTextEffect documentation for details. - char_fx.character = ord("*") + {"foo": "hello", "bar": true, "baz": 42, "color": Color(1, 1, 1, 1)} + +.. rst-class:: classref-item-separator ---- -.. _class_CharFXTransform_property_color: +.. _class_CharFXTransform_property_font: -- :ref:`Color` **color** +.. rst-class:: classref-property -+-----------+-------------------------+ -| *Default* | ``Color( 0, 0, 0, 1 )`` | -+-----------+-------------------------+ -| *Setter* | set_color(value) | -+-----------+-------------------------+ -| *Getter* | get_color() | -+-----------+-------------------------+ +:ref:`RID` **font** = ``RID()`` :ref:`🔗` -The color the character will be drawn with. +.. rst-class:: classref-property-setget + +- |void| **set_font**\ (\ value\: :ref:`RID`\ ) +- :ref:`RID` **get_font**\ (\ ) + +:ref:`TextServer` RID of the font used to render glyph, this value can be used with ``TextServer.font_*`` methods to retrieve font information. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +.. rst-class:: classref-item-separator ---- -.. _class_CharFXTransform_property_elapsed_time: +.. _class_CharFXTransform_property_glyph_count: + +.. rst-class:: classref-property + +:ref:`int` **glyph_count** = ``0`` :ref:`🔗` -- :ref:`float` **elapsed_time** +.. rst-class:: classref-property-setget -+-----------+-------------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------------+ -| *Setter* | set_elapsed_time(value) | -+-----------+-------------------------+ -| *Getter* | get_elapsed_time() | -+-----------+-------------------------+ +- |void| **set_glyph_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_glyph_count**\ (\ ) -The time elapsed since the :ref:`RichTextLabel` was added to the scene tree (in seconds). Time stops when the project is paused, unless the :ref:`RichTextLabel`'s :ref:`Node.pause_mode` is set to :ref:`Node.PAUSE_MODE_PROCESS`. +Number of glyphs in the grapheme cluster. This value is set in the first glyph of a cluster. -**Note:** Time still passes while the :ref:`RichTextLabel` is hidden. +\ **Note:** Read-only. Setting this property won't affect drawing. + +.. rst-class:: classref-item-separator ---- -.. _class_CharFXTransform_property_env: +.. _class_CharFXTransform_property_glyph_flags: -- :ref:`Dictionary` **env** +.. rst-class:: classref-property -+-----------+------------------------+ -| *Default* | ``{}`` | -+-----------+------------------------+ -| *Setter* | set_environment(value) | -+-----------+------------------------+ -| *Getter* | get_environment() | -+-----------+------------------------+ +:ref:`int` **glyph_flags** = ``0`` :ref:`🔗` -Contains the arguments passed in the opening BBCode tag. By default, arguments are strings; if their contents match a type such as :ref:`bool`, :ref:`int` or :ref:`float`, they will be converted automatically. Color codes in the form ``#rrggbb`` or ``#rgb`` will be converted to an opaque :ref:`Color`. String arguments may not contain spaces, even if they're quoted. If present, quotes will also be present in the final string. +.. rst-class:: classref-property-setget -For example, the opening BBCode tag ``[example foo=hello bar=true baz=42 color=#ffffff]`` will map to the following :ref:`Dictionary`: +- |void| **set_glyph_flags**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_glyph_flags**\ (\ ) -:: +Glyph flags. See :ref:`GraphemeFlag` for more info. - {"foo": "hello", "bar": true, "baz": 42, "color": Color(1, 1, 1, 1)} +\ **Note:** Read-only. Setting this property won't affect drawing. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharFXTransform_property_glyph_index: + +.. rst-class:: classref-property + +:ref:`int` **glyph_index** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_glyph_index**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_glyph_index**\ (\ ) + +Glyph index specific to the :ref:`font`. If you want to replace this glyph, use :ref:`TextServer.font_get_glyph_index()` with :ref:`font` to get a new glyph index for a single character. + +.. rst-class:: classref-item-separator ---- .. _class_CharFXTransform_property_offset: -- :ref:`Vector2` **offset** +.. rst-class:: classref-property + +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` -+-----------+---------------------+ -| *Default* | ``Vector2( 0, 0 )`` | -+-----------+---------------------+ -| *Setter* | set_offset(value) | -+-----------+---------------------+ -| *Getter* | get_offset() | -+-----------+---------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_offset**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_offset**\ (\ ) The position offset the character will be drawn with (in pixels). +.. rst-class:: classref-item-separator + +---- + +.. _class_CharFXTransform_property_outline: + +.. rst-class:: classref-property + +:ref:`bool` **outline** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_outline**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_outline**\ (\ ) + +If ``true``, FX transform is called for outline drawing. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CharFXTransform_property_range: + +.. rst-class:: classref-property + +:ref:`Vector2i` **range** = ``Vector2i(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_range**\ (\ value\: :ref:`Vector2i`\ ) +- :ref:`Vector2i` **get_range**\ (\ ) + +Absolute character range in the string, corresponding to the glyph. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +.. rst-class:: classref-item-separator + ---- .. _class_CharFXTransform_property_relative_index: -- :ref:`int` **relative_index** +.. rst-class:: classref-property + +:ref:`int` **relative_index** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_relative_index**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_relative_index**\ (\ ) + +The character offset of the glyph, relative to the current :ref:`RichTextEffect` custom block. -+-----------+---------------------------+ -| *Default* | ``0`` | -+-----------+---------------------------+ -| *Setter* | set_relative_index(value) | -+-----------+---------------------------+ -| *Getter* | get_relative_index() | -+-----------+---------------------------+ +\ **Note:** Read-only. Setting this property won't affect drawing. -The index of the current character (starting from 0). Setting this property won't affect drawing. +.. rst-class:: classref-item-separator + +---- + +.. _class_CharFXTransform_property_transform: + +.. rst-class:: classref-property + +:ref:`Transform2D` **transform** = ``Transform2D(1, 0, 0, 1, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_transform**\ (\ value\: :ref:`Transform2D`\ ) +- :ref:`Transform2D` **get_transform**\ (\ ) + +The current transform of the current glyph. It can be overridden (for example, by driving the position and rotation from a curve). You can also alter the existing value to apply transforms on top of other effects. + +.. rst-class:: classref-item-separator ---- .. _class_CharFXTransform_property_visible: -- :ref:`bool` **visible** +.. rst-class:: classref-property + +:ref:`bool` **visible** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-----------------------+ -| *Default* | ``true`` | -+-----------+-----------------------+ -| *Setter* | set_visibility(value) | -+-----------+-----------------------+ -| *Getter* | is_visible() | -+-----------+-----------------------+ +- |void| **set_visibility**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_visible**\ (\ ) If ``true``, the character will be drawn. If ``false``, the character will be hidden. Characters around hidden characters will reflow to take the space of hidden characters. If this is not desired, set their :ref:`color` to ``Color(1, 1, 1, 0)`` instead. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_checkbox.rst b/classes/class_checkbox.rst index a0d99f47103..74019676d11 100644 --- a/classes/class_checkbox.rst +++ b/classes/class_checkbox.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CheckBox.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CheckBox.xml. .. _class_CheckBox: @@ -11,60 +12,208 @@ CheckBox **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Binary choice user interface widget. See also :ref:`CheckButton`. +A button that represents a binary choice. + +.. rst-class:: classref-introduction-group Description ----------- -A checkbox allows the user to make a binary choice (choosing only one of two possible options). It's similar to :ref:`CheckButton` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use CheckBox when toggling it has **no** immediate effect on something. For instance, it should be used when toggling it will only do something once a confirmation button is pressed. +**CheckBox** allows the user to choose one of only two possible options. It's similar to :ref:`CheckButton` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use **CheckBox** when toggling it has **no** immediate effect on something. For example, it could be used when toggling it will only do something once a confirmation button is pressed. + +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + +When :ref:`BaseButton.button_group` specifies a :ref:`ButtonGroup`, **CheckBox** changes its appearance to that of a radio button and uses the various ``radio_*`` theme properties. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------+-------------+-----------------+ -| :ref:`TextAlign` | align | **O:** ``0`` | -+-----------------------------------------+-------------+-----------------+ -| :ref:`bool` | toggle_mode | **O:** ``true`` | -+-----------------------------------------+-------------+-----------------+ +.. table:: + :widths: auto + + +-------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------+ + | :ref:`HorizontalAlignment` | alignment | ``0`` (overrides :ref:`Button`) | + +-------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | toggle_mode | ``true`` (overrides :ref:`BaseButton`) | + +-------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Theme Properties ---------------- -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`int` | check_vadjust | 0 | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Texture2D` | checked | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | disabled | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | focus | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Font` | font | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color | Color( 0.88, 0.88, 0.88, 1 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color_disabled | Color( 0.9, 0.9, 0.9, 0.2 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color_hover | Color( 0.94, 0.94, 0.94, 1 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color_hover_pressed | Color( 1, 1, 1, 1 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color_pressed | Color( 1, 1, 1, 1 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | hover | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | hover_pressed | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`int` | hseparation | 4 | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | normal | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | pressed | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Texture2D` | radio_checked | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Texture2D` | radio_unchecked | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Texture2D` | unchecked | | -+-----------------------------------+--------------------------+------------------------------+ +.. table:: + :widths: auto + + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`checkbox_checked_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`checkbox_unchecked_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`check_v_offset` | ``0`` | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked_disabled` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`radio_checked` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`radio_checked_disabled` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`radio_unchecked` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`radio_unchecked_disabled` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked_disabled` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Theme Property Descriptions +--------------------------- + +.. _class_CheckBox_theme_color_checkbox_checked_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **checkbox_checked_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +The color of the checked icon when the checkbox is pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_color_checkbox_unchecked_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **checkbox_unchecked_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +The color of the unchecked icon when the checkbox is not pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_constant_check_v_offset: + +.. rst-class:: classref-themeproperty + +:ref:`int` **check_v_offset** = ``0`` :ref:`🔗` + +The vertical offset used when rendering the check icons (in pixels). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_icon_checked: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **checked** :ref:`🔗` + +The check icon to display when the **CheckBox** is checked. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_icon_checked_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **checked_disabled** :ref:`🔗` + +The check icon to display when the **CheckBox** is checked and is disabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_icon_radio_checked: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **radio_checked** :ref:`🔗` + +The check icon to display when the **CheckBox** is configured as a radio button and is checked. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_icon_radio_checked_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **radio_checked_disabled** :ref:`🔗` + +The check icon to display when the **CheckBox** is configured as a radio button, is disabled, and is unchecked. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_icon_radio_unchecked: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **radio_unchecked** :ref:`🔗` + +The check icon to display when the **CheckBox** is configured as a radio button and is unchecked. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_icon_radio_unchecked_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **radio_unchecked_disabled** :ref:`🔗` + +The check icon to display when the **CheckBox** is configured as a radio button, is disabled, and is unchecked. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_icon_unchecked: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **unchecked** :ref:`🔗` + +The check icon to display when the **CheckBox** is unchecked. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_icon_unchecked_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **unchecked_disabled** :ref:`🔗` + +The check icon to display when the **CheckBox** is unchecked and is disabled. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_checkbutton.rst b/classes/class_checkbutton.rst index 9537ee3c79c..0c4217f088a 100644 --- a/classes/class_checkbutton.rst +++ b/classes/class_checkbutton.rst @@ -1,8 +1,12 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CheckButton.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. meta:: + :keywords: switch, toggle + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CheckButton.xml. .. _class_CheckButton: @@ -11,60 +15,206 @@ CheckButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Checkable button. See also :ref:`CheckBox`. +A button that represents a binary choice. + +.. rst-class:: classref-introduction-group Description ----------- -CheckButton is a toggle button displayed as a check field. It's similar to :ref:`CheckBox` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use CheckButton when toggling it has an **immediate** effect on something. For instance, it should be used if toggling it enables/disables a setting without requiring the user to press a confirmation button. +**CheckButton** is a toggle button displayed as a check field. It's similar to :ref:`CheckBox` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use **CheckButton** when toggling it has an **immediate** effect on something. For example, it can be used when pressing it shows or hides advanced settings, without asking the user to confirm this action. + +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------+-------------+-----------------+ -| :ref:`TextAlign` | align | **O:** ``0`` | -+-----------------------------------------+-------------+-----------------+ -| :ref:`bool` | toggle_mode | **O:** ``true`` | -+-----------------------------------------+-------------+-----------------+ +.. table:: + :widths: auto + + +-------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------+ + | :ref:`HorizontalAlignment` | alignment | ``0`` (overrides :ref:`Button`) | + +-------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | toggle_mode | ``true`` (overrides :ref:`BaseButton`) | + +-------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Theme Properties ---------------- -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`int` | check_vadjust | 0 | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | disabled | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | focus | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Font` | font | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color | Color( 0.88, 0.88, 0.88, 1 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color_disabled | Color( 0.9, 0.9, 0.9, 0.2 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color_hover | Color( 0.94, 0.94, 0.94, 1 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color_hover_pressed | Color( 1, 1, 1, 1 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Color` | font_color_pressed | Color( 1, 1, 1, 1 ) | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | hover | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | hover_pressed | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`int` | hseparation | 4 | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | normal | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Texture2D` | off | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Texture2D` | off_disabled | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Texture2D` | on | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`Texture2D` | on_disabled | | -+-----------------------------------+--------------------------+------------------------------+ -| :ref:`StyleBox` | pressed | | -+-----------------------------------+--------------------------+------------------------------+ +.. table:: + :widths: auto + + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`button_checked_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`button_unchecked_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`check_v_offset` | ``0`` | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked_disabled` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked_disabled_mirrored` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked_mirrored` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked_disabled` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked_disabled_mirrored` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked_mirrored` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Theme Property Descriptions +--------------------------- + +.. _class_CheckButton_theme_color_button_checked_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **button_checked_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +The color of the checked icon when the checkbox is pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_color_button_unchecked_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **button_unchecked_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +The color of the unchecked icon when the checkbox is not pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_constant_check_v_offset: + +.. rst-class:: classref-themeproperty + +:ref:`int` **check_v_offset** = ``0`` :ref:`🔗` + +The vertical offset used when rendering the toggle icons (in pixels). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_icon_checked: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **checked** :ref:`🔗` + +The icon to display when the **CheckButton** is checked (for left-to-right layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_icon_checked_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **checked_disabled** :ref:`🔗` + +The icon to display when the **CheckButton** is checked and disabled (for left-to-right layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_icon_checked_disabled_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **checked_disabled_mirrored** :ref:`🔗` + +The icon to display when the **CheckButton** is checked and disabled (for right-to-left layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_icon_checked_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **checked_mirrored** :ref:`🔗` + +The icon to display when the **CheckButton** is checked (for right-to-left layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_icon_unchecked: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **unchecked** :ref:`🔗` + +The icon to display when the **CheckButton** is unchecked (for left-to-right layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_icon_unchecked_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **unchecked_disabled** :ref:`🔗` + +The icon to display when the **CheckButton** is unchecked and disabled (for left-to-right layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_icon_unchecked_disabled_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **unchecked_disabled_mirrored** :ref:`🔗` + +The icon to display when the **CheckButton** is unchecked and disabled (for right-to-left layouts). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_icon_unchecked_mirrored: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **unchecked_mirrored** :ref:`🔗` + +The icon to display when the **CheckButton** is unchecked (for right-to-left layouts). +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_circleshape2d.rst b/classes/class_circleshape2d.rst index a4052cb5e99..9f329d07357 100644 --- a/classes/class_circleshape2d.rst +++ b/classes/class_circleshape2d.rst @@ -1,44 +1,68 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CircleShape2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CircleShape2D.xml. .. _class_CircleShape2D: CircleShape2D ============= -**Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Circular shape for 2D collisions. +A 2D circle shape used for physics collision. + +.. rst-class:: classref-introduction-group Description ----------- -Circular shape for 2D collisions. This shape is useful for modeling balls or small characters and its collision detection with everything else is very fast. +A 2D circle shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape2D`. + +\ **Performance:** **CircleShape2D** is fast to check collisions against. It is faster than :ref:`RectangleShape2D` and :ref:`CapsuleShape2D`. + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+----------------------------------------------------+----------+ -| :ref:`float` | :ref:`radius` | ``10.0`` | -+---------------------------+----------------------------------------------------+----------+ +.. table:: + :widths: auto + + +---------------------------+----------------------------------------------------+----------+ + | :ref:`float` | :ref:`radius` | ``10.0`` | + +---------------------------+----------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_CircleShape2D_property_radius: -- :ref:`float` **radius** +.. rst-class:: classref-property + +:ref:`float` **radius** = ``10.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+-------------------+ -| *Default* | ``10.0`` | -+-----------+-------------------+ -| *Setter* | set_radius(value) | -+-----------+-------------------+ -| *Getter* | get_radius() | -+-----------+-------------------+ +- |void| **set_radius**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_radius**\ (\ ) The circle's radius. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_classdb.rst b/classes/class_classdb.rst index 4e8df88f465..59f3c705811 100644 --- a/classes/class_classdb.rst +++ b/classes/class_classdb.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ClassDB.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ClassDB.xml. .. _class_ClassDB: @@ -11,216 +12,517 @@ ClassDB **Inherits:** :ref:`Object` -Class information repository. +A class information repository. + +.. rst-class:: classref-introduction-group Description ----------- -Provides access to metadata stored for every available class. +Provides access to metadata stored for every available engine class. + +\ **Note:** Script-defined classes with ``class_name`` are not part of **ClassDB**, so they will not return reflection data such as a method or property list. However, :ref:`GDExtension`-defined classes *are* part of **ClassDB**, so they will return reflection data. + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`can_instance` **(** :ref:`StringName` class **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`class_exists` **(** :ref:`StringName` class **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`class_get_category` **(** :ref:`StringName` class **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`class_get_integer_constant` **(** :ref:`StringName` class, :ref:`StringName` name **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`class_get_integer_constant_list` **(** :ref:`StringName` class, :ref:`bool` no_inheritance=false **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`class_get_method_list` **(** :ref:`StringName` class, :ref:`bool` no_inheritance=false **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`class_get_property` **(** :ref:`Object` object, :ref:`StringName` property **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`class_get_property_list` **(** :ref:`StringName` class, :ref:`bool` no_inheritance=false **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Dictionary` | :ref:`class_get_signal` **(** :ref:`StringName` class, :ref:`StringName` signal **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`class_get_signal_list` **(** :ref:`StringName` class, :ref:`bool` no_inheritance=false **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`class_has_integer_constant` **(** :ref:`StringName` class, :ref:`StringName` name **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`class_has_method` **(** :ref:`StringName` class, :ref:`StringName` method, :ref:`bool` no_inheritance=false **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`class_has_signal` **(** :ref:`StringName` class, :ref:`StringName` signal **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`class_set_property` **(** :ref:`Object` object, :ref:`StringName` property, :ref:`Variant` value **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_class_list` **(** **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_inheriters_from_class` **(** :ref:`StringName` class **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StringName` | :ref:`get_parent_class` **(** :ref:`StringName` class **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`instance` **(** :ref:`StringName` class **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_class_enabled` **(** :ref:`StringName` class **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_parent_class` **(** :ref:`StringName` class, :ref:`StringName` inherits **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`can_instantiate`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`class_call_static`\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, ...\ ) |vararg| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_exists`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`APIType` | :ref:`class_get_api_type`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`class_get_enum_constants`\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`class_get_enum_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`class_get_integer_constant`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`class_get_integer_constant_enum`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`class_get_integer_constant_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`class_get_method_argument_count`\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_method_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`class_get_property`\ (\ object\: :ref:`Object`, property\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`class_get_property_default_value`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`class_get_property_getter`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_property_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`class_get_property_setter`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`class_get_signal`\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_signal_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_has_enum`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_has_integer_constant`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_has_method`\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_has_signal`\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`class_set_property`\ (\ object\: :ref:`Object`, property\: :ref:`StringName`, value\: :ref:`Variant`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_class_list`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_inheriters_from_class`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_parent_class`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`instantiate`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_class_enabled`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_class_enum_bitfield`\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_parent_class`\ (\ class\: :ref:`StringName`, inherits\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_ClassDB_APIType: + +.. rst-class:: classref-enumeration + +enum **APIType**: :ref:`🔗` + +.. _class_ClassDB_constant_API_CORE: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_CORE** = ``0`` + +Native Core class type. + +.. _class_ClassDB_constant_API_EDITOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EDITOR** = ``1`` + +Native Editor class type. + +.. _class_ClassDB_constant_API_EXTENSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EXTENSION** = ``2`` + +GDExtension class type. + +.. _class_ClassDB_constant_API_EDITOR_EXTENSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EDITOR_EXTENSION** = ``3`` + +GDExtension Editor class type. + +.. _class_ClassDB_constant_API_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_NONE** = ``4`` + +Unknown class type. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_ClassDB_method_can_instance: +.. _class_ClassDB_method_can_instantiate: + +.. rst-class:: classref-method -- :ref:`bool` **can_instance** **(** :ref:`StringName` class **)** const +:ref:`bool` **can_instantiate**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns ``true`` if you can instance objects from the specified ``class``, ``false`` in other case. +Returns ``true`` if objects can be instantiated from the specified ``class``, otherwise returns ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_call_static: + +.. rst-class:: classref-method + +:ref:`Variant` **class_call_static**\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, ...\ ) |vararg| :ref:`🔗` + +Calls a static method on a class. + +.. rst-class:: classref-item-separator ---- .. _class_ClassDB_method_class_exists: -- :ref:`bool` **class_exists** **(** :ref:`StringName` class **)** const +.. rst-class:: classref-method + +:ref:`bool` **class_exists**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether the specified ``class`` is available or not. +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_get_api_type: + +.. rst-class:: classref-method + +:ref:`APIType` **class_get_api_type**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the API type of the specified ``class``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_get_enum_constants: + +.. rst-class:: classref-method + +:ref:`PackedStringArray` **class_get_enum_constants**\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns an array with all the keys in ``enum`` of ``class`` or its ancestry. + +.. rst-class:: classref-item-separator + ---- -.. _class_ClassDB_method_class_get_category: +.. _class_ClassDB_method_class_get_enum_list: + +.. rst-class:: classref-method -- :ref:`StringName` **class_get_category** **(** :ref:`StringName` class **)** const +:ref:`PackedStringArray` **class_get_enum_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` -Returns a category associated with the class for use in documentation and the Asset Library. Debug mode required. +Returns an array with all the enums of ``class`` or its ancestry. + +.. rst-class:: classref-item-separator ---- .. _class_ClassDB_method_class_get_integer_constant: -- :ref:`int` **class_get_integer_constant** **(** :ref:`StringName` class, :ref:`StringName` name **)** const +.. rst-class:: classref-method + +:ref:`int` **class_get_integer_constant**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the value of the integer constant ``name`` of ``class`` or its ancestry. Always returns 0 when the constant could not be found. +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_get_integer_constant_enum: + +.. rst-class:: classref-method + +:ref:`StringName` **class_get_integer_constant_enum**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns which enum the integer constant ``name`` of ``class`` or its ancestry belongs to. + +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_class_get_integer_constant_list: -- :ref:`PackedStringArray` **class_get_integer_constant_list** **(** :ref:`StringName` class, :ref:`bool` no_inheritance=false **)** const +.. rst-class:: classref-method + +:ref:`PackedStringArray` **class_get_integer_constant_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns an array with the names all the integer constants of ``class`` or its ancestry. +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_get_method_argument_count: + +.. rst-class:: classref-method + +:ref:`int` **class_get_method_argument_count**\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns the number of arguments of the method ``method`` of ``class`` or its ancestry if ``no_inheritance`` is ``false``. + +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_class_get_method_list: -- :ref:`Array` **class_get_method_list** **(** :ref:`StringName` class, :ref:`bool` no_inheritance=false **)** const +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Dictionary`\] **class_get_method_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns an array with all the methods of ``class`` or its ancestry if ``no_inheritance`` is ``false``. Every element of the array is a :ref:`Dictionary` with the following keys: ``args``, ``default_args``, ``flags``, ``id``, ``name``, ``return: (class_name, hint, hint_string, name, type, usage)``. +\ **Note:** In exported release builds the debug info is not available, so the returned dictionaries will contain only method names. + +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_class_get_property: -- :ref:`Variant` **class_get_property** **(** :ref:`Object` object, :ref:`StringName` property **)** const +.. rst-class:: classref-method + +:ref:`Variant` **class_get_property**\ (\ object\: :ref:`Object`, property\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the value of ``property`` of ``object`` or its ancestry. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_get_property_default_value: + +.. rst-class:: classref-method + +:ref:`Variant` **class_get_property_default_value**\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the default value of ``property`` of ``class`` or its ancestor classes. -Returns the value of ``property`` of ``class`` or its ancestry. +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_get_property_getter: + +.. rst-class:: classref-method + +:ref:`StringName` **class_get_property_getter**\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) :ref:`🔗` + +Returns the getter method name of ``property`` of ``class``. + +.. rst-class:: classref-item-separator ---- .. _class_ClassDB_method_class_get_property_list: -- :ref:`Array` **class_get_property_list** **(** :ref:`StringName` class, :ref:`bool` no_inheritance=false **)** const +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Dictionary`\] **class_get_property_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns an array with all the properties of ``class`` or its ancestry if ``no_inheritance`` is ``false``. +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_get_property_setter: + +.. rst-class:: classref-method + +:ref:`StringName` **class_get_property_setter**\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) :ref:`🔗` + +Returns the setter method name of ``property`` of ``class``. + +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_class_get_signal: -- :ref:`Dictionary` **class_get_signal** **(** :ref:`StringName` class, :ref:`StringName` signal **)** const +.. rst-class:: classref-method + +:ref:`Dictionary` **class_get_signal**\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the ``signal`` data of ``class`` or its ancestry. The returned value is a :ref:`Dictionary` with the following keys: ``args``, ``default_args``, ``flags``, ``id``, ``name``, ``return: (class_name, hint, hint_string, name, type, usage)``. +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_class_get_signal_list: -- :ref:`Array` **class_get_signal_list** **(** :ref:`StringName` class, :ref:`bool` no_inheritance=false **)** const +.. rst-class:: classref-method -Returns an array with all the signals of ``class`` or its ancestry if ``no_inheritance`` is ``false``. Every element of the array is a :ref:`Dictionary` as described in :ref:`class_get_signal`. +:ref:`Array`\[:ref:`Dictionary`\] **class_get_signal_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns an array with all the signals of ``class`` or its ancestry if ``no_inheritance`` is ``false``. Every element of the array is a :ref:`Dictionary` as described in :ref:`class_get_signal()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_has_enum: + +.. rst-class:: classref-method + +:ref:`bool` **class_has_enum**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns whether ``class`` or its ancestry has an enum called ``name`` or not. + +.. rst-class:: classref-item-separator ---- .. _class_ClassDB_method_class_has_integer_constant: -- :ref:`bool` **class_has_integer_constant** **(** :ref:`StringName` class, :ref:`StringName` name **)** const +.. rst-class:: classref-method + +:ref:`bool` **class_has_integer_constant**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether ``class`` or its ancestry has an integer constant called ``name`` or not. +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_class_has_method: -- :ref:`bool` **class_has_method** **(** :ref:`StringName` class, :ref:`StringName` method, :ref:`bool` no_inheritance=false **)** const +.. rst-class:: classref-method + +:ref:`bool` **class_has_method**\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns whether ``class`` (or its ancestry if ``no_inheritance`` is ``false``) has a method called ``method`` or not. +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_class_has_signal: -- :ref:`bool` **class_has_signal** **(** :ref:`StringName` class, :ref:`StringName` signal **)** const +.. rst-class:: classref-method + +:ref:`bool` **class_has_signal**\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether ``class`` or its ancestry has a signal called ``signal`` or not. +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_class_set_property: -- :ref:`Error` **class_set_property** **(** :ref:`Object` object, :ref:`StringName` property, :ref:`Variant` value **)** const +.. rst-class:: classref-method + +:ref:`Error` **class_set_property**\ (\ object\: :ref:`Object`, property\: :ref:`StringName`, value\: :ref:`Variant`\ ) |const| :ref:`🔗` -Sets ``property`` value of ``class`` to ``value``. +Sets ``property`` value of ``object`` to ``value``. + +.. rst-class:: classref-item-separator ---- .. _class_ClassDB_method_get_class_list: -- :ref:`PackedStringArray` **get_class_list** **(** **)** const +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_class_list**\ (\ ) |const| :ref:`🔗` -Returns the names of all the classes available. +Returns the names of all engine classes available. + +\ **Note:** Script-defined classes with ``class_name`` are not included in this list. Use :ref:`ProjectSettings.get_global_class_list()` to get a list of script-defined classes instead. + +.. rst-class:: classref-item-separator ---- .. _class_ClassDB_method_get_inheriters_from_class: -- :ref:`PackedStringArray` **get_inheriters_from_class** **(** :ref:`StringName` class **)** const +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_inheriters_from_class**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns the names of all the classes that directly or indirectly inherit from ``class``. +Returns the names of all engine classes that directly or indirectly inherit from ``class``. + +.. rst-class:: classref-item-separator ---- .. _class_ClassDB_method_get_parent_class: -- :ref:`StringName` **get_parent_class** **(** :ref:`StringName` class **)** const +.. rst-class:: classref-method + +:ref:`StringName` **get_parent_class**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the parent class of ``class``. +.. rst-class:: classref-item-separator + ---- -.. _class_ClassDB_method_instance: +.. _class_ClassDB_method_instantiate: + +.. rst-class:: classref-method -- :ref:`Variant` **instance** **(** :ref:`StringName` class **)** const +:ref:`Variant` **instantiate**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Creates an instance of ``class``. +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_is_class_enabled: -- :ref:`bool` **is_class_enabled** **(** :ref:`StringName` class **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_class_enabled**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether this ``class`` is enabled or not. +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_is_class_enum_bitfield: + +.. rst-class:: classref-method + +:ref:`bool` **is_class_enum_bitfield**\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns whether ``class`` (or its ancestor classes if ``no_inheritance`` is ``false``) has an enum called ``enum`` that is a bitfield. + +.. rst-class:: classref-item-separator + ---- .. _class_ClassDB_method_is_parent_class: -- :ref:`bool` **is_parent_class** **(** :ref:`StringName` class, :ref:`StringName` inherits **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_parent_class**\ (\ class\: :ref:`StringName`, inherits\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether ``inherits`` is an ancestor of ``class`` or not. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_clippedcamera.rst b/classes/class_clippedcamera.rst deleted file mode 100644 index 630220bc1ee..00000000000 --- a/classes/class_clippedcamera.rst +++ /dev/null @@ -1,221 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ClippedCamera.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ClippedCamera: - -ClippedCamera -============= - -**Inherits:** :ref:`Camera` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -A :ref:`Camera` that includes collision. - -Description ------------ - -This node extends :ref:`Camera` to add collisions with :ref:`Area` and/or :ref:`PhysicsBody` nodes. The camera cannot move through colliding objects. - -Properties ----------- - -+----------------------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`clip_to_areas` | ``false`` | -+----------------------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`clip_to_bodies` | ``true`` | -+----------------------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`int` | :ref:`collision_mask` | ``1`` | -+----------------------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`margin` | ``0.0`` | -+----------------------------------------------------+--------------------------------------------------------------------+-----------+ -| :ref:`ProcessMode` | :ref:`process_mode` | ``0`` | -+----------------------------------------------------+--------------------------------------------------------------------+-----------+ - -Methods -------- - -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_exception` **(** :ref:`Object` node **)** | -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_exception_rid` **(** :ref:`RID` rid **)** | -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_exceptions` **(** **)** | -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_clip_offset` **(** **)** const | -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`get_collision_mask_bit` **(** :ref:`int` bit **)** const | -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_exception` **(** :ref:`Object` node **)** | -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_exception_rid` **(** :ref:`RID` rid **)** | -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_collision_mask_bit` **(** :ref:`int` bit, :ref:`bool` value **)** | -+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Enumerations ------------- - -.. _enum_ClippedCamera_ProcessMode: - -.. _class_ClippedCamera_constant_CLIP_PROCESS_PHYSICS: - -.. _class_ClippedCamera_constant_CLIP_PROCESS_IDLE: - -enum **ProcessMode**: - -- **CLIP_PROCESS_PHYSICS** = **0** --- The camera updates with the ``_physics_process`` callback. - -- **CLIP_PROCESS_IDLE** = **1** --- The camera updates with the ``_process`` callback. - -Property Descriptions ---------------------- - -.. _class_ClippedCamera_property_clip_to_areas: - -- :ref:`bool` **clip_to_areas** - -+-----------+----------------------------+ -| *Default* | ``false`` | -+-----------+----------------------------+ -| *Setter* | set_clip_to_areas(value) | -+-----------+----------------------------+ -| *Getter* | is_clip_to_areas_enabled() | -+-----------+----------------------------+ - -If ``true``, the camera stops on contact with :ref:`Area`\ s. - ----- - -.. _class_ClippedCamera_property_clip_to_bodies: - -- :ref:`bool` **clip_to_bodies** - -+-----------+-----------------------------+ -| *Default* | ``true`` | -+-----------+-----------------------------+ -| *Setter* | set_clip_to_bodies(value) | -+-----------+-----------------------------+ -| *Getter* | is_clip_to_bodies_enabled() | -+-----------+-----------------------------+ - -If ``true``, the camera stops on contact with :ref:`PhysicsBody`\ s. - ----- - -.. _class_ClippedCamera_property_collision_mask: - -- :ref:`int` **collision_mask** - -+-----------+---------------------------+ -| *Default* | ``1`` | -+-----------+---------------------------+ -| *Setter* | set_collision_mask(value) | -+-----------+---------------------------+ -| *Getter* | get_collision_mask() | -+-----------+---------------------------+ - -The camera's collision mask. Only objects in at least one collision layer matching the mask will be detected. - ----- - -.. _class_ClippedCamera_property_margin: - -- :ref:`float` **margin** - -+-----------+-------------------+ -| *Default* | ``0.0`` | -+-----------+-------------------+ -| *Setter* | set_margin(value) | -+-----------+-------------------+ -| *Getter* | get_margin() | -+-----------+-------------------+ - -The camera's collision margin. The camera can't get closer than this distance to a colliding object. - ----- - -.. _class_ClippedCamera_property_process_mode: - -- :ref:`ProcessMode` **process_mode** - -+-----------+-------------------------+ -| *Default* | ``0`` | -+-----------+-------------------------+ -| *Setter* | set_process_mode(value) | -+-----------+-------------------------+ -| *Getter* | get_process_mode() | -+-----------+-------------------------+ - -The camera's process callback. See :ref:`ProcessMode`. - -Method Descriptions -------------------- - -.. _class_ClippedCamera_method_add_exception: - -- void **add_exception** **(** :ref:`Object` node **)** - -Adds a collision exception so the camera does not collide with the specified node. - ----- - -.. _class_ClippedCamera_method_add_exception_rid: - -- void **add_exception_rid** **(** :ref:`RID` rid **)** - -Adds a collision exception so the camera does not collide with the specified :ref:`RID`. - ----- - -.. _class_ClippedCamera_method_clear_exceptions: - -- void **clear_exceptions** **(** **)** - -Removes all collision exceptions. - ----- - -.. _class_ClippedCamera_method_get_clip_offset: - -- :ref:`float` **get_clip_offset** **(** **)** const - -Returns the distance the camera has been offset due to a collision. - ----- - -.. _class_ClippedCamera_method_get_collision_mask_bit: - -- :ref:`bool` **get_collision_mask_bit** **(** :ref:`int` bit **)** const - -Returns ``true`` if the specified bit index is on. - -**Note:** Bit indices range from 0-19. - ----- - -.. _class_ClippedCamera_method_remove_exception: - -- void **remove_exception** **(** :ref:`Object` node **)** - -Removes a collision exception with the specified node. - ----- - -.. _class_ClippedCamera_method_remove_exception_rid: - -- void **remove_exception_rid** **(** :ref:`RID` rid **)** - -Removes a collision exception with the specified :ref:`RID`. - ----- - -.. _class_ClippedCamera_method_set_collision_mask_bit: - -- void **set_collision_mask_bit** **(** :ref:`int` bit, :ref:`bool` value **)** - -Sets the specified bit index to the ``value``. - -**Note:** Bit indices range from 0-19. - diff --git a/classes/class_codeedit.rst b/classes/class_codeedit.rst new file mode 100644 index 00000000000..96dfdf7b0a0 --- /dev/null +++ b/classes/class_codeedit.rst @@ -0,0 +1,2113 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CodeEdit.xml. + +.. _class_CodeEdit: + +CodeEdit +======== + +**Inherits:** :ref:`TextEdit` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` + +A multiline text editor designed for editing code. + +.. rst-class:: classref-introduction-group + +Description +----------- + +CodeEdit is a specialized :ref:`TextEdit` designed for editing plain text code files. It has many features commonly found in code editors such as line numbers, line folding, code completion, indent management, and string/comment management. + +\ **Note:** Regardless of locale, **CodeEdit** will by default always use left-to-right text direction to correctly display source code. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`auto_brace_completion_enabled` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`auto_brace_completion_highlight_matching` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`auto_brace_completion_pairs` | ``{ "\"": "\"", "'": "'", "(": ")", "[": "]", "{": "}" }`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`code_completion_enabled` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`String`\] | :ref:`code_completion_prefixes` | ``[]`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`String`\] | :ref:`delimiter_comments` | ``[]`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`String`\] | :ref:`delimiter_strings` | ``["' '", "\" \""]`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`gutters_draw_bookmarks` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`gutters_draw_breakpoints_gutter` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`gutters_draw_executing_lines` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`gutters_draw_fold_gutter` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`gutters_draw_line_numbers` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`int` | :ref:`gutters_line_numbers_min_digits` | ``3`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`gutters_zero_pad_line_numbers` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`indent_automatic` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`String`\] | :ref:`indent_automatic_prefixes` | ``[":", "{", "[", "("]`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`int` | :ref:`indent_size` | ``4`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`indent_use_spaces` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`LayoutDirection` | layout_direction | ``2`` (overrides :ref:`Control`) | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`line_folding` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`int`\] | :ref:`line_length_guidelines` | ``[]`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`symbol_lookup_on_click` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`symbol_tooltip_on_hover` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`TextDirection` | text_direction | ``1`` (overrides :ref:`TextEdit`) | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_confirm_code_completion`\ (\ replace\: :ref:`bool`\ ) |virtual| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`_filter_code_completion_candidates`\ (\ candidates\: :ref:`Array`\[:ref:`Dictionary`\]\ ) |virtual| |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_request_code_completion`\ (\ force\: :ref:`bool`\ ) |virtual| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_auto_brace_completion_pair`\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_code_completion_option`\ (\ type\: :ref:`CodeCompletionKind`, display_text\: :ref:`String`, insert_text\: :ref:`String`, text_color\: :ref:`Color` = Color(1, 1, 1, 1), icon\: :ref:`Resource` = null, value\: :ref:`Variant` = null, location\: :ref:`int` = 1024\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_comment_delimiter`\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, line_only\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_string_delimiter`\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, line_only\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`can_fold_line`\ (\ line\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`cancel_code_completion`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_bookmarked_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_breakpointed_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_comment_delimiters`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_executing_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_string_delimiters`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`confirm_code_completion`\ (\ replace\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`convert_indent`\ (\ from_line\: :ref:`int` = -1, to_line\: :ref:`int` = -1\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`create_code_region`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`delete_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`do_indent`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`duplicate_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`duplicate_selection`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fold_all_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fold_line`\ (\ line\: :ref:`int`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_auto_brace_completion_close_key`\ (\ open_key\: :ref:`String`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`get_bookmarked_lines`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`get_breakpointed_lines`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`get_code_completion_option`\ (\ index\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`get_code_completion_options`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_code_completion_selected_index`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_code_region_end_tag`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_code_region_start_tag`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_delimiter_end_key`\ (\ delimiter_index\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_delimiter_end_position`\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_delimiter_start_key`\ (\ delimiter_index\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_delimiter_start_position`\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`get_executing_lines`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`int`\] | :ref:`get_folded_lines`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_text_for_code_completion`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_text_for_symbol_lookup`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_text_with_cursor_char`\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_auto_brace_completion_close_key`\ (\ close_key\: :ref:`String`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_auto_brace_completion_open_key`\ (\ open_key\: :ref:`String`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_comment_delimiter`\ (\ start_key\: :ref:`String`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_string_delimiter`\ (\ start_key\: :ref:`String`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`indent_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`is_in_comment`\ (\ line\: :ref:`int`, column\: :ref:`int` = -1\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`is_in_string`\ (\ line\: :ref:`int`, column\: :ref:`int` = -1\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_line_bookmarked`\ (\ line\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_line_breakpointed`\ (\ line\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_line_code_region_end`\ (\ line\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_line_code_region_start`\ (\ line\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_line_executing`\ (\ line\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_line_folded`\ (\ line\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`move_lines_down`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`move_lines_up`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_comment_delimiter`\ (\ start_key\: :ref:`String`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_string_delimiter`\ (\ start_key\: :ref:`String`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`request_code_completion`\ (\ force\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_code_completion_selected_index`\ (\ index\: :ref:`int`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_code_hint`\ (\ code_hint\: :ref:`String`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_code_hint_draw_below`\ (\ draw_below\: :ref:`bool`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_code_region_tags`\ (\ start\: :ref:`String` = "region", end\: :ref:`String` = "endregion"\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_line_as_bookmarked`\ (\ line\: :ref:`int`, bookmarked\: :ref:`bool`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_line_as_breakpoint`\ (\ line\: :ref:`int`, breakpointed\: :ref:`bool`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_line_as_executing`\ (\ line\: :ref:`int`, executing\: :ref:`bool`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_symbol_lookup_word_as_valid`\ (\ valid\: :ref:`bool`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`toggle_foldable_line`\ (\ line\: :ref:`int`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`toggle_foldable_lines_at_carets`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`unfold_all_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`unfold_line`\ (\ line\: :ref:`int`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`unindent_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`update_code_completion_options`\ (\ force\: :ref:`bool`\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Theme Properties +---------------- + +.. table:: + :widths: auto + + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`bookmark_color` | ``Color(0.5, 0.64, 1, 0.8)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`brace_mismatch_color` | ``Color(1, 0.2, 0.2, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`breakpoint_color` | ``Color(0.9, 0.29, 0.3, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`code_folding_color` | ``Color(0.8, 0.8, 0.8, 0.8)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`completion_background_color` | ``Color(0.17, 0.16, 0.2, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`completion_existing_color` | ``Color(0.87, 0.87, 0.87, 0.13)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`completion_scroll_color` | ``Color(1, 1, 1, 0.29)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`completion_scroll_hovered_color` | ``Color(1, 1, 1, 0.4)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`completion_selected_color` | ``Color(0.26, 0.26, 0.27, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`executing_line_color` | ``Color(0.98, 0.89, 0.27, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`folded_code_region_color` | ``Color(0.68, 0.46, 0.77, 0.2)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`line_length_guideline_color` | ``Color(0.3, 0.5, 0.8, 0.1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Color` | :ref:`line_number_color` | ``Color(0.67, 0.67, 0.67, 0.4)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`int` | :ref:`completion_lines` | ``7`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`int` | :ref:`completion_max_width` | ``50`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`int` | :ref:`completion_scroll_width` | ``6`` | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`bookmark` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`breakpoint` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`can_fold` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`can_fold_code_region` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`completion_color_bg` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`executing_line` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`folded` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`folded_code_region` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`folded_eol_icon` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`StyleBox` | :ref:`completion` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_CodeEdit_signal_breakpoint_toggled: + +.. rst-class:: classref-signal + +**breakpoint_toggled**\ (\ line\: :ref:`int`\ ) :ref:`🔗` + +Emitted when a breakpoint is added or removed from a line. If the line is removed via backspace, a signal is emitted at the old line. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_signal_code_completion_requested: + +.. rst-class:: classref-signal + +**code_completion_requested**\ (\ ) :ref:`🔗` + +Emitted when the user requests code completion. This signal will not be sent if :ref:`_request_code_completion()` is overridden or :ref:`code_completion_enabled` is ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_signal_symbol_hovered: + +.. rst-class:: classref-signal + +**symbol_hovered**\ (\ symbol\: :ref:`String`, line\: :ref:`int`, column\: :ref:`int`\ ) :ref:`🔗` + +Emitted when the user hovers over a symbol. Unlike :ref:`Control.mouse_entered`, this signal is not emitted immediately, but when the cursor is over the symbol for :ref:`ProjectSettings.gui/timers/tooltip_delay_sec` seconds. + +\ **Note:** :ref:`symbol_tooltip_on_hover` must be ``true`` for this signal to be emitted. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_signal_symbol_lookup: + +.. rst-class:: classref-signal + +**symbol_lookup**\ (\ symbol\: :ref:`String`, line\: :ref:`int`, column\: :ref:`int`\ ) :ref:`🔗` + +Emitted when the user has clicked on a valid symbol. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_signal_symbol_validate: + +.. rst-class:: classref-signal + +**symbol_validate**\ (\ symbol\: :ref:`String`\ ) :ref:`🔗` + +Emitted when the user hovers over a symbol. The symbol should be validated and responded to, by calling :ref:`set_symbol_lookup_word_as_valid()`. + +\ **Note:** :ref:`symbol_lookup_on_click` must be ``true`` for this signal to be emitted. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_CodeEdit_CodeCompletionKind: + +.. rst-class:: classref-enumeration + +enum **CodeCompletionKind**: :ref:`🔗` + +.. _class_CodeEdit_constant_KIND_CLASS: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_CLASS** = ``0`` + +Marks the option as a class. + +.. _class_CodeEdit_constant_KIND_FUNCTION: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_FUNCTION** = ``1`` + +Marks the option as a function. + +.. _class_CodeEdit_constant_KIND_SIGNAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_SIGNAL** = ``2`` + +Marks the option as a Godot signal. + +.. _class_CodeEdit_constant_KIND_VARIABLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_VARIABLE** = ``3`` + +Marks the option as a variable. + +.. _class_CodeEdit_constant_KIND_MEMBER: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_MEMBER** = ``4`` + +Marks the option as a member. + +.. _class_CodeEdit_constant_KIND_ENUM: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_ENUM** = ``5`` + +Marks the option as an enum entry. + +.. _class_CodeEdit_constant_KIND_CONSTANT: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_CONSTANT** = ``6`` + +Marks the option as a constant. + +.. _class_CodeEdit_constant_KIND_NODE_PATH: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_NODE_PATH** = ``7`` + +Marks the option as a Godot node path. + +.. _class_CodeEdit_constant_KIND_FILE_PATH: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_FILE_PATH** = ``8`` + +Marks the option as a file path. + +.. _class_CodeEdit_constant_KIND_PLAIN_TEXT: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionKind` **KIND_PLAIN_TEXT** = ``9`` + +Marks the option as unclassified or plain text. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_CodeEdit_CodeCompletionLocation: + +.. rst-class:: classref-enumeration + +enum **CodeCompletionLocation**: :ref:`🔗` + +.. _class_CodeEdit_constant_LOCATION_LOCAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionLocation` **LOCATION_LOCAL** = ``0`` + +The option is local to the location of the code completion query - e.g. a local variable. Subsequent value of location represent options from the outer class, the exact value represent how far they are (in terms of inner classes). + +.. _class_CodeEdit_constant_LOCATION_PARENT_MASK: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionLocation` **LOCATION_PARENT_MASK** = ``256`` + +The option is from the containing class or a parent class, relative to the location of the code completion query. Perform a bitwise OR with the class depth (e.g. ``0`` for the local class, ``1`` for the parent, ``2`` for the grandparent, etc.) to store the depth of an option in the class or a parent class. + +.. _class_CodeEdit_constant_LOCATION_OTHER_USER_CODE: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionLocation` **LOCATION_OTHER_USER_CODE** = ``512`` + +The option is from user code which is not local and not in a derived class (e.g. Autoload Singletons). + +.. _class_CodeEdit_constant_LOCATION_OTHER: + +.. rst-class:: classref-enumeration-constant + +:ref:`CodeCompletionLocation` **LOCATION_OTHER** = ``1024`` + +The option is from other engine code, not covered by the other enum constants - e.g. built-in classes. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CodeEdit_property_auto_brace_completion_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **auto_brace_completion_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_brace_completion_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_auto_brace_completion_enabled**\ (\ ) + +If ``true``, uses :ref:`auto_brace_completion_pairs` to automatically insert the closing brace when the opening brace is inserted by typing or autocompletion. Also automatically removes the closing brace when using backspace on the opening brace. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_auto_brace_completion_highlight_matching: + +.. rst-class:: classref-property + +:ref:`bool` **auto_brace_completion_highlight_matching** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_highlight_matching_braces_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_highlight_matching_braces_enabled**\ (\ ) + +If ``true``, highlights brace pairs when the caret is on either one, using :ref:`auto_brace_completion_pairs`. If matching, the pairs will be underlined. If a brace is unmatched, it is colored with :ref:`brace_mismatch_color`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_auto_brace_completion_pairs: + +.. rst-class:: classref-property + +:ref:`Dictionary` **auto_brace_completion_pairs** = ``{ "\"": "\"", "'": "'", "(": ")", "[": "]", "{": "}" }`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_brace_completion_pairs**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_auto_brace_completion_pairs**\ (\ ) + +Sets the brace pairs to be autocompleted. For each entry in the dictionary, the key is the opening brace and the value is the closing brace that matches it. A brace is a :ref:`String` made of symbols. See :ref:`auto_brace_completion_enabled` and :ref:`auto_brace_completion_highlight_matching`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_code_completion_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **code_completion_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_code_completion_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_code_completion_enabled**\ (\ ) + +If ``true``, the :ref:`ProjectSettings.input/ui_text_completion_query` action requests code completion. To handle it, see :ref:`_request_code_completion()` or :ref:`code_completion_requested`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_code_completion_prefixes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`String`\] **code_completion_prefixes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_code_completion_prefixes**\ (\ value\: :ref:`Array`\[:ref:`String`\]\ ) +- :ref:`Array`\[:ref:`String`\] **get_code_completion_prefixes**\ (\ ) + +Sets prefixes that will trigger code completion. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_delimiter_comments: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`String`\] **delimiter_comments** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_comment_delimiters**\ (\ value\: :ref:`Array`\[:ref:`String`\]\ ) +- :ref:`Array`\[:ref:`String`\] **get_comment_delimiters**\ (\ ) + +Sets the comment delimiters. All existing comment delimiters will be removed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_delimiter_strings: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`String`\] **delimiter_strings** = ``["' '", "\" \""]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_string_delimiters**\ (\ value\: :ref:`Array`\[:ref:`String`\]\ ) +- :ref:`Array`\[:ref:`String`\] **get_string_delimiters**\ (\ ) + +Sets the string delimiters. All existing string delimiters will be removed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_gutters_draw_bookmarks: + +.. rst-class:: classref-property + +:ref:`bool` **gutters_draw_bookmarks** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_draw_bookmarks_gutter**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_drawing_bookmarks_gutter**\ (\ ) + +If ``true``, bookmarks are drawn in the gutter. This gutter is shared with breakpoints and executing lines. See :ref:`set_line_as_bookmarked()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_gutters_draw_breakpoints_gutter: + +.. rst-class:: classref-property + +:ref:`bool` **gutters_draw_breakpoints_gutter** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_draw_breakpoints_gutter**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_drawing_breakpoints_gutter**\ (\ ) + +If ``true``, breakpoints are drawn in the gutter. This gutter is shared with bookmarks and executing lines. Clicking the gutter will toggle the breakpoint for the line, see :ref:`set_line_as_breakpoint()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_gutters_draw_executing_lines: + +.. rst-class:: classref-property + +:ref:`bool` **gutters_draw_executing_lines** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_draw_executing_lines_gutter**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_drawing_executing_lines_gutter**\ (\ ) + +If ``true``, executing lines are marked in the gutter. This gutter is shared with breakpoints and bookmarks. See :ref:`set_line_as_executing()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_gutters_draw_fold_gutter: + +.. rst-class:: classref-property + +:ref:`bool` **gutters_draw_fold_gutter** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_draw_fold_gutter**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_drawing_fold_gutter**\ (\ ) + +If ``true``, the fold gutter is drawn. In this gutter, the :ref:`can_fold_code_region` icon is drawn for each foldable line (see :ref:`can_fold_line()`) and the :ref:`folded_code_region` icon is drawn for each folded line (see :ref:`is_line_folded()`). These icons can be clicked to toggle the fold state, see :ref:`toggle_foldable_line()`. :ref:`line_folding` must be ``true`` to show icons. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_gutters_draw_line_numbers: + +.. rst-class:: classref-property + +:ref:`bool` **gutters_draw_line_numbers** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_draw_line_numbers**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_draw_line_numbers_enabled**\ (\ ) + +If ``true``, the line number gutter is drawn. Line numbers start at ``1`` and are incremented for each line of text. Clicking and dragging in the line number gutter will select entire lines of text. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_gutters_line_numbers_min_digits: + +.. rst-class:: classref-property + +:ref:`int` **gutters_line_numbers_min_digits** = ``3`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_line_numbers_min_digits**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_line_numbers_min_digits**\ (\ ) + +The minimum width in digits reserved for the line number gutter. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_gutters_zero_pad_line_numbers: + +.. rst-class:: classref-property + +:ref:`bool` **gutters_zero_pad_line_numbers** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_line_numbers_zero_padded**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_line_numbers_zero_padded**\ (\ ) + +If ``true``, line numbers drawn in the gutter are zero padded based on the total line count. Requires :ref:`gutters_draw_line_numbers` to be set to ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_indent_automatic: + +.. rst-class:: classref-property + +:ref:`bool` **indent_automatic** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_indent_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_auto_indent_enabled**\ (\ ) + +If ``true``, an extra indent is automatically inserted when a new line is added and a prefix in :ref:`indent_automatic_prefixes` is found. If a brace pair opening key is found, the matching closing brace will be moved to another new line (see :ref:`auto_brace_completion_pairs`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_indent_automatic_prefixes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`String`\] **indent_automatic_prefixes** = ``[":", "{", "[", "("]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_indent_prefixes**\ (\ value\: :ref:`Array`\[:ref:`String`\]\ ) +- :ref:`Array`\[:ref:`String`\] **get_auto_indent_prefixes**\ (\ ) + +Prefixes to trigger an automatic indent. Used when :ref:`indent_automatic` is set to ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_indent_size: + +.. rst-class:: classref-property + +:ref:`int` **indent_size** = ``4`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_indent_size**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_indent_size**\ (\ ) + +Size of the tabulation indent (one :kbd:`Tab` press) in characters. If :ref:`indent_use_spaces` is enabled the number of spaces to use. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_indent_use_spaces: + +.. rst-class:: classref-property + +:ref:`bool` **indent_use_spaces** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_indent_using_spaces**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_indent_using_spaces**\ (\ ) + +Use spaces instead of tabs for indentation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_line_folding: + +.. rst-class:: classref-property + +:ref:`bool` **line_folding** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_line_folding_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_line_folding_enabled**\ (\ ) + +If ``true``, lines can be folded. Otherwise, line folding methods like :ref:`fold_line()` will not work and :ref:`can_fold_line()` will always return ``false``. See :ref:`gutters_draw_fold_gutter`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_line_length_guidelines: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`int`\] **line_length_guidelines** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_line_length_guidelines**\ (\ value\: :ref:`Array`\[:ref:`int`\]\ ) +- :ref:`Array`\[:ref:`int`\] **get_line_length_guidelines**\ (\ ) + +Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is drawn more prominently. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_symbol_lookup_on_click: + +.. rst-class:: classref-property + +:ref:`bool` **symbol_lookup_on_click** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_symbol_lookup_on_click_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_symbol_lookup_on_click_enabled**\ (\ ) + +Set when a validated word from :ref:`symbol_validate` is clicked, the :ref:`symbol_lookup` should be emitted. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_symbol_tooltip_on_hover: + +.. rst-class:: classref-property + +:ref:`bool` **symbol_tooltip_on_hover** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_symbol_tooltip_on_hover_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_symbol_tooltip_on_hover_enabled**\ (\ ) + +If ``true``, the :ref:`symbol_hovered` signal is emitted when hovering over a word. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CodeEdit_private_method__confirm_code_completion: + +.. rst-class:: classref-method + +|void| **_confirm_code_completion**\ (\ replace\: :ref:`bool`\ ) |virtual| :ref:`🔗` + +Override this method to define how the selected entry should be inserted. If ``replace`` is ``true``, any existing text should be replaced. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_private_method__filter_code_completion_candidates: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Dictionary`\] **_filter_code_completion_candidates**\ (\ candidates\: :ref:`Array`\[:ref:`Dictionary`\]\ ) |virtual| |const| :ref:`🔗` + +Override this method to define what items in ``candidates`` should be displayed. + +Both ``candidates`` and the return is an :ref:`Array` of :ref:`Dictionary`, see :ref:`get_code_completion_option()` for :ref:`Dictionary` content. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_private_method__request_code_completion: + +.. rst-class:: classref-method + +|void| **_request_code_completion**\ (\ force\: :ref:`bool`\ ) |virtual| :ref:`🔗` + +Override this method to define what happens when the user requests code completion. If ``force`` is ``true``, any checks should be bypassed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_add_auto_brace_completion_pair: + +.. rst-class:: classref-method + +|void| **add_auto_brace_completion_pair**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`\ ) :ref:`🔗` + +Adds a brace pair. + +Both the start and end keys must be symbols. Only the start key has to be unique. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_add_code_completion_option: + +.. rst-class:: classref-method + +|void| **add_code_completion_option**\ (\ type\: :ref:`CodeCompletionKind`, display_text\: :ref:`String`, insert_text\: :ref:`String`, text_color\: :ref:`Color` = Color(1, 1, 1, 1), icon\: :ref:`Resource` = null, value\: :ref:`Variant` = null, location\: :ref:`int` = 1024\ ) :ref:`🔗` + +Submits an item to the queue of potential candidates for the autocomplete menu. Call :ref:`update_code_completion_options()` to update the list. + +\ ``location`` indicates location of the option relative to the location of the code completion query. See :ref:`CodeCompletionLocation` for how to set this value. + +\ **Note:** This list will replace all current candidates. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_add_comment_delimiter: + +.. rst-class:: classref-method + +|void| **add_comment_delimiter**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, line_only\: :ref:`bool` = false\ ) :ref:`🔗` + +Adds a comment delimiter from ``start_key`` to ``end_key``. Both keys should be symbols, and ``start_key`` must not be shared with other delimiters. + +If ``line_only`` is ``true`` or ``end_key`` is an empty :ref:`String`, the region does not carry over to the next line. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_add_string_delimiter: + +.. rst-class:: classref-method + +|void| **add_string_delimiter**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, line_only\: :ref:`bool` = false\ ) :ref:`🔗` + +Defines a string delimiter from ``start_key`` to ``end_key``. Both keys should be symbols, and ``start_key`` must not be shared with other delimiters. + +If ``line_only`` is ``true`` or ``end_key`` is an empty :ref:`String`, the region does not carry over to the next line. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_can_fold_line: + +.. rst-class:: classref-method + +:ref:`bool` **can_fold_line**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given line is foldable. A line is foldable if it is the start of a valid code region (see :ref:`get_code_region_start_tag()`), if it is the start of a comment or string block, or if the next non-empty line is more indented (see :ref:`TextEdit.get_indent_level()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_cancel_code_completion: + +.. rst-class:: classref-method + +|void| **cancel_code_completion**\ (\ ) :ref:`🔗` + +Cancels the autocomplete menu. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_clear_bookmarked_lines: + +.. rst-class:: classref-method + +|void| **clear_bookmarked_lines**\ (\ ) :ref:`🔗` + +Clears all bookmarked lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_clear_breakpointed_lines: + +.. rst-class:: classref-method + +|void| **clear_breakpointed_lines**\ (\ ) :ref:`🔗` + +Clears all breakpointed lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_clear_comment_delimiters: + +.. rst-class:: classref-method + +|void| **clear_comment_delimiters**\ (\ ) :ref:`🔗` + +Removes all comment delimiters. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_clear_executing_lines: + +.. rst-class:: classref-method + +|void| **clear_executing_lines**\ (\ ) :ref:`🔗` + +Clears all executed lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_clear_string_delimiters: + +.. rst-class:: classref-method + +|void| **clear_string_delimiters**\ (\ ) :ref:`🔗` + +Removes all string delimiters. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_confirm_code_completion: + +.. rst-class:: classref-method + +|void| **confirm_code_completion**\ (\ replace\: :ref:`bool` = false\ ) :ref:`🔗` + +Inserts the selected entry into the text. If ``replace`` is ``true``, any existing text is replaced rather than merged. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_convert_indent: + +.. rst-class:: classref-method + +|void| **convert_indent**\ (\ from_line\: :ref:`int` = -1, to_line\: :ref:`int` = -1\ ) :ref:`🔗` + +Converts the indents of lines between ``from_line`` and ``to_line`` to tabs or spaces as set by :ref:`indent_use_spaces`. + +Values of ``-1`` convert the entire text. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_create_code_region: + +.. rst-class:: classref-method + +|void| **create_code_region**\ (\ ) :ref:`🔗` + +Creates a new code region with the selection. At least one single line comment delimiter have to be defined (see :ref:`add_comment_delimiter()`). + +A code region is a part of code that is highlighted when folded and can help organize your script. + +Code region start and end tags can be customized (see :ref:`set_code_region_tags()`). + +Code regions are delimited using start and end tags (respectively ``region`` and ``endregion`` by default) preceded by one line comment delimiter. (eg. ``#region`` and ``#endregion``) + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_delete_lines: + +.. rst-class:: classref-method + +|void| **delete_lines**\ (\ ) :ref:`🔗` + +Deletes all lines that are selected or have a caret on them. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_do_indent: + +.. rst-class:: classref-method + +|void| **do_indent**\ (\ ) :ref:`🔗` + +If there is no selection, indentation is inserted at the caret. Otherwise, the selected lines are indented like :ref:`indent_lines()`. Equivalent to the :ref:`ProjectSettings.input/ui_text_indent` action. The indentation characters used depend on :ref:`indent_use_spaces` and :ref:`indent_size`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_duplicate_lines: + +.. rst-class:: classref-method + +|void| **duplicate_lines**\ (\ ) :ref:`🔗` + +Duplicates all lines currently selected with any caret. Duplicates the entire line beneath the current one no matter where the caret is within the line. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_duplicate_selection: + +.. rst-class:: classref-method + +|void| **duplicate_selection**\ (\ ) :ref:`🔗` + +Duplicates all selected text and duplicates all lines with a caret on them. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_fold_all_lines: + +.. rst-class:: classref-method + +|void| **fold_all_lines**\ (\ ) :ref:`🔗` + +Folds all lines that are possible to be folded (see :ref:`can_fold_line()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_fold_line: + +.. rst-class:: classref-method + +|void| **fold_line**\ (\ line\: :ref:`int`\ ) :ref:`🔗` + +Folds the given line, if possible (see :ref:`can_fold_line()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_auto_brace_completion_close_key: + +.. rst-class:: classref-method + +:ref:`String` **get_auto_brace_completion_close_key**\ (\ open_key\: :ref:`String`\ ) |const| :ref:`🔗` + +Gets the matching auto brace close key for ``open_key``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_bookmarked_lines: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **get_bookmarked_lines**\ (\ ) |const| :ref:`🔗` + +Gets all bookmarked lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_breakpointed_lines: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **get_breakpointed_lines**\ (\ ) |const| :ref:`🔗` + +Gets all breakpointed lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_code_completion_option: + +.. rst-class:: classref-method + +:ref:`Dictionary` **get_code_completion_option**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Gets the completion option at ``index``. The return :ref:`Dictionary` has the following key-values: + +\ ``kind``: :ref:`CodeCompletionKind`\ + +\ ``display_text``: Text that is shown on the autocomplete menu. + +\ ``insert_text``: Text that is to be inserted when this item is selected. + +\ ``font_color``: Color of the text on the autocomplete menu. + +\ ``icon``: Icon to draw on the autocomplete menu. + +\ ``default_value``: Value of the symbol. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_code_completion_options: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Dictionary`\] **get_code_completion_options**\ (\ ) |const| :ref:`🔗` + +Gets all completion options, see :ref:`get_code_completion_option()` for return content. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_code_completion_selected_index: + +.. rst-class:: classref-method + +:ref:`int` **get_code_completion_selected_index**\ (\ ) |const| :ref:`🔗` + +Gets the index of the current selected completion option. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_code_region_end_tag: + +.. rst-class:: classref-method + +:ref:`String` **get_code_region_end_tag**\ (\ ) |const| :ref:`🔗` + +Returns the code region end tag (without comment delimiter). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_code_region_start_tag: + +.. rst-class:: classref-method + +:ref:`String` **get_code_region_start_tag**\ (\ ) |const| :ref:`🔗` + +Returns the code region start tag (without comment delimiter). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_delimiter_end_key: + +.. rst-class:: classref-method + +:ref:`String` **get_delimiter_end_key**\ (\ delimiter_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Gets the end key for a string or comment region index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_delimiter_end_position: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_delimiter_end_position**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| :ref:`🔗` + +If ``line`` ``column`` is in a string or comment, returns the end position of the region. If not or no end could be found, both :ref:`Vector2` values will be ``-1``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_delimiter_start_key: + +.. rst-class:: classref-method + +:ref:`String` **get_delimiter_start_key**\ (\ delimiter_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Gets the start key for a string or comment region index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_delimiter_start_position: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_delimiter_start_position**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| :ref:`🔗` + +If ``line`` ``column`` is in a string or comment, returns the start position of the region. If not or no start could be found, both :ref:`Vector2` values will be ``-1``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_executing_lines: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **get_executing_lines**\ (\ ) |const| :ref:`🔗` + +Gets all executing lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_folded_lines: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`int`\] **get_folded_lines**\ (\ ) |const| :ref:`🔗` + +Returns all lines that are currently folded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_text_for_code_completion: + +.. rst-class:: classref-method + +:ref:`String` **get_text_for_code_completion**\ (\ ) |const| :ref:`🔗` + +Returns the full text with char ``0xFFFF`` at the caret location. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_text_for_symbol_lookup: + +.. rst-class:: classref-method + +:ref:`String` **get_text_for_symbol_lookup**\ (\ ) |const| :ref:`🔗` + +Returns the full text with char ``0xFFFF`` at the cursor location. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_get_text_with_cursor_char: + +.. rst-class:: classref-method + +:ref:`String` **get_text_with_cursor_char**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the full text with char ``0xFFFF`` at the specified location. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_has_auto_brace_completion_close_key: + +.. rst-class:: classref-method + +:ref:`bool` **has_auto_brace_completion_close_key**\ (\ close_key\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns ``true`` if close key ``close_key`` exists. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_has_auto_brace_completion_open_key: + +.. rst-class:: classref-method + +:ref:`bool` **has_auto_brace_completion_open_key**\ (\ open_key\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns ``true`` if open key ``open_key`` exists. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_has_comment_delimiter: + +.. rst-class:: classref-method + +:ref:`bool` **has_comment_delimiter**\ (\ start_key\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns ``true`` if comment ``start_key`` exists. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_has_string_delimiter: + +.. rst-class:: classref-method + +:ref:`bool` **has_string_delimiter**\ (\ start_key\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns ``true`` if string ``start_key`` exists. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_indent_lines: + +.. rst-class:: classref-method + +|void| **indent_lines**\ (\ ) :ref:`🔗` + +Indents all lines that are selected or have a caret on them. Uses spaces or a tab depending on :ref:`indent_use_spaces`. See :ref:`unindent_lines()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_is_in_comment: + +.. rst-class:: classref-method + +:ref:`int` **is_in_comment**\ (\ line\: :ref:`int`, column\: :ref:`int` = -1\ ) |const| :ref:`🔗` + +Returns delimiter index if ``line`` ``column`` is in a comment. If ``column`` is not provided, will return delimiter index if the entire ``line`` is a comment. Otherwise ``-1``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_is_in_string: + +.. rst-class:: classref-method + +:ref:`int` **is_in_string**\ (\ line\: :ref:`int`, column\: :ref:`int` = -1\ ) |const| :ref:`🔗` + +Returns the delimiter index if ``line`` ``column`` is in a string. If ``column`` is not provided, will return the delimiter index if the entire ``line`` is a string. Otherwise ``-1``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_is_line_bookmarked: + +.. rst-class:: classref-method + +:ref:`bool` **is_line_bookmarked**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given line is bookmarked. See :ref:`set_line_as_bookmarked()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_is_line_breakpointed: + +.. rst-class:: classref-method + +:ref:`bool` **is_line_breakpointed**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given line is breakpointed. See :ref:`set_line_as_breakpoint()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_is_line_code_region_end: + +.. rst-class:: classref-method + +:ref:`bool` **is_line_code_region_end**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given line is a code region end. See :ref:`set_code_region_tags()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_is_line_code_region_start: + +.. rst-class:: classref-method + +:ref:`bool` **is_line_code_region_start**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given line is a code region start. See :ref:`set_code_region_tags()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_is_line_executing: + +.. rst-class:: classref-method + +:ref:`bool` **is_line_executing**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given line is marked as executing. See :ref:`set_line_as_executing()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_is_line_folded: + +.. rst-class:: classref-method + +:ref:`bool` **is_line_folded**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given line is folded. See :ref:`fold_line()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_move_lines_down: + +.. rst-class:: classref-method + +|void| **move_lines_down**\ (\ ) :ref:`🔗` + +Moves all lines down that are selected or have a caret on them. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_move_lines_up: + +.. rst-class:: classref-method + +|void| **move_lines_up**\ (\ ) :ref:`🔗` + +Moves all lines up that are selected or have a caret on them. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_remove_comment_delimiter: + +.. rst-class:: classref-method + +|void| **remove_comment_delimiter**\ (\ start_key\: :ref:`String`\ ) :ref:`🔗` + +Removes the comment delimiter with ``start_key``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_remove_string_delimiter: + +.. rst-class:: classref-method + +|void| **remove_string_delimiter**\ (\ start_key\: :ref:`String`\ ) :ref:`🔗` + +Removes the string delimiter with ``start_key``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_request_code_completion: + +.. rst-class:: classref-method + +|void| **request_code_completion**\ (\ force\: :ref:`bool` = false\ ) :ref:`🔗` + +Emits :ref:`code_completion_requested`, if ``force`` is ``true`` will bypass all checks. Otherwise will check that the caret is in a word or in front of a prefix. Will ignore the request if all current options are of type file path, node path, or signal. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_set_code_completion_selected_index: + +.. rst-class:: classref-method + +|void| **set_code_completion_selected_index**\ (\ index\: :ref:`int`\ ) :ref:`🔗` + +Sets the current selected completion option. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_set_code_hint: + +.. rst-class:: classref-method + +|void| **set_code_hint**\ (\ code_hint\: :ref:`String`\ ) :ref:`🔗` + +Sets the code hint text. Pass an empty string to clear. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_set_code_hint_draw_below: + +.. rst-class:: classref-method + +|void| **set_code_hint_draw_below**\ (\ draw_below\: :ref:`bool`\ ) :ref:`🔗` + +If ``true``, the code hint will draw below the main caret. If ``false``, the code hint will draw above the main caret. See :ref:`set_code_hint()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_set_code_region_tags: + +.. rst-class:: classref-method + +|void| **set_code_region_tags**\ (\ start\: :ref:`String` = "region", end\: :ref:`String` = "endregion"\ ) :ref:`🔗` + +Sets the code region start and end tags (without comment delimiter). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_set_line_as_bookmarked: + +.. rst-class:: classref-method + +|void| **set_line_as_bookmarked**\ (\ line\: :ref:`int`, bookmarked\: :ref:`bool`\ ) :ref:`🔗` + +Sets the given line as bookmarked. If ``true`` and :ref:`gutters_draw_bookmarks` is ``true``, draws the :ref:`bookmark` icon in the gutter for this line. See :ref:`get_bookmarked_lines()` and :ref:`is_line_bookmarked()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_set_line_as_breakpoint: + +.. rst-class:: classref-method + +|void| **set_line_as_breakpoint**\ (\ line\: :ref:`int`, breakpointed\: :ref:`bool`\ ) :ref:`🔗` + +Sets the given line as a breakpoint. If ``true`` and :ref:`gutters_draw_breakpoints_gutter` is ``true``, draws the :ref:`breakpoint` icon in the gutter for this line. See :ref:`get_breakpointed_lines()` and :ref:`is_line_breakpointed()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_set_line_as_executing: + +.. rst-class:: classref-method + +|void| **set_line_as_executing**\ (\ line\: :ref:`int`, executing\: :ref:`bool`\ ) :ref:`🔗` + +Sets the given line as executing. If ``true`` and :ref:`gutters_draw_executing_lines` is ``true``, draws the :ref:`executing_line` icon in the gutter for this line. See :ref:`get_executing_lines()` and :ref:`is_line_executing()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_set_symbol_lookup_word_as_valid: + +.. rst-class:: classref-method + +|void| **set_symbol_lookup_word_as_valid**\ (\ valid\: :ref:`bool`\ ) :ref:`🔗` + +Sets the symbol emitted by :ref:`symbol_validate` as a valid lookup. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_toggle_foldable_line: + +.. rst-class:: classref-method + +|void| **toggle_foldable_line**\ (\ line\: :ref:`int`\ ) :ref:`🔗` + +Toggle the folding of the code block at the given line. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_toggle_foldable_lines_at_carets: + +.. rst-class:: classref-method + +|void| **toggle_foldable_lines_at_carets**\ (\ ) :ref:`🔗` + +Toggle the folding of the code block on all lines with a caret on them. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_unfold_all_lines: + +.. rst-class:: classref-method + +|void| **unfold_all_lines**\ (\ ) :ref:`🔗` + +Unfolds all lines that are folded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_unfold_line: + +.. rst-class:: classref-method + +|void| **unfold_line**\ (\ line\: :ref:`int`\ ) :ref:`🔗` + +Unfolds the given line if it is folded or if it is hidden under a folded line. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_unindent_lines: + +.. rst-class:: classref-method + +|void| **unindent_lines**\ (\ ) :ref:`🔗` + +Unindents all lines that are selected or have a caret on them. Uses spaces or a tab depending on :ref:`indent_use_spaces`. Equivalent to the :ref:`ProjectSettings.input/ui_text_dedent` action. See :ref:`indent_lines()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_update_code_completion_options: + +.. rst-class:: classref-method + +|void| **update_code_completion_options**\ (\ force\: :ref:`bool`\ ) :ref:`🔗` + +Submits all completion options added with :ref:`add_code_completion_option()`. Will try to force the autocomplete menu to popup, if ``force`` is ``true``. + +\ **Note:** This will replace all current candidates. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Theme Property Descriptions +--------------------------- + +.. _class_CodeEdit_theme_color_bookmark_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **bookmark_color** = ``Color(0.5, 0.64, 1, 0.8)`` :ref:`🔗` + +:ref:`Color` of the bookmark icon for bookmarked lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_brace_mismatch_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **brace_mismatch_color** = ``Color(1, 0.2, 0.2, 1)`` :ref:`🔗` + +:ref:`Color` of the text to highlight mismatched braces. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_breakpoint_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **breakpoint_color** = ``Color(0.9, 0.29, 0.3, 1)`` :ref:`🔗` + +:ref:`Color` of the breakpoint icon for bookmarked lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_code_folding_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **code_folding_color** = ``Color(0.8, 0.8, 0.8, 0.8)`` :ref:`🔗` + +:ref:`Color` for all icons related to line folding. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_completion_background_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **completion_background_color** = ``Color(0.17, 0.16, 0.2, 1)`` :ref:`🔗` + +Sets the background :ref:`Color` for the code completion popup. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_completion_existing_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **completion_existing_color** = ``Color(0.87, 0.87, 0.87, 0.13)`` :ref:`🔗` + +Background highlight :ref:`Color` for matching text in code completion options. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_completion_scroll_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **completion_scroll_color** = ``Color(1, 1, 1, 0.29)`` :ref:`🔗` + +:ref:`Color` of the scrollbar in the code completion popup. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_completion_scroll_hovered_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **completion_scroll_hovered_color** = ``Color(1, 1, 1, 0.4)`` :ref:`🔗` + +:ref:`Color` of the scrollbar in the code completion popup when hovered. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_completion_selected_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **completion_selected_color** = ``Color(0.26, 0.26, 0.27, 1)`` :ref:`🔗` + +Background highlight :ref:`Color` for the current selected option item in the code completion popup. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_executing_line_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **executing_line_color** = ``Color(0.98, 0.89, 0.27, 1)`` :ref:`🔗` + +:ref:`Color` of the executing icon for executing lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_folded_code_region_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **folded_code_region_color** = ``Color(0.68, 0.46, 0.77, 0.2)`` :ref:`🔗` + +:ref:`Color` of background line highlight for folded code region. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_line_length_guideline_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **line_length_guideline_color** = ``Color(0.3, 0.5, 0.8, 0.1)`` :ref:`🔗` + +:ref:`Color` of the main line length guideline, secondary guidelines will have 50% alpha applied. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_color_line_number_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **line_number_color** = ``Color(0.67, 0.67, 0.67, 0.4)`` :ref:`🔗` + +Sets the :ref:`Color` of line numbers. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_constant_completion_lines: + +.. rst-class:: classref-themeproperty + +:ref:`int` **completion_lines** = ``7`` :ref:`🔗` + +Max number of options to display in the code completion popup at any one time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_constant_completion_max_width: + +.. rst-class:: classref-themeproperty + +:ref:`int` **completion_max_width** = ``50`` :ref:`🔗` + +Max width of options in the code completion popup. Options longer than this will be cut off. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_constant_completion_scroll_width: + +.. rst-class:: classref-themeproperty + +:ref:`int` **completion_scroll_width** = ``6`` :ref:`🔗` + +Width of the scrollbar in the code completion popup. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_bookmark: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **bookmark** :ref:`🔗` + +Sets a custom :ref:`Texture2D` to draw in the bookmark gutter for bookmarked lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_breakpoint: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **breakpoint** :ref:`🔗` + +Sets a custom :ref:`Texture2D` to draw in the breakpoint gutter for breakpointed lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_can_fold: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **can_fold** :ref:`🔗` + +Sets a custom :ref:`Texture2D` to draw in the line folding gutter when a line can be folded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_can_fold_code_region: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **can_fold_code_region** :ref:`🔗` + +Sets a custom :ref:`Texture2D` to draw in the line folding gutter when a code region can be folded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_completion_color_bg: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **completion_color_bg** :ref:`🔗` + +Background panel for the color preview box in autocompletion (visible when the color is translucent). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_executing_line: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **executing_line** :ref:`🔗` + +Icon to draw in the executing gutter for executing lines. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_folded: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **folded** :ref:`🔗` + +Sets a custom :ref:`Texture2D` to draw in the line folding gutter when a line is folded and can be unfolded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_folded_code_region: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **folded_code_region** :ref:`🔗` + +Sets a custom :ref:`Texture2D` to draw in the line folding gutter when a code region is folded and can be unfolded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_icon_folded_eol_icon: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **folded_eol_icon** :ref:`🔗` + +Sets a custom :ref:`Texture2D` to draw at the end of a folded line. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_theme_style_completion: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **completion** :ref:`🔗` + +:ref:`StyleBox` for the code completion popup. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_codehighlighter.rst b/classes/class_codehighlighter.rst new file mode 100644 index 00000000000..88147fd276d --- /dev/null +++ b/classes/class_codehighlighter.rst @@ -0,0 +1,399 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CodeHighlighter.xml. + +.. _class_CodeHighlighter: + +CodeHighlighter +=============== + +**Inherits:** :ref:`SyntaxHighlighter` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +A syntax highlighter intended for code. + +.. rst-class:: classref-introduction-group + +Description +----------- + +By adjusting various properties of this resource, you can change the colors of strings, comments, numbers, and other text patterns inside a :ref:`TextEdit` control. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------------+------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Dictionary` | :ref:`color_regions` | ``{}`` | + +-------------------------------------+------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`function_color` | ``Color(0, 0, 0, 1)`` | + +-------------------------------------+------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Dictionary` | :ref:`keyword_colors` | ``{}`` | + +-------------------------------------+------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Dictionary` | :ref:`member_keyword_colors` | ``{}`` | + +-------------------------------------+------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`member_variable_color` | ``Color(0, 0, 0, 1)`` | + +-------------------------------------+------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`number_color` | ``Color(0, 0, 0, 1)`` | + +-------------------------------------+------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`symbol_color` | ``Color(0, 0, 0, 1)`` | + +-------------------------------------+------------------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_color_region`\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, color\: :ref:`Color`, line_only\: :ref:`bool` = false\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_keyword_color`\ (\ keyword\: :ref:`String`, color\: :ref:`Color`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_member_keyword_color`\ (\ member_keyword\: :ref:`String`, color\: :ref:`Color`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_color_regions`\ (\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_keyword_colors`\ (\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_member_keyword_colors`\ (\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`get_keyword_color`\ (\ keyword\: :ref:`String`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`get_member_keyword_color`\ (\ member_keyword\: :ref:`String`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_color_region`\ (\ start_key\: :ref:`String`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_keyword_color`\ (\ keyword\: :ref:`String`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_member_keyword_color`\ (\ member_keyword\: :ref:`String`\ ) |const| | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_color_region`\ (\ start_key\: :ref:`String`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_keyword_color`\ (\ keyword\: :ref:`String`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_member_keyword_color`\ (\ member_keyword\: :ref:`String`\ ) | + +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CodeHighlighter_property_color_regions: + +.. rst-class:: classref-property + +:ref:`Dictionary` **color_regions** = ``{}`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_color_regions**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_color_regions**\ (\ ) + +Sets the color regions. All existing regions will be removed. The :ref:`Dictionary` key is the region start and end key, separated by a space. The value is the region color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_property_function_color: + +.. rst-class:: classref-property + +:ref:`Color` **function_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_function_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_function_color**\ (\ ) + +Sets color for functions. A function is a non-keyword string followed by a '('. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_property_keyword_colors: + +.. rst-class:: classref-property + +:ref:`Dictionary` **keyword_colors** = ``{}`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_keyword_colors**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_keyword_colors**\ (\ ) + +Sets the keyword colors. All existing keywords will be removed. The :ref:`Dictionary` key is the keyword. The value is the keyword color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_property_member_keyword_colors: + +.. rst-class:: classref-property + +:ref:`Dictionary` **member_keyword_colors** = ``{}`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_member_keyword_colors**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_member_keyword_colors**\ (\ ) + +Sets the member keyword colors. All existing member keyword will be removed. The :ref:`Dictionary` key is the member keyword. The value is the member keyword color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_property_member_variable_color: + +.. rst-class:: classref-property + +:ref:`Color` **member_variable_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_member_variable_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_member_variable_color**\ (\ ) + +Sets color for member variables. A member variable is non-keyword, non-function string proceeded with a '.'. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_property_number_color: + +.. rst-class:: classref-property + +:ref:`Color` **number_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_number_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_number_color**\ (\ ) + +Sets the color for numbers. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_property_symbol_color: + +.. rst-class:: classref-property + +:ref:`Color` **symbol_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_symbol_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_symbol_color**\ (\ ) + +Sets the color for symbols. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CodeHighlighter_method_add_color_region: + +.. rst-class:: classref-method + +|void| **add_color_region**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, color\: :ref:`Color`, line_only\: :ref:`bool` = false\ ) :ref:`🔗` + +Adds a color region (such as for comments or strings) from ``start_key`` to ``end_key``. Both keys should be symbols, and ``start_key`` must not be shared with other delimiters. + +If ``line_only`` is ``true`` or ``end_key`` is an empty :ref:`String`, the region does not carry over to the next line. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_add_keyword_color: + +.. rst-class:: classref-method + +|void| **add_keyword_color**\ (\ keyword\: :ref:`String`, color\: :ref:`Color`\ ) :ref:`🔗` + +Sets the color for a keyword. + +The keyword cannot contain any symbols except '\_'. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_add_member_keyword_color: + +.. rst-class:: classref-method + +|void| **add_member_keyword_color**\ (\ member_keyword\: :ref:`String`, color\: :ref:`Color`\ ) :ref:`🔗` + +Sets the color for a member keyword. + +The member keyword cannot contain any symbols except '\_'. + +It will not be highlighted if preceded by a '.'. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_clear_color_regions: + +.. rst-class:: classref-method + +|void| **clear_color_regions**\ (\ ) :ref:`🔗` + +Removes all color regions. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_clear_keyword_colors: + +.. rst-class:: classref-method + +|void| **clear_keyword_colors**\ (\ ) :ref:`🔗` + +Removes all keywords. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_clear_member_keyword_colors: + +.. rst-class:: classref-method + +|void| **clear_member_keyword_colors**\ (\ ) :ref:`🔗` + +Removes all member keywords. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_get_keyword_color: + +.. rst-class:: classref-method + +:ref:`Color` **get_keyword_color**\ (\ keyword\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns the color for a keyword. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_get_member_keyword_color: + +.. rst-class:: classref-method + +:ref:`Color` **get_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns the color for a member keyword. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_has_color_region: + +.. rst-class:: classref-method + +:ref:`bool` **has_color_region**\ (\ start_key\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns ``true`` if the start key exists, else ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_has_keyword_color: + +.. rst-class:: classref-method + +:ref:`bool` **has_keyword_color**\ (\ keyword\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns ``true`` if the keyword exists, else ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_has_member_keyword_color: + +.. rst-class:: classref-method + +:ref:`bool` **has_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) |const| :ref:`🔗` + +Returns ``true`` if the member keyword exists, else ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_remove_color_region: + +.. rst-class:: classref-method + +|void| **remove_color_region**\ (\ start_key\: :ref:`String`\ ) :ref:`🔗` + +Removes the color region that uses that start key. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_remove_keyword_color: + +.. rst-class:: classref-method + +|void| **remove_keyword_color**\ (\ keyword\: :ref:`String`\ ) :ref:`🔗` + +Removes the keyword. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeHighlighter_method_remove_member_keyword_color: + +.. rst-class:: classref-method + +|void| **remove_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) :ref:`🔗` + +Removes the member keyword. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_collisionobject.rst b/classes/class_collisionobject.rst deleted file mode 100644 index 08e09cc0289..00000000000 --- a/classes/class_collisionobject.rst +++ /dev/null @@ -1,265 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CollisionObject.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_CollisionObject: - -CollisionObject -=============== - -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -**Inherited By:** :ref:`Area`, :ref:`PhysicsBody` - -Base node for collision objects. - -Description ------------ - -CollisionObject is the base class for physics objects. It can hold any number of collision :ref:`Shape`\ s. Each shape must be assigned to a *shape owner*. The CollisionObject can have any number of shape owners. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. - -Properties ----------- - -+-------------------------+------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`input_capture_on_drag` | ``false`` | -+-------------------------+------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`input_ray_pickable` | ``true`` | -+-------------------------+------------------------------------------------------------------------------------+-----------+ - -Methods -------- - -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`_input_event` **(** :ref:`Object` camera, :ref:`InputEvent` event, :ref:`Vector3` click_position, :ref:`Vector3` click_normal, :ref:`int` shape_idx **)** virtual | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`create_shape_owner` **(** :ref:`Object` owner **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`RID` | :ref:`get_rid` **(** **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_shape_owners` **(** **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_shape_owner_disabled` **(** :ref:`int` owner_id **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_shape_owner` **(** :ref:`int` owner_id **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`shape_find_owner` **(** :ref:`int` shape_index **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_add_shape` **(** :ref:`int` owner_id, :ref:`Shape` shape **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_clear_shapes` **(** :ref:`int` owner_id **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Object` | :ref:`shape_owner_get_owner` **(** :ref:`int` owner_id **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Shape` | :ref:`shape_owner_get_shape` **(** :ref:`int` owner_id, :ref:`int` shape_id **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`shape_owner_get_shape_count` **(** :ref:`int` owner_id **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`shape_owner_get_shape_index` **(** :ref:`int` owner_id, :ref:`int` shape_id **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform` | :ref:`shape_owner_get_transform` **(** :ref:`int` owner_id **)** const | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_remove_shape` **(** :ref:`int` owner_id, :ref:`int` shape_id **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_set_disabled` **(** :ref:`int` owner_id, :ref:`bool` disabled **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_set_transform` **(** :ref:`int` owner_id, :ref:`Transform` transform **)** | -+-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -Signals -------- - -.. _class_CollisionObject_signal_input_event: - -- **input_event** **(** :ref:`Node` camera, :ref:`InputEvent` event, :ref:`Vector3` click_position, :ref:`Vector3` click_normal, :ref:`int` shape_idx **)** - -Emitted when :ref:`_input_event` receives an event. See its description for details. - ----- - -.. _class_CollisionObject_signal_mouse_entered: - -- **mouse_entered** **(** **)** - -Emitted when the mouse pointer enters any of this object's shapes. - ----- - -.. _class_CollisionObject_signal_mouse_exited: - -- **mouse_exited** **(** **)** - -Emitted when the mouse pointer exits all this object's shapes. - -Property Descriptions ---------------------- - -.. _class_CollisionObject_property_input_capture_on_drag: - -- :ref:`bool` **input_capture_on_drag** - -+-----------+----------------------------------+ -| *Default* | ``false`` | -+-----------+----------------------------------+ -| *Setter* | set_capture_input_on_drag(value) | -+-----------+----------------------------------+ -| *Getter* | get_capture_input_on_drag() | -+-----------+----------------------------------+ - -If ``true``, the ``CollisionObject`` will continue to receive input events as the mouse is dragged across its shapes. - ----- - -.. _class_CollisionObject_property_input_ray_pickable: - -- :ref:`bool` **input_ray_pickable** - -+-----------+-------------------------+ -| *Default* | ``true`` | -+-----------+-------------------------+ -| *Setter* | set_ray_pickable(value) | -+-----------+-------------------------+ -| *Getter* | is_ray_pickable() | -+-----------+-------------------------+ - -If ``true``, the ``CollisionObject``'s shapes will respond to :ref:`RayCast`\ s. - -Method Descriptions -------------------- - -.. _class_CollisionObject_method__input_event: - -- void **_input_event** **(** :ref:`Object` camera, :ref:`InputEvent` event, :ref:`Vector3` click_position, :ref:`Vector3` click_normal, :ref:`int` shape_idx **)** virtual - -Accepts unhandled :ref:`InputEvent`\ s. ``click_position`` is the clicked location in world space and ``click_normal`` is the normal vector extending from the clicked surface of the :ref:`Shape` at ``shape_idx``. Connect to the ``input_event`` signal to easily pick up these events. - ----- - -.. _class_CollisionObject_method_create_shape_owner: - -- :ref:`int` **create_shape_owner** **(** :ref:`Object` owner **)** - -Creates a new shape owner for the given object. Returns ``owner_id`` of the new owner for future reference. - ----- - -.. _class_CollisionObject_method_get_rid: - -- :ref:`RID` **get_rid** **(** **)** const - -Returns the object's :ref:`RID`. - ----- - -.. _class_CollisionObject_method_get_shape_owners: - -- :ref:`Array` **get_shape_owners** **(** **)** - -Returns an :ref:`Array` of ``owner_id`` identifiers. You can use these ids in other methods that take ``owner_id`` as an argument. - ----- - -.. _class_CollisionObject_method_is_shape_owner_disabled: - -- :ref:`bool` **is_shape_owner_disabled** **(** :ref:`int` owner_id **)** const - -If ``true``, the shape owner and its shapes are disabled. - ----- - -.. _class_CollisionObject_method_remove_shape_owner: - -- void **remove_shape_owner** **(** :ref:`int` owner_id **)** - -Removes the given shape owner. - ----- - -.. _class_CollisionObject_method_shape_find_owner: - -- :ref:`int` **shape_find_owner** **(** :ref:`int` shape_index **)** const - -Returns the ``owner_id`` of the given shape. - ----- - -.. _class_CollisionObject_method_shape_owner_add_shape: - -- void **shape_owner_add_shape** **(** :ref:`int` owner_id, :ref:`Shape` shape **)** - -Adds a :ref:`Shape` to the shape owner. - ----- - -.. _class_CollisionObject_method_shape_owner_clear_shapes: - -- void **shape_owner_clear_shapes** **(** :ref:`int` owner_id **)** - -Removes all shapes from the shape owner. - ----- - -.. _class_CollisionObject_method_shape_owner_get_owner: - -- :ref:`Object` **shape_owner_get_owner** **(** :ref:`int` owner_id **)** const - -Returns the parent object of the given shape owner. - ----- - -.. _class_CollisionObject_method_shape_owner_get_shape: - -- :ref:`Shape` **shape_owner_get_shape** **(** :ref:`int` owner_id, :ref:`int` shape_id **)** const - -Returns the :ref:`Shape` with the given id from the given shape owner. - ----- - -.. _class_CollisionObject_method_shape_owner_get_shape_count: - -- :ref:`int` **shape_owner_get_shape_count** **(** :ref:`int` owner_id **)** const - -Returns the number of shapes the given shape owner contains. - ----- - -.. _class_CollisionObject_method_shape_owner_get_shape_index: - -- :ref:`int` **shape_owner_get_shape_index** **(** :ref:`int` owner_id, :ref:`int` shape_id **)** const - -Returns the child index of the :ref:`Shape` with the given id from the given shape owner. - ----- - -.. _class_CollisionObject_method_shape_owner_get_transform: - -- :ref:`Transform` **shape_owner_get_transform** **(** :ref:`int` owner_id **)** const - -Returns the shape owner's :ref:`Transform`. - ----- - -.. _class_CollisionObject_method_shape_owner_remove_shape: - -- void **shape_owner_remove_shape** **(** :ref:`int` owner_id, :ref:`int` shape_id **)** - -Removes a shape from the given shape owner. - ----- - -.. _class_CollisionObject_method_shape_owner_set_disabled: - -- void **shape_owner_set_disabled** **(** :ref:`int` owner_id, :ref:`bool` disabled **)** - -If ``true``, disables the given shape owner. - ----- - -.. _class_CollisionObject_method_shape_owner_set_transform: - -- void **shape_owner_set_transform** **(** :ref:`int` owner_id, :ref:`Transform` transform **)** - -Sets the :ref:`Transform` of the given shape owner. - diff --git a/classes/class_collisionobject2d.rst b/classes/class_collisionobject2d.rst index f0b84ab404a..f17ca4c4dba 100644 --- a/classes/class_collisionobject2d.rst +++ b/classes/class_collisionobject2d.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CollisionObject2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CollisionObject2D.xml. .. _class_CollisionObject2D: @@ -13,275 +14,672 @@ CollisionObject2D **Inherited By:** :ref:`Area2D`, :ref:`PhysicsBody2D` -Base node for 2D collision objects. +Abstract base class for 2D physics objects. + +.. rst-class:: classref-introduction-group Description ----------- -CollisionObject2D is the base class for 2D physics objects. It can hold any number of 2D collision :ref:`Shape2D`\ s. Each shape must be assigned to a *shape owner*. The CollisionObject2D can have any number of shape owners. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. +Abstract base class for 2D physics objects. **CollisionObject2D** can hold any number of :ref:`Shape2D`\ s for collision. Each shape must be assigned to a *shape owner*. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. + +\ **Note:** Only collisions between objects within the same canvas (:ref:`Viewport` canvas or :ref:`CanvasLayer`) are supported. The behavior of collisions between objects in different canvases is undefined. + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------+------------------------------------------------------------------------+----------+ -| :ref:`bool` | :ref:`input_pickable` | ``true`` | -+-------------------------+------------------------------------------------------------------------+----------+ +.. table:: + :widths: auto + + +--------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`int` | :ref:`collision_layer` | ``1`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`int` | :ref:`collision_mask` | ``1`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`collision_priority` | ``1.0`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`DisableMode` | :ref:`disable_mode` | ``0`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`bool` | :ref:`input_pickable` | ``true`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------+----------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`_input_event` **(** :ref:`Object` viewport, :ref:`InputEvent` event, :ref:`int` shape_idx **)** virtual | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`create_shape_owner` **(** :ref:`Object` owner **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`RID` | :ref:`get_rid` **(** **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_shape_owner_one_way_collision_margin` **(** :ref:`int` owner_id **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_shape_owners` **(** **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_shape_owner_disabled` **(** :ref:`int` owner_id **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_shape_owner_one_way_collision_enabled` **(** :ref:`int` owner_id **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_shape_owner` **(** :ref:`int` owner_id **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`shape_find_owner` **(** :ref:`int` shape_index **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_add_shape` **(** :ref:`int` owner_id, :ref:`Shape2D` shape **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_clear_shapes` **(** :ref:`int` owner_id **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Object` | :ref:`shape_owner_get_owner` **(** :ref:`int` owner_id **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Shape2D` | :ref:`shape_owner_get_shape` **(** :ref:`int` owner_id, :ref:`int` shape_id **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`shape_owner_get_shape_count` **(** :ref:`int` owner_id **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`shape_owner_get_shape_index` **(** :ref:`int` owner_id, :ref:`int` shape_id **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Transform2D` | :ref:`shape_owner_get_transform` **(** :ref:`int` owner_id **)** const | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_remove_shape` **(** :ref:`int` owner_id, :ref:`int` shape_id **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_set_disabled` **(** :ref:`int` owner_id, :ref:`bool` disabled **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_set_one_way_collision` **(** :ref:`int` owner_id, :ref:`bool` enable **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_set_one_way_collision_margin` **(** :ref:`int` owner_id, :ref:`float` margin **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shape_owner_set_transform` **(** :ref:`int` owner_id, :ref:`Transform2D` transform **)** | -+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_input_event`\ (\ viewport\: :ref:`Viewport`, event\: :ref:`InputEvent`, shape_idx\: :ref:`int`\ ) |virtual| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_mouse_enter`\ (\ ) |virtual| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_mouse_exit`\ (\ ) |virtual| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_mouse_shape_enter`\ (\ shape_idx\: :ref:`int`\ ) |virtual| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_mouse_shape_exit`\ (\ shape_idx\: :ref:`int`\ ) |virtual| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`create_shape_owner`\ (\ owner\: :ref:`Object`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_collision_layer_value`\ (\ layer_number\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_collision_mask_value`\ (\ layer_number\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_rid`\ (\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_shape_owner_one_way_collision_margin`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`get_shape_owners`\ (\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_shape_owner_disabled`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_shape_owner_one_way_collision_enabled`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_shape_owner`\ (\ owner_id\: :ref:`int`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_collision_layer_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_collision_mask_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_find_owner`\ (\ shape_index\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_add_shape`\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape2D`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_clear_shapes`\ (\ owner_id\: :ref:`int`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Object` | :ref:`shape_owner_get_owner`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Shape2D` | :ref:`shape_owner_get_shape`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_owner_get_shape_count`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_owner_get_shape_index`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`shape_owner_get_transform`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_remove_shape`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_set_disabled`\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_set_one_way_collision`\ (\ owner_id\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_set_one_way_collision_margin`\ (\ owner_id\: :ref:`int`, margin\: :ref:`float`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_set_transform`\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform2D`\ ) | + +-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_CollisionObject2D_signal_input_event: -- **input_event** **(** :ref:`Node` viewport, :ref:`InputEvent` event, :ref:`int` shape_idx **)** +.. rst-class:: classref-signal + +**input_event**\ (\ viewport\: :ref:`Node`, event\: :ref:`InputEvent`, shape_idx\: :ref:`int`\ ) :ref:`🔗` + +Emitted when an input event occurs. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. See :ref:`_input_event()` for details. -Emitted when an input event occurs. Requires :ref:`input_pickable` to be ``true`` and at least one ``collision_layer`` bit to be set. See :ref:`_input_event` for details. +.. rst-class:: classref-item-separator ---- .. _class_CollisionObject2D_signal_mouse_entered: -- **mouse_entered** **(** **)** +.. rst-class:: classref-signal + +**mouse_entered**\ (\ ) :ref:`🔗` + +Emitted when the mouse pointer enters any of this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this signal to be emitted. + +\ **Note:** Due to the lack of continuous collision detection, this signal may not be emitted in the expected order if the mouse moves fast enough and the **CollisionObject2D**'s area is small. This signal may also not be emitted if another **CollisionObject2D** is overlapping the **CollisionObject2D** in question. -Emitted when the mouse pointer enters any of this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one ``collision_layer`` bit to be set. +.. rst-class:: classref-item-separator ---- .. _class_CollisionObject2D_signal_mouse_exited: -- **mouse_exited** **(** **)** +.. rst-class:: classref-signal + +**mouse_exited**\ (\ ) :ref:`🔗` + +Emitted when the mouse pointer exits all this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this signal to be emitted. + +\ **Note:** Due to the lack of continuous collision detection, this signal may not be emitted in the expected order if the mouse moves fast enough and the **CollisionObject2D**'s area is small. This signal may also not be emitted if another **CollisionObject2D** is overlapping the **CollisionObject2D** in question. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_signal_mouse_shape_entered: + +.. rst-class:: classref-signal + +**mouse_shape_entered**\ (\ shape_idx\: :ref:`int`\ ) :ref:`🔗` + +Emitted when the mouse pointer enters any of this object's shapes or moves from one shape to another. ``shape_idx`` is the child index of the newly entered :ref:`Shape2D`. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_signal_mouse_shape_exited: + +.. rst-class:: classref-signal + +**mouse_shape_exited**\ (\ shape_idx\: :ref:`int`\ ) :ref:`🔗` + +Emitted when the mouse pointer exits any of this object's shapes. ``shape_idx`` is the child index of the exited :ref:`Shape2D`. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_CollisionObject2D_DisableMode: + +.. rst-class:: classref-enumeration + +enum **DisableMode**: :ref:`🔗` + +.. _class_CollisionObject2D_constant_DISABLE_MODE_REMOVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DisableMode` **DISABLE_MODE_REMOVE** = ``0`` + +When :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`, remove from the physics simulation to stop all physics interactions with this **CollisionObject2D**. + +Automatically re-added to the physics simulation when the :ref:`Node` is processed again. + +.. _class_CollisionObject2D_constant_DISABLE_MODE_MAKE_STATIC: + +.. rst-class:: classref-enumeration-constant + +:ref:`DisableMode` **DISABLE_MODE_MAKE_STATIC** = ``1`` + +When :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`, make the body static. Doesn't affect :ref:`Area2D`. :ref:`PhysicsBody2D` can't be affected by forces or other bodies while static. + +Automatically set :ref:`PhysicsBody2D` back to its original mode when the :ref:`Node` is processed again. + +.. _class_CollisionObject2D_constant_DISABLE_MODE_KEEP_ACTIVE: + +.. rst-class:: classref-enumeration-constant -Emitted when the mouse pointer exits all this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one ``collision_layer`` bit to be set. +:ref:`DisableMode` **DISABLE_MODE_KEEP_ACTIVE** = ``2`` + +When :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`, do not affect the physics simulation. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- +.. _class_CollisionObject2D_property_collision_layer: + +.. rst-class:: classref-property + +:ref:`int` **collision_layer** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_collision_layer**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_collision_layer**\ (\ ) + +The physics layers this CollisionObject2D is in. Collision objects can exist in one or more of 32 different layers. See also :ref:`collision_mask`. + +\ **Note:** Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See `Collision layers and masks <../tutorials/physics/physics_introduction.html#collision-layers-and-masks>`__ in the documentation for more information. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_property_collision_mask: + +.. rst-class:: classref-property + +:ref:`int` **collision_mask** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_collision_mask**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_collision_mask**\ (\ ) + +The physics layers this CollisionObject2D scans. Collision objects can scan one or more of 32 different layers. See also :ref:`collision_layer`. + +\ **Note:** Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See `Collision layers and masks <../tutorials/physics/physics_introduction.html#collision-layers-and-masks>`__ in the documentation for more information. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_property_collision_priority: + +.. rst-class:: classref-property + +:ref:`float` **collision_priority** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_collision_priority**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_collision_priority**\ (\ ) + +The priority used to solve colliding when occurring penetration. The higher the priority is, the lower the penetration into the object will be. This can for example be used to prevent the player from breaking through the boundaries of a level. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_property_disable_mode: + +.. rst-class:: classref-property + +:ref:`DisableMode` **disable_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_disable_mode**\ (\ value\: :ref:`DisableMode`\ ) +- :ref:`DisableMode` **get_disable_mode**\ (\ ) + +Defines the behavior in physics when :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`. + +.. rst-class:: classref-item-separator + +---- + .. _class_CollisionObject2D_property_input_pickable: -- :ref:`bool` **input_pickable** +.. rst-class:: classref-property -+-----------+---------------------+ -| *Default* | ``true`` | -+-----------+---------------------+ -| *Setter* | set_pickable(value) | -+-----------+---------------------+ -| *Getter* | is_pickable() | -+-----------+---------------------+ +:ref:`bool` **input_pickable** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pickable**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_pickable**\ (\ ) + +If ``true``, this object is pickable. A pickable object can detect the mouse pointer entering/leaving, and if the mouse is inside it, report input events. Requires at least one :ref:`collision_layer` bit to be set. + +.. rst-class:: classref-section-separator + +---- -If ``true``, this object is pickable. A pickable object can detect the mouse pointer entering/leaving, and if the mouse is inside it, report input events. Requires at least one ``collision_layer`` bit to be set. +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_CollisionObject2D_method__input_event: +.. _class_CollisionObject2D_private_method__input_event: -- void **_input_event** **(** :ref:`Object` viewport, :ref:`InputEvent` event, :ref:`int` shape_idx **)** virtual +.. rst-class:: classref-method -Accepts unhandled :ref:`InputEvent`\ s. Requires :ref:`input_pickable` to be ``true``. ``shape_idx`` is the child index of the clicked :ref:`Shape2D`. Connect to the ``input_event`` signal to easily pick up these events. +|void| **_input_event**\ (\ viewport\: :ref:`Viewport`, event\: :ref:`InputEvent`, shape_idx\: :ref:`int`\ ) |virtual| :ref:`🔗` + +Accepts unhandled :ref:`InputEvent`\ s. ``shape_idx`` is the child index of the clicked :ref:`Shape2D`. Connect to :ref:`input_event` to easily pick up these events. + +\ **Note:** :ref:`_input_event()` requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_private_method__mouse_enter: + +.. rst-class:: classref-method + +|void| **_mouse_enter**\ (\ ) |virtual| :ref:`🔗` + +Called when the mouse pointer enters any of this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this function to be called. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_private_method__mouse_exit: + +.. rst-class:: classref-method + +|void| **_mouse_exit**\ (\ ) |virtual| :ref:`🔗` + +Called when the mouse pointer exits all this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this function to be called. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_private_method__mouse_shape_enter: + +.. rst-class:: classref-method + +|void| **_mouse_shape_enter**\ (\ shape_idx\: :ref:`int`\ ) |virtual| :ref:`🔗` + +Called when the mouse pointer enters any of this object's shapes or moves from one shape to another. ``shape_idx`` is the child index of the newly entered :ref:`Shape2D`. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be called. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_private_method__mouse_shape_exit: + +.. rst-class:: classref-method + +|void| **_mouse_shape_exit**\ (\ shape_idx\: :ref:`int`\ ) |virtual| :ref:`🔗` + +Called when the mouse pointer exits any of this object's shapes. ``shape_idx`` is the child index of the exited :ref:`Shape2D`. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be called. + +.. rst-class:: classref-item-separator ---- .. _class_CollisionObject2D_method_create_shape_owner: -- :ref:`int` **create_shape_owner** **(** :ref:`Object` owner **)** +.. rst-class:: classref-method + +:ref:`int` **create_shape_owner**\ (\ owner\: :ref:`Object`\ ) :ref:`🔗` Creates a new shape owner for the given object. Returns ``owner_id`` of the new owner for future reference. +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_method_get_collision_layer_value: + +.. rst-class:: classref-method + +:ref:`bool` **get_collision_layer_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether or not the specified layer of the :ref:`collision_layer` is enabled, given a ``layer_number`` between 1 and 32. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_method_get_collision_mask_value: + +.. rst-class:: classref-method + +:ref:`bool` **get_collision_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether or not the specified layer of the :ref:`collision_mask` is enabled, given a ``layer_number`` between 1 and 32. + +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_get_rid: -- :ref:`RID` **get_rid** **(** **)** const +.. rst-class:: classref-method + +:ref:`RID` **get_rid**\ (\ ) |const| :ref:`🔗` Returns the object's :ref:`RID`. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_get_shape_owner_one_way_collision_margin: -- :ref:`float` **get_shape_owner_one_way_collision_margin** **(** :ref:`int` owner_id **)** const +.. rst-class:: classref-method + +:ref:`float` **get_shape_owner_one_way_collision_margin**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the ``one_way_collision_margin`` of the shape owner identified by given ``owner_id``. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_get_shape_owners: -- :ref:`Array` **get_shape_owners** **(** **)** +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **get_shape_owners**\ (\ ) :ref:`🔗` Returns an :ref:`Array` of ``owner_id`` identifiers. You can use these ids in other methods that take ``owner_id`` as an argument. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_is_shape_owner_disabled: -- :ref:`bool` **is_shape_owner_disabled** **(** :ref:`int` owner_id **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_shape_owner_disabled**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the shape owner and its shapes are disabled. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_is_shape_owner_one_way_collision_enabled: -- :ref:`bool` **is_shape_owner_one_way_collision_enabled** **(** :ref:`int` owner_id **)** const +.. rst-class:: classref-method + +:ref:`bool` **is_shape_owner_one_way_collision_enabled**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` -Returns ``true`` if collisions for the shape owner originating from this ``CollisionObject2D`` will not be reported to collided with ``CollisionObject2D``\ s. +Returns ``true`` if collisions for the shape owner originating from this **CollisionObject2D** will not be reported to collided with **CollisionObject2D**\ s. + +.. rst-class:: classref-item-separator ---- .. _class_CollisionObject2D_method_remove_shape_owner: -- void **remove_shape_owner** **(** :ref:`int` owner_id **)** +.. rst-class:: classref-method + +|void| **remove_shape_owner**\ (\ owner_id\: :ref:`int`\ ) :ref:`🔗` Removes the given shape owner. +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_method_set_collision_layer_value: + +.. rst-class:: classref-method + +|void| **set_collision_layer_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` + +Based on ``value``, enables or disables the specified layer in the :ref:`collision_layer`, given a ``layer_number`` between 1 and 32. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject2D_method_set_collision_mask_value: + +.. rst-class:: classref-method + +|void| **set_collision_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` + +Based on ``value``, enables or disables the specified layer in the :ref:`collision_mask`, given a ``layer_number`` between 1 and 32. + +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_find_owner: -- :ref:`int` **shape_find_owner** **(** :ref:`int` shape_index **)** const +.. rst-class:: classref-method + +:ref:`int` **shape_find_owner**\ (\ shape_index\: :ref:`int`\ ) |const| :ref:`🔗` Returns the ``owner_id`` of the given shape. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_add_shape: -- void **shape_owner_add_shape** **(** :ref:`int` owner_id, :ref:`Shape2D` shape **)** +.. rst-class:: classref-method + +|void| **shape_owner_add_shape**\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape2D`\ ) :ref:`🔗` Adds a :ref:`Shape2D` to the shape owner. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_clear_shapes: -- void **shape_owner_clear_shapes** **(** :ref:`int` owner_id **)** +.. rst-class:: classref-method + +|void| **shape_owner_clear_shapes**\ (\ owner_id\: :ref:`int`\ ) :ref:`🔗` Removes all shapes from the shape owner. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_get_owner: -- :ref:`Object` **shape_owner_get_owner** **(** :ref:`int` owner_id **)** const +.. rst-class:: classref-method + +:ref:`Object` **shape_owner_get_owner**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the parent object of the given shape owner. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_get_shape: -- :ref:`Shape2D` **shape_owner_get_shape** **(** :ref:`int` owner_id, :ref:`int` shape_id **)** const +.. rst-class:: classref-method + +:ref:`Shape2D` **shape_owner_get_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the :ref:`Shape2D` with the given ID from the given shape owner. -Returns the :ref:`Shape2D` with the given id from the given shape owner. +.. rst-class:: classref-item-separator ---- .. _class_CollisionObject2D_method_shape_owner_get_shape_count: -- :ref:`int` **shape_owner_get_shape_count** **(** :ref:`int` owner_id **)** const +.. rst-class:: classref-method + +:ref:`int` **shape_owner_get_shape_count**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the number of shapes the given shape owner contains. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_get_shape_index: -- :ref:`int` **shape_owner_get_shape_index** **(** :ref:`int` owner_id, :ref:`int` shape_id **)** const +.. rst-class:: classref-method + +:ref:`int` **shape_owner_get_shape_index**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the child index of the :ref:`Shape2D` with the given id from the given shape owner. +Returns the child index of the :ref:`Shape2D` with the given ID from the given shape owner. + +.. rst-class:: classref-item-separator ---- .. _class_CollisionObject2D_method_shape_owner_get_transform: -- :ref:`Transform2D` **shape_owner_get_transform** **(** :ref:`int` owner_id **)** const +.. rst-class:: classref-method + +:ref:`Transform2D` **shape_owner_get_transform**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the shape owner's :ref:`Transform2D`. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_remove_shape: -- void **shape_owner_remove_shape** **(** :ref:`int` owner_id, :ref:`int` shape_id **)** +.. rst-class:: classref-method + +|void| **shape_owner_remove_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) :ref:`🔗` Removes a shape from the given shape owner. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_set_disabled: -- void **shape_owner_set_disabled** **(** :ref:`int` owner_id, :ref:`bool` disabled **)** +.. rst-class:: classref-method + +|void| **shape_owner_set_disabled**\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) :ref:`🔗` If ``true``, disables the given shape owner. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_set_one_way_collision: -- void **shape_owner_set_one_way_collision** **(** :ref:`int` owner_id, :ref:`bool` enable **)** +.. rst-class:: classref-method + +|void| **shape_owner_set_one_way_collision**\ (\ owner_id\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` + +If ``enable`` is ``true``, collisions for the shape owner originating from this **CollisionObject2D** will not be reported to collided with **CollisionObject2D**\ s. -If ``enable`` is ``true``, collisions for the shape owner originating from this ``CollisionObject2D`` will not be reported to collided with ``CollisionObject2D``\ s. +.. rst-class:: classref-item-separator ---- .. _class_CollisionObject2D_method_shape_owner_set_one_way_collision_margin: -- void **shape_owner_set_one_way_collision_margin** **(** :ref:`int` owner_id, :ref:`float` margin **)** +.. rst-class:: classref-method + +|void| **shape_owner_set_one_way_collision_margin**\ (\ owner_id\: :ref:`int`, margin\: :ref:`float`\ ) :ref:`🔗` Sets the ``one_way_collision_margin`` of the shape owner identified by given ``owner_id`` to ``margin`` pixels. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionObject2D_method_shape_owner_set_transform: -- void **shape_owner_set_transform** **(** :ref:`int` owner_id, :ref:`Transform2D` transform **)** +.. rst-class:: classref-method + +|void| **shape_owner_set_transform**\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform2D`\ ) :ref:`🔗` Sets the :ref:`Transform2D` of the given shape owner. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_collisionobject3d.rst b/classes/class_collisionobject3d.rst new file mode 100644 index 00000000000..2760df168bc --- /dev/null +++ b/classes/class_collisionobject3d.rst @@ -0,0 +1,596 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CollisionObject3D.xml. + +.. _class_CollisionObject3D: + +CollisionObject3D +================= + +**Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +**Inherited By:** :ref:`Area3D`, :ref:`PhysicsBody3D` + +Abstract base class for 3D physics objects. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Abstract base class for 3D physics objects. **CollisionObject3D** can hold any number of :ref:`Shape3D`\ s for collision. Each shape must be assigned to a *shape owner*. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. + +\ **Warning:** With a non-uniform scale, this node will likely not behave as expected. It is advised to keep its scale the same on all axes and adjust its collision shape(s) instead. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`collision_layer` | ``1`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`collision_mask` | ``1`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`collision_priority` | ``1.0`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ + | :ref:`DisableMode` | :ref:`disable_mode` | ``0`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`input_capture_on_drag` | ``false`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`input_ray_pickable` | ``true`` | + +--------------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_input_event`\ (\ camera\: :ref:`Camera3D`, event\: :ref:`InputEvent`, event_position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) |virtual| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_mouse_enter`\ (\ ) |virtual| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_mouse_exit`\ (\ ) |virtual| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`create_shape_owner`\ (\ owner\: :ref:`Object`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_collision_layer_value`\ (\ layer_number\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_collision_mask_value`\ (\ layer_number\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_rid`\ (\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`get_shape_owners`\ (\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_shape_owner_disabled`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_shape_owner`\ (\ owner_id\: :ref:`int`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_collision_layer_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_collision_mask_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_find_owner`\ (\ shape_index\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_add_shape`\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape3D`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_clear_shapes`\ (\ owner_id\: :ref:`int`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Object` | :ref:`shape_owner_get_owner`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Shape3D` | :ref:`shape_owner_get_shape`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_owner_get_shape_count`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_owner_get_shape_index`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform3D` | :ref:`shape_owner_get_transform`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_remove_shape`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_set_disabled`\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_set_transform`\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform3D`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_CollisionObject3D_signal_input_event: + +.. rst-class:: classref-signal + +**input_event**\ (\ camera\: :ref:`Node`, event\: :ref:`InputEvent`, event_position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) :ref:`🔗` + +Emitted when the object receives an unhandled :ref:`InputEvent`. ``event_position`` is the location in world space of the mouse pointer on the surface of the shape with index ``shape_idx`` and ``normal`` is the normal vector of the surface at that point. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_signal_mouse_entered: + +.. rst-class:: classref-signal + +**mouse_entered**\ (\ ) :ref:`🔗` + +Emitted when the mouse pointer enters any of this object's shapes. Requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. + +\ **Note:** Due to the lack of continuous collision detection, this signal may not be emitted in the expected order if the mouse moves fast enough and the **CollisionObject3D**'s area is small. This signal may also not be emitted if another **CollisionObject3D** is overlapping the **CollisionObject3D** in question. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_signal_mouse_exited: + +.. rst-class:: classref-signal + +**mouse_exited**\ (\ ) :ref:`🔗` + +Emitted when the mouse pointer exits all this object's shapes. Requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. + +\ **Note:** Due to the lack of continuous collision detection, this signal may not be emitted in the expected order if the mouse moves fast enough and the **CollisionObject3D**'s area is small. This signal may also not be emitted if another **CollisionObject3D** is overlapping the **CollisionObject3D** in question. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_CollisionObject3D_DisableMode: + +.. rst-class:: classref-enumeration + +enum **DisableMode**: :ref:`🔗` + +.. _class_CollisionObject3D_constant_DISABLE_MODE_REMOVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DisableMode` **DISABLE_MODE_REMOVE** = ``0`` + +When :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`, remove from the physics simulation to stop all physics interactions with this **CollisionObject3D**. + +Automatically re-added to the physics simulation when the :ref:`Node` is processed again. + +.. _class_CollisionObject3D_constant_DISABLE_MODE_MAKE_STATIC: + +.. rst-class:: classref-enumeration-constant + +:ref:`DisableMode` **DISABLE_MODE_MAKE_STATIC** = ``1`` + +When :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`, make the body static. Doesn't affect :ref:`Area3D`. :ref:`PhysicsBody3D` can't be affected by forces or other bodies while static. + +Automatically set :ref:`PhysicsBody3D` back to its original mode when the :ref:`Node` is processed again. + +.. _class_CollisionObject3D_constant_DISABLE_MODE_KEEP_ACTIVE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DisableMode` **DISABLE_MODE_KEEP_ACTIVE** = ``2`` + +When :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`, do not affect the physics simulation. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CollisionObject3D_property_collision_layer: + +.. rst-class:: classref-property + +:ref:`int` **collision_layer** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_collision_layer**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_collision_layer**\ (\ ) + +The physics layers this CollisionObject3D **is in**. Collision objects can exist in one or more of 32 different layers. See also :ref:`collision_mask`. + +\ **Note:** Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See `Collision layers and masks <../tutorials/physics/physics_introduction.html#collision-layers-and-masks>`__ in the documentation for more information. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_property_collision_mask: + +.. rst-class:: classref-property + +:ref:`int` **collision_mask** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_collision_mask**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_collision_mask**\ (\ ) + +The physics layers this CollisionObject3D **scans**. Collision objects can scan one or more of 32 different layers. See also :ref:`collision_layer`. + +\ **Note:** Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See `Collision layers and masks <../tutorials/physics/physics_introduction.html#collision-layers-and-masks>`__ in the documentation for more information. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_property_collision_priority: + +.. rst-class:: classref-property + +:ref:`float` **collision_priority** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_collision_priority**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_collision_priority**\ (\ ) + +The priority used to solve colliding when occurring penetration. The higher the priority is, the lower the penetration into the object will be. This can for example be used to prevent the player from breaking through the boundaries of a level. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_property_disable_mode: + +.. rst-class:: classref-property + +:ref:`DisableMode` **disable_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_disable_mode**\ (\ value\: :ref:`DisableMode`\ ) +- :ref:`DisableMode` **get_disable_mode**\ (\ ) + +Defines the behavior in physics when :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_property_input_capture_on_drag: + +.. rst-class:: classref-property + +:ref:`bool` **input_capture_on_drag** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_capture_input_on_drag**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_capture_input_on_drag**\ (\ ) + +If ``true``, the **CollisionObject3D** will continue to receive input events as the mouse is dragged across its shapes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_property_input_ray_pickable: + +.. rst-class:: classref-property + +:ref:`bool` **input_ray_pickable** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_ray_pickable**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_ray_pickable**\ (\ ) + +If ``true``, this object is pickable. A pickable object can detect the mouse pointer entering/leaving, and if the mouse is inside it, report input events. Requires at least one :ref:`collision_layer` bit to be set. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CollisionObject3D_private_method__input_event: + +.. rst-class:: classref-method + +|void| **_input_event**\ (\ camera\: :ref:`Camera3D`, event\: :ref:`InputEvent`, event_position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) |virtual| :ref:`🔗` + +Receives unhandled :ref:`InputEvent`\ s. ``event_position`` is the location in world space of the mouse pointer on the surface of the shape with index ``shape_idx`` and ``normal`` is the normal vector of the surface at that point. Connect to the :ref:`input_event` signal to easily pick up these events. + +\ **Note:** :ref:`_input_event()` requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_private_method__mouse_enter: + +.. rst-class:: classref-method + +|void| **_mouse_enter**\ (\ ) |virtual| :ref:`🔗` + +Called when the mouse pointer enters any of this object's shapes. Requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject3D** won't cause this function to be called. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_private_method__mouse_exit: + +.. rst-class:: classref-method + +|void| **_mouse_exit**\ (\ ) |virtual| :ref:`🔗` + +Called when the mouse pointer exits all this object's shapes. Requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject3D** won't cause this function to be called. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_create_shape_owner: + +.. rst-class:: classref-method + +:ref:`int` **create_shape_owner**\ (\ owner\: :ref:`Object`\ ) :ref:`🔗` + +Creates a new shape owner for the given object. Returns ``owner_id`` of the new owner for future reference. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_get_collision_layer_value: + +.. rst-class:: classref-method + +:ref:`bool` **get_collision_layer_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether or not the specified layer of the :ref:`collision_layer` is enabled, given a ``layer_number`` between 1 and 32. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_get_collision_mask_value: + +.. rst-class:: classref-method + +:ref:`bool` **get_collision_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether or not the specified layer of the :ref:`collision_mask` is enabled, given a ``layer_number`` between 1 and 32. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_get_rid: + +.. rst-class:: classref-method + +:ref:`RID` **get_rid**\ (\ ) |const| :ref:`🔗` + +Returns the object's :ref:`RID`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_get_shape_owners: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **get_shape_owners**\ (\ ) :ref:`🔗` + +Returns an :ref:`Array` of ``owner_id`` identifiers. You can use these ids in other methods that take ``owner_id`` as an argument. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_is_shape_owner_disabled: + +.. rst-class:: classref-method + +:ref:`bool` **is_shape_owner_disabled**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` + +If ``true``, the shape owner and its shapes are disabled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_remove_shape_owner: + +.. rst-class:: classref-method + +|void| **remove_shape_owner**\ (\ owner_id\: :ref:`int`\ ) :ref:`🔗` + +Removes the given shape owner. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_set_collision_layer_value: + +.. rst-class:: classref-method + +|void| **set_collision_layer_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` + +Based on ``value``, enables or disables the specified layer in the :ref:`collision_layer`, given a ``layer_number`` between 1 and 32. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_set_collision_mask_value: + +.. rst-class:: classref-method + +|void| **set_collision_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` + +Based on ``value``, enables or disables the specified layer in the :ref:`collision_mask`, given a ``layer_number`` between 1 and 32. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_find_owner: + +.. rst-class:: classref-method + +:ref:`int` **shape_find_owner**\ (\ shape_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the ``owner_id`` of the given shape. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_add_shape: + +.. rst-class:: classref-method + +|void| **shape_owner_add_shape**\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape3D`\ ) :ref:`🔗` + +Adds a :ref:`Shape3D` to the shape owner. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_clear_shapes: + +.. rst-class:: classref-method + +|void| **shape_owner_clear_shapes**\ (\ owner_id\: :ref:`int`\ ) :ref:`🔗` + +Removes all shapes from the shape owner. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_get_owner: + +.. rst-class:: classref-method + +:ref:`Object` **shape_owner_get_owner**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the parent object of the given shape owner. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_get_shape: + +.. rst-class:: classref-method + +:ref:`Shape3D` **shape_owner_get_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the :ref:`Shape3D` with the given ID from the given shape owner. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_get_shape_count: + +.. rst-class:: classref-method + +:ref:`int` **shape_owner_get_shape_count**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the number of shapes the given shape owner contains. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_get_shape_index: + +.. rst-class:: classref-method + +:ref:`int` **shape_owner_get_shape_index**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the child index of the :ref:`Shape3D` with the given ID from the given shape owner. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_get_transform: + +.. rst-class:: classref-method + +:ref:`Transform3D` **shape_owner_get_transform**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the shape owner's :ref:`Transform3D`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_remove_shape: + +.. rst-class:: classref-method + +|void| **shape_owner_remove_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) :ref:`🔗` + +Removes a shape from the given shape owner. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_set_disabled: + +.. rst-class:: classref-method + +|void| **shape_owner_set_disabled**\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) :ref:`🔗` + +If ``true``, disables the given shape owner. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionObject3D_method_shape_owner_set_transform: + +.. rst-class:: classref-method + +|void| **shape_owner_set_transform**\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform3D`\ ) :ref:`🔗` + +Sets the :ref:`Transform3D` of the given shape owner. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_collisionpolygon.rst b/classes/class_collisionpolygon.rst deleted file mode 100644 index eef08d028bb..00000000000 --- a/classes/class_collisionpolygon.rst +++ /dev/null @@ -1,82 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CollisionPolygon.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_CollisionPolygon: - -CollisionPolygon -================ - -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -Editor-only class for defining a collision polygon in 3D space. - -Description ------------ - -Allows editing a collision polygon's vertices on a selected plane. Can also set a depth perpendicular to that plane. This class is only available in the editor. It will not appear in the scene tree at run-time. Creates a :ref:`Shape` for gameplay. Properties modified during gameplay will have no effect. - -Properties ----------- - -+-----------------------------------------------------+-----------------------------------------------------------+----------------------------+ -| :ref:`float` | :ref:`depth` | ``1.0`` | -+-----------------------------------------------------+-----------------------------------------------------------+----------------------------+ -| :ref:`bool` | :ref:`disabled` | ``false`` | -+-----------------------------------------------------+-----------------------------------------------------------+----------------------------+ -| :ref:`PackedVector2Array` | :ref:`polygon` | ``PackedVector2Array( )`` | -+-----------------------------------------------------+-----------------------------------------------------------+----------------------------+ - -Property Descriptions ---------------------- - -.. _class_CollisionPolygon_property_depth: - -- :ref:`float` **depth** - -+-----------+------------------+ -| *Default* | ``1.0`` | -+-----------+------------------+ -| *Setter* | set_depth(value) | -+-----------+------------------+ -| *Getter* | get_depth() | -+-----------+------------------+ - -Length that the resulting collision extends in either direction perpendicular to its polygon. - ----- - -.. _class_CollisionPolygon_property_disabled: - -- :ref:`bool` **disabled** - -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_disabled(value) | -+-----------+---------------------+ -| *Getter* | is_disabled() | -+-----------+---------------------+ - -If ``true``, no collision will be produced. - ----- - -.. _class_CollisionPolygon_property_polygon: - -- :ref:`PackedVector2Array` **polygon** - -+-----------+----------------------------+ -| *Default* | ``PackedVector2Array( )`` | -+-----------+----------------------------+ -| *Setter* | set_polygon(value) | -+-----------+----------------------------+ -| *Getter* | get_polygon() | -+-----------+----------------------------+ - -Array of vertices which define the polygon. - -**Note:** The returned value is a copy of the original. Methods which mutate the size or properties of the return value will not impact the original polygon. To change properties of the polygon, assign it to a temporary variable and make changes before reassigning the ``polygon`` member. - diff --git a/classes/class_collisionpolygon2d.rst b/classes/class_collisionpolygon2d.rst index 2a1fde3c660..989cc284509 100644 --- a/classes/class_collisionpolygon2d.rst +++ b/classes/class_collisionpolygon2d.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CollisionPolygon2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CollisionPolygon2D.xml. .. _class_CollisionPolygon2D: @@ -11,121 +12,170 @@ CollisionPolygon2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Defines a 2D collision polygon. +A node that provides a polygon shape to a :ref:`CollisionObject2D` parent. + +.. rst-class:: classref-introduction-group Description ----------- -Provides a 2D collision polygon to a :ref:`CollisionObject2D` parent. Polygons can be drawn in the editor or specified by a list of vertices. +A node that provides a polygon shape to a :ref:`CollisionObject2D` parent and allows it to be edited. The polygon can be concave or convex. This can give a detection shape to an :ref:`Area2D`, turn a :ref:`PhysicsBody2D` into a solid object, or give a hollow shape to a :ref:`StaticBody2D`. + +\ **Warning:** A non-uniformly scaled **CollisionPolygon2D** will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its polygon instead. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------------+---------------------------------------------------------------------------------------------+----------------------------+ -| :ref:`BuildMode` | :ref:`build_mode` | ``0`` | -+-----------------------------------------------------+---------------------------------------------------------------------------------------------+----------------------------+ -| :ref:`bool` | :ref:`disabled` | ``false`` | -+-----------------------------------------------------+---------------------------------------------------------------------------------------------+----------------------------+ -| :ref:`bool` | :ref:`one_way_collision` | ``false`` | -+-----------------------------------------------------+---------------------------------------------------------------------------------------------+----------------------------+ -| :ref:`float` | :ref:`one_way_collision_margin` | ``1.0`` | -+-----------------------------------------------------+---------------------------------------------------------------------------------------------+----------------------------+ -| :ref:`PackedVector2Array` | :ref:`polygon` | ``PackedVector2Array( )`` | -+-----------------------------------------------------+---------------------------------------------------------------------------------------------+----------------------------+ +.. table:: + :widths: auto + + +-----------------------------------------------------+---------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`BuildMode` | :ref:`build_mode` | ``0`` | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`bool` | :ref:`disabled` | ``false`` | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`bool` | :ref:`one_way_collision` | ``false`` | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`float` | :ref:`one_way_collision_margin` | ``1.0`` | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------+--------------------------+ + | :ref:`PackedVector2Array` | :ref:`polygon` | ``PackedVector2Array()`` | + +-----------------------------------------------------+---------------------------------------------------------------------------------------------+--------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_CollisionPolygon2D_BuildMode: +.. rst-class:: classref-enumeration + +enum **BuildMode**: :ref:`🔗` + .. _class_CollisionPolygon2D_constant_BUILD_SOLIDS: +.. rst-class:: classref-enumeration-constant + +:ref:`BuildMode` **BUILD_SOLIDS** = ``0`` + +Collisions will include the polygon and its contained area. In this mode the node has the same effect as several :ref:`ConvexPolygonShape2D` nodes, one for each convex shape in the convex decomposition of the polygon (but without the overhead of multiple nodes). + .. _class_CollisionPolygon2D_constant_BUILD_SEGMENTS: -enum **BuildMode**: +.. rst-class:: classref-enumeration-constant -- **BUILD_SOLIDS** = **0** --- Collisions will include the polygon and its contained area. +:ref:`BuildMode` **BUILD_SEGMENTS** = ``1`` + +Collisions will only include the polygon edges. In this mode the node has the same effect as a single :ref:`ConcavePolygonShape2D` made of segments, with the restriction that each segment (after the first one) starts where the previous one ends, and the last one ends where the first one starts (forming a closed but hollow polygon). + +.. rst-class:: classref-section-separator + +---- -- **BUILD_SEGMENTS** = **1** --- Collisions will only include the polygon edges. +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_CollisionPolygon2D_property_build_mode: -- :ref:`BuildMode` **build_mode** +.. rst-class:: classref-property -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_build_mode(value) | -+-----------+-----------------------+ -| *Getter* | get_build_mode() | -+-----------+-----------------------+ +:ref:`BuildMode` **build_mode** = ``0`` :ref:`🔗` -Collision build mode. Use one of the :ref:`BuildMode` constants. +.. rst-class:: classref-property-setget + +- |void| **set_build_mode**\ (\ value\: :ref:`BuildMode`\ ) +- :ref:`BuildMode` **get_build_mode**\ (\ ) + +Collision build mode. + +.. rst-class:: classref-item-separator ---- .. _class_CollisionPolygon2D_property_disabled: -- :ref:`bool` **disabled** +.. rst-class:: classref-property + +:ref:`bool` **disabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_disabled(value) | -+-----------+---------------------+ -| *Getter* | is_disabled() | -+-----------+---------------------+ +- |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_disabled**\ (\ ) -If ``true``, no collisions will be detected. +If ``true``, no collisions will be detected. This property should be changed with :ref:`Object.set_deferred()`. + +.. rst-class:: classref-item-separator ---- .. _class_CollisionPolygon2D_property_one_way_collision: -- :ref:`bool` **one_way_collision** +.. rst-class:: classref-property + +:ref:`bool` **one_way_collision** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_one_way_collision**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_one_way_collision_enabled**\ (\ ) -+-----------+--------------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------------+ -| *Setter* | set_one_way_collision(value) | -+-----------+--------------------------------+ -| *Getter* | is_one_way_collision_enabled() | -+-----------+--------------------------------+ +If ``true``, only edges that face up, relative to **CollisionPolygon2D**'s rotation, will collide with other objects. -If ``true``, only edges that face up, relative to ``CollisionPolygon2D``'s rotation, will collide with other objects. +\ **Note:** This property has no effect if this **CollisionPolygon2D** is a child of an :ref:`Area2D` node. + +.. rst-class:: classref-item-separator ---- .. _class_CollisionPolygon2D_property_one_way_collision_margin: -- :ref:`float` **one_way_collision_margin** +.. rst-class:: classref-property + +:ref:`float` **one_way_collision_margin** = ``1.0`` :ref:`🔗` -+-----------+-------------------------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------------------------+ -| *Setter* | set_one_way_collision_margin(value) | -+-----------+-------------------------------------+ -| *Getter* | get_one_way_collision_margin() | -+-----------+-------------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_one_way_collision_margin**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_one_way_collision_margin**\ (\ ) The margin used for one-way collision (in pixels). Higher values will make the shape thicker, and work better for colliders that enter the polygon at a high velocity. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionPolygon2D_property_polygon: -- :ref:`PackedVector2Array` **polygon** +.. rst-class:: classref-property + +:ref:`PackedVector2Array` **polygon** = ``PackedVector2Array()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_polygon**\ (\ value\: :ref:`PackedVector2Array`\ ) +- :ref:`PackedVector2Array` **get_polygon**\ (\ ) + +The polygon's list of vertices. Each point will be connected to the next, and the final point will be connected to the first. -+-----------+----------------------------+ -| *Default* | ``PackedVector2Array( )`` | -+-----------+----------------------------+ -| *Setter* | set_polygon(value) | -+-----------+----------------------------+ -| *Getter* | get_polygon() | -+-----------+----------------------------+ +\ **Note:** The returned vertices are in the local coordinate space of the given **CollisionPolygon2D**. -The polygon's list of vertices. The final point will be connected to the first. The returned value is a clone of the :ref:`PackedVector2Array`, not a reference. +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedVector2Array` for more details. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_collisionpolygon3d.rst b/classes/class_collisionpolygon3d.rst new file mode 100644 index 00000000000..404587f8e5f --- /dev/null +++ b/classes/class_collisionpolygon3d.rst @@ -0,0 +1,167 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CollisionPolygon3D.xml. + +.. _class_CollisionPolygon3D: + +CollisionPolygon3D +================== + +**Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +A node that provides a thickened polygon shape (a prism) to a :ref:`CollisionObject3D` parent. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A node that provides a thickened polygon shape (a prism) to a :ref:`CollisionObject3D` parent and allows it to be edited. The polygon can be concave or convex. This can give a detection shape to an :ref:`Area3D` or turn a :ref:`PhysicsBody3D` into a solid object. + +\ **Warning:** A non-uniformly scaled :ref:`CollisionShape3D` will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its shape resource instead. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 0)`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`bool` | :ref:`debug_fill` | ``true`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`float` | :ref:`depth` | ``1.0`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`bool` | :ref:`disabled` | ``false`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`float` | :ref:`margin` | ``0.04`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`PackedVector2Array` | :ref:`polygon` | ``PackedVector2Array()`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CollisionPolygon3D_property_debug_color: + +.. rst-class:: classref-property + +:ref:`Color` **debug_color** = ``Color(0, 0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_debug_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. + +\ **Note:** The default value is :ref:`ProjectSettings.debug/shapes/collision/shape_color`. The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionPolygon3D_property_debug_fill: + +.. rst-class:: classref-property + +:ref:`bool` **debug_fill** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_enable_debug_fill**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_enable_debug_fill**\ (\ ) + +If ``true``, when the shape is displayed, it will show a solid fill color in addition to its wireframe. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionPolygon3D_property_depth: + +.. rst-class:: classref-property + +:ref:`float` **depth** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_depth**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_depth**\ (\ ) + +Length that the resulting collision extends in either direction perpendicular to its 2D polygon. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionPolygon3D_property_disabled: + +.. rst-class:: classref-property + +:ref:`bool` **disabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_disabled**\ (\ ) + +If ``true``, no collision will be produced. This property should be changed with :ref:`Object.set_deferred()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionPolygon3D_property_margin: + +.. rst-class:: classref-property + +:ref:`float` **margin** = ``0.04`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_margin**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_margin**\ (\ ) + +The collision margin for the generated :ref:`Shape3D`. See :ref:`Shape3D.margin` for more details. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionPolygon3D_property_polygon: + +.. rst-class:: classref-property + +:ref:`PackedVector2Array` **polygon** = ``PackedVector2Array()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_polygon**\ (\ value\: :ref:`PackedVector2Array`\ ) +- :ref:`PackedVector2Array` **get_polygon**\ (\ ) + +Array of vertices which define the 2D polygon in the local XY plane. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedVector2Array` for more details. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_collisionshape.rst b/classes/class_collisionshape.rst deleted file mode 100644 index 8456966523f..00000000000 --- a/classes/class_collisionshape.rst +++ /dev/null @@ -1,91 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CollisionShape.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_CollisionShape: - -CollisionShape -============== - -**Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -Node that represents collision shape data in 3D space. - -Description ------------ - -Editor facility for creating and editing collision shapes in 3D space. You can use this node to represent all sorts of collision shapes, for example, add this to an :ref:`Area` to give it a detection shape, or add it to a :ref:`PhysicsBody` to create a solid object. **IMPORTANT**: this is an Editor-only helper to create shapes, use :ref:`CollisionObject.shape_owner_get_shape` to get the actual shape. - -Tutorials ---------- - -- :doc:`../tutorials/physics/physics_introduction` - -Properties ----------- - -+---------------------------+---------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`disabled` | ``false`` | -+---------------------------+---------------------------------------------------------+-----------+ -| :ref:`Shape` | :ref:`shape` | | -+---------------------------+---------------------------------------------------------+-----------+ - -Methods -------- - -+------+----------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`make_convex_from_brothers` **(** **)** | -+------+----------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`resource_changed` **(** :ref:`Resource` resource **)** | -+------+----------------------------------------------------------------------------------------------------------------------------+ - -Property Descriptions ---------------------- - -.. _class_CollisionShape_property_disabled: - -- :ref:`bool` **disabled** - -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_disabled(value) | -+-----------+---------------------+ -| *Getter* | is_disabled() | -+-----------+---------------------+ - -A disabled collision shape has no effect in the world. - ----- - -.. _class_CollisionShape_property_shape: - -- :ref:`Shape` **shape** - -+----------+------------------+ -| *Setter* | set_shape(value) | -+----------+------------------+ -| *Getter* | get_shape() | -+----------+------------------+ - -The actual shape owned by this collision shape. - -Method Descriptions -------------------- - -.. _class_CollisionShape_method_make_convex_from_brothers: - -- void **make_convex_from_brothers** **(** **)** - -Sets the collision shape's shape to the addition of all its convexed :ref:`MeshInstance` siblings geometry. - ----- - -.. _class_CollisionShape_method_resource_changed: - -- void **resource_changed** **(** :ref:`Resource` resource **)** - -If this method exists within a script it will be called whenever the shape resource has been modified. - diff --git a/classes/class_collisionshape2d.rst b/classes/class_collisionshape2d.rst index 0b6cc153099..a99ea414d2d 100644 --- a/classes/class_collisionshape2d.rst +++ b/classes/class_collisionshape2d.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the CollisionShape2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CollisionShape2D.xml. .. _class_CollisionShape2D: @@ -11,91 +12,148 @@ CollisionShape2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Node that represents collision shape data in 2D space. +A node that provides a :ref:`Shape2D` to a :ref:`CollisionObject2D` parent. + +.. rst-class:: classref-introduction-group Description ----------- -Editor facility for creating and editing collision shapes in 2D space. You can use this node to represent all sorts of collision shapes, for example, add this to an :ref:`Area2D` to give it a detection shape, or add it to a :ref:`PhysicsBody2D` to create a solid object. **IMPORTANT**: this is an Editor-only helper to create shapes, use :ref:`CollisionObject2D.shape_owner_get_shape` to get the actual shape. +A node that provides a :ref:`Shape2D` to a :ref:`CollisionObject2D` parent and allows it to be edited. This can give a detection shape to an :ref:`Area2D` or turn a :ref:`PhysicsBody2D` into a solid object. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/physics/physics_introduction` +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- `2D Dodge The Creeps Demo `__ + +- `2D Pong Demo `__ + +- `2D Kinematic Character Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`disabled` | ``false`` | -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`one_way_collision` | ``false`` | -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`one_way_collision_margin` | ``1.0`` | -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`Shape2D` | :ref:`shape` | | -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ +.. table:: + :widths: auto + + +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 0)`` | + +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disabled` | ``false`` | + +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`one_way_collision` | ``false`` | + +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`one_way_collision_margin` | ``1.0`` | + +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Shape2D` | :ref:`shape` | | + +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- +.. _class_CollisionShape2D_property_debug_color: + +.. rst-class:: classref-property + +:ref:`Color` **debug_color** = ``Color(0, 0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_debug_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. + +\ **Note:** The default value is :ref:`ProjectSettings.debug/shapes/collision/shape_color`. The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. + +.. rst-class:: classref-item-separator + +---- + .. _class_CollisionShape2D_property_disabled: -- :ref:`bool` **disabled** +.. rst-class:: classref-property -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_disabled(value) | -+-----------+---------------------+ -| *Getter* | is_disabled() | -+-----------+---------------------+ +:ref:`bool` **disabled** = ``false`` :ref:`🔗` -A disabled collision shape has no effect in the world. +.. rst-class:: classref-property-setget + +- |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_disabled**\ (\ ) + +A disabled collision shape has no effect in the world. This property should be changed with :ref:`Object.set_deferred()`. + +.. rst-class:: classref-item-separator ---- .. _class_CollisionShape2D_property_one_way_collision: -- :ref:`bool` **one_way_collision** +.. rst-class:: classref-property + +:ref:`bool` **one_way_collision** = ``false`` :ref:`🔗` -+-----------+--------------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------------+ -| *Setter* | set_one_way_collision(value) | -+-----------+--------------------------------+ -| *Getter* | is_one_way_collision_enabled() | -+-----------+--------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_one_way_collision**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_one_way_collision_enabled**\ (\ ) Sets whether this collision shape should only detect collision on one side (top or bottom). +\ **Note:** This property has no effect if this **CollisionShape2D** is a child of an :ref:`Area2D` node. + +.. rst-class:: classref-item-separator + ---- .. _class_CollisionShape2D_property_one_way_collision_margin: -- :ref:`float` **one_way_collision_margin** +.. rst-class:: classref-property + +:ref:`float` **one_way_collision_margin** = ``1.0`` :ref:`🔗` -+-----------+-------------------------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------------------------+ -| *Setter* | set_one_way_collision_margin(value) | -+-----------+-------------------------------------+ -| *Getter* | get_one_way_collision_margin() | -+-----------+-------------------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_one_way_collision_margin**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_one_way_collision_margin**\ (\ ) The margin used for one-way collision (in pixels). Higher values will make the shape thicker, and work better for colliders that enter the shape at a high velocity. +.. rst-class:: classref-item-separator + ---- .. _class_CollisionShape2D_property_shape: -- :ref:`Shape2D` **shape** +.. rst-class:: classref-property + +:ref:`Shape2D` **shape** :ref:`🔗` + +.. rst-class:: classref-property-setget -+----------+------------------+ -| *Setter* | set_shape(value) | -+----------+------------------+ -| *Getter* | get_shape() | -+----------+------------------+ +- |void| **set_shape**\ (\ value\: :ref:`Shape2D`\ ) +- :ref:`Shape2D` **get_shape**\ (\ ) The actual shape owned by this collision shape. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_collisionshape3d.rst b/classes/class_collisionshape3d.rst new file mode 100644 index 00000000000..77e66abc3f2 --- /dev/null +++ b/classes/class_collisionshape3d.rst @@ -0,0 +1,185 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CollisionShape3D.xml. + +.. _class_CollisionShape3D: + +CollisionShape3D +================ + +**Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +A node that provides a :ref:`Shape3D` to a :ref:`CollisionObject3D` parent. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A node that provides a :ref:`Shape3D` to a :ref:`CollisionObject3D` parent and allows it to be edited. This can give a detection shape to an :ref:`Area3D` or turn a :ref:`PhysicsBody3D` into a solid object. + +\ **Warning:** A non-uniformly scaled **CollisionShape3D** will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its :ref:`shape` resource instead. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- `3D Kinematic Character Demo `__ + +- `3D Platformer Demo `__ + +- `Third Person Shooter (TPS) Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 0)`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`debug_fill` | ``true`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disabled` | ``false`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`Shape3D` | :ref:`shape` | | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +--------+---------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`make_convex_from_siblings`\ (\ ) | + +--------+---------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`resource_changed`\ (\ resource\: :ref:`Resource`\ ) | + +--------+---------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CollisionShape3D_property_debug_color: + +.. rst-class:: classref-property + +:ref:`Color` **debug_color** = ``Color(0, 0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_debug_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. + +\ **Note:** The default value is :ref:`ProjectSettings.debug/shapes/collision/shape_color`. The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionShape3D_property_debug_fill: + +.. rst-class:: classref-property + +:ref:`bool` **debug_fill** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_enable_debug_fill**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_enable_debug_fill**\ (\ ) + +If ``true``, when the shape is displayed, it will show a solid fill color in addition to its wireframe. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionShape3D_property_disabled: + +.. rst-class:: classref-property + +:ref:`bool` **disabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_disabled**\ (\ ) + +A disabled collision shape has no effect in the world. This property should be changed with :ref:`Object.set_deferred()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionShape3D_property_shape: + +.. rst-class:: classref-property + +:ref:`Shape3D` **shape** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_shape**\ (\ value\: :ref:`Shape3D`\ ) +- :ref:`Shape3D` **get_shape**\ (\ ) + +The actual shape owned by this collision shape. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CollisionShape3D_method_make_convex_from_siblings: + +.. rst-class:: classref-method + +|void| **make_convex_from_siblings**\ (\ ) :ref:`🔗` + +Sets the collision shape's shape to the addition of all its convexed :ref:`MeshInstance3D` siblings geometry. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionShape3D_method_resource_changed: + +.. rst-class:: classref-method + +|void| **resource_changed**\ (\ resource\: :ref:`Resource`\ ) :ref:`🔗` + +**Deprecated:** Use :ref:`Resource.changed` instead. + +This method does nothing. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_color.rst b/classes/class_color.rst index f8bb8e03365..9ca631ed5dc 100644 --- a/classes/class_color.rst +++ b/classes/class_color.rst @@ -1,1051 +1,2472 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Color.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Color.xml. .. _class_Color: Color ===== -Color in RGBA format with some support for ARGB format. +A color represented in RGBA format. + +.. rst-class:: classref-introduction-group Description ----------- -A color is represented by red, green, and blue ``(r, g, b)`` components. Additionally, ``a`` represents the alpha component, often used for transparency. Values are in floating-point and usually range from 0 to 1. Some properties (such as :ref:`CanvasItem.modulate`) may accept values greater than 1. +A color represented in RGBA format by a red (:ref:`r`), green (:ref:`g`), blue (:ref:`b`), and alpha (:ref:`a`) component. Each component is a 32-bit floating-point value, usually ranging from ``0.0`` to ``1.0``. Some properties (such as :ref:`CanvasItem.modulate`) may support values greater than ``1.0``, for overbright or HDR (High Dynamic Range) colors. + +Colors can be created in a number of ways: By the various **Color** constructors, by static methods such as :ref:`from_hsv()`, and by using a name from the set of standardized colors based on `X11 color names `__ with the addition of :ref:`TRANSPARENT`. GDScript also provides :ref:`@GDScript.Color8()`, which uses integers from ``0`` to ``255`` and doesn't support overbright colors. + +\ `Color constants cheatsheet `__\ + +Although **Color** may be used to store values of any encoding, the red (:ref:`r`), green (:ref:`g`), and blue (:ref:`b`) properties of **Color** are expected by Godot to be encoded using the `nonlinear sRGB transfer function `__ unless otherwise stated. This color encoding is used by many traditional art and web tools, making it easy to match colors between Godot and these tools. Godot uses `Rec. ITU-R BT.709 `__ color primaries, which are used by the sRGB standard. + +All physical simulation, such as lighting calculations, and colorimetry transformations, such as :ref:`get_luminance()`, must be performed on linearly encoded values to produce correct results. When performing these calculations, convert **Color** to and from linear encoding using :ref:`srgb_to_linear()` and :ref:`linear_to_srgb()`. + +\ **Note:** In a boolean context, a Color will evaluate to ``false`` if it is equal to ``Color(0, 0, 0, 1)`` (opaque black). Otherwise, a Color will always evaluate to ``true``. + +.. note:: + + There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `2D GD Paint Demo `__ + +- `Tween Interpolation Demo `__ + +- `GUI Drag And Drop Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`a` | ``1.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`a8` | ``255`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`b` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`b8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`g` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`g8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`h` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_h` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_l` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_s` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`r` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`r8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`s` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`v` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + +.. rst-class:: classref-reftable-group + +Constructors +------------ + +.. table:: + :widths: auto + + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`Color`\ (\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`Color`\ (\ from\: :ref:`Color`, alpha\: :ref:`float`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`Color`\ (\ from\: :ref:`Color`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`Color`\ (\ code\: :ref:`String`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`Color`\ (\ code\: :ref:`String`, alpha\: :ref:`float`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`Color`\ (\ r\: :ref:`float`, g\: :ref:`float`, b\: :ref:`float`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`Color`\ (\ r\: :ref:`float`, g\: :ref:`float`, b\: :ref:`float`, a\: :ref:`float`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`blend`\ (\ over\: :ref:`Color`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`clamp`\ (\ min\: :ref:`Color` = Color(0, 0, 0, 0), max\: :ref:`Color` = Color(1, 1, 1, 1)\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`darkened`\ (\ amount\: :ref:`float`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`from_hsv`\ (\ h\: :ref:`float`, s\: :ref:`float`, v\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`from_ok_hsl`\ (\ h\: :ref:`float`, s\: :ref:`float`, l\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`from_rgba8`\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`from_rgbe9995`\ (\ rgbe\: :ref:`int`\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`from_string`\ (\ str\: :ref:`String`, default\: :ref:`Color`\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_luminance`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`hex`\ (\ hex\: :ref:`int`\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`hex64`\ (\ hex\: :ref:`int`\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`html`\ (\ rgba\: :ref:`String`\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`html_is_valid`\ (\ color\: :ref:`String`\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`inverted`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_equal_approx`\ (\ to\: :ref:`Color`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`lerp`\ (\ to\: :ref:`Color`, weight\: :ref:`float`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`lightened`\ (\ amount\: :ref:`float`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`linear_to_srgb`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`srgb_to_linear`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`to_abgr32`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`to_abgr64`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`to_argb32`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`to_argb64`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`to_html`\ (\ with_alpha\: :ref:`bool` = true\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`to_rgba32`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`to_rgba64`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Operators +--------- + +.. table:: + :widths: auto + + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator !=`\ (\ right\: :ref:`Color`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator *`\ (\ right\: :ref:`Color`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator *`\ (\ right\: :ref:`float`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator *`\ (\ right\: :ref:`int`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator +`\ (\ right\: :ref:`Color`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator -`\ (\ right\: :ref:`Color`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator /`\ (\ right\: :ref:`Color`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator /`\ (\ right\: :ref:`float`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator /`\ (\ right\: :ref:`int`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`operator ==`\ (\ right\: :ref:`Color`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`operator []`\ (\ index\: :ref:`int`\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator unary+`\ (\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`operator unary-`\ (\ ) | + +---------------------------+---------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_Color_constant_ALICE_BLUE: + +.. rst-class:: classref-constant + +**ALICE_BLUE** = ``Color(0.9411765, 0.972549, 1, 1)`` :ref:`🔗` + +Alice blue color. + +.. _class_Color_constant_ANTIQUE_WHITE: + +.. rst-class:: classref-constant + +**ANTIQUE_WHITE** = ``Color(0.98039216, 0.92156863, 0.84313726, 1)`` :ref:`🔗` + +Antique white color. + +.. _class_Color_constant_AQUA: + +.. rst-class:: classref-constant + +**AQUA** = ``Color(0, 1, 1, 1)`` :ref:`🔗` + +Aqua color. + +.. _class_Color_constant_AQUAMARINE: + +.. rst-class:: classref-constant + +**AQUAMARINE** = ``Color(0.49803922, 1, 0.83137256, 1)`` :ref:`🔗` + +Aquamarine color. + +.. _class_Color_constant_AZURE: + +.. rst-class:: classref-constant + +**AZURE** = ``Color(0.9411765, 1, 1, 1)`` :ref:`🔗` + +Azure color. + +.. _class_Color_constant_BEIGE: + +.. rst-class:: classref-constant + +**BEIGE** = ``Color(0.9607843, 0.9607843, 0.8627451, 1)`` :ref:`🔗` + +Beige color. + +.. _class_Color_constant_BISQUE: + +.. rst-class:: classref-constant + +**BISQUE** = ``Color(1, 0.89411765, 0.76862746, 1)`` :ref:`🔗` + +Bisque color. + +.. _class_Color_constant_BLACK: + +.. rst-class:: classref-constant + +**BLACK** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +Black color. In GDScript, this is the default value of any color. + +.. _class_Color_constant_BLANCHED_ALMOND: + +.. rst-class:: classref-constant + +**BLANCHED_ALMOND** = ``Color(1, 0.92156863, 0.8039216, 1)`` :ref:`🔗` + +Blanched almond color. + +.. _class_Color_constant_BLUE: + +.. rst-class:: classref-constant + +**BLUE** = ``Color(0, 0, 1, 1)`` :ref:`🔗` + +Blue color. + +.. _class_Color_constant_BLUE_VIOLET: + +.. rst-class:: classref-constant + +**BLUE_VIOLET** = ``Color(0.5411765, 0.16862746, 0.8862745, 1)`` :ref:`🔗` + +Blue violet color. + +.. _class_Color_constant_BROWN: + +.. rst-class:: classref-constant + +**BROWN** = ``Color(0.64705884, 0.16470589, 0.16470589, 1)`` :ref:`🔗` + +Brown color. + +.. _class_Color_constant_BURLYWOOD: + +.. rst-class:: classref-constant + +**BURLYWOOD** = ``Color(0.87058824, 0.72156864, 0.5294118, 1)`` :ref:`🔗` + +Burlywood color. + +.. _class_Color_constant_CADET_BLUE: + +.. rst-class:: classref-constant + +**CADET_BLUE** = ``Color(0.37254903, 0.61960787, 0.627451, 1)`` :ref:`🔗` + +Cadet blue color. + +.. _class_Color_constant_CHARTREUSE: + +.. rst-class:: classref-constant + +**CHARTREUSE** = ``Color(0.49803922, 1, 0, 1)`` :ref:`🔗` + +Chartreuse color. + +.. _class_Color_constant_CHOCOLATE: + +.. rst-class:: classref-constant + +**CHOCOLATE** = ``Color(0.8235294, 0.4117647, 0.11764706, 1)`` :ref:`🔗` + +Chocolate color. + +.. _class_Color_constant_CORAL: + +.. rst-class:: classref-constant + +**CORAL** = ``Color(1, 0.49803922, 0.3137255, 1)`` :ref:`🔗` + +Coral color. + +.. _class_Color_constant_CORNFLOWER_BLUE: + +.. rst-class:: classref-constant + +**CORNFLOWER_BLUE** = ``Color(0.39215687, 0.58431375, 0.92941177, 1)`` :ref:`🔗` + +Cornflower blue color. + +.. _class_Color_constant_CORNSILK: + +.. rst-class:: classref-constant + +**CORNSILK** = ``Color(1, 0.972549, 0.8627451, 1)`` :ref:`🔗` + +Cornsilk color. + +.. _class_Color_constant_CRIMSON: + +.. rst-class:: classref-constant + +**CRIMSON** = ``Color(0.8627451, 0.078431375, 0.23529412, 1)`` :ref:`🔗` + +Crimson color. + +.. _class_Color_constant_CYAN: + +.. rst-class:: classref-constant + +**CYAN** = ``Color(0, 1, 1, 1)`` :ref:`🔗` + +Cyan color. + +.. _class_Color_constant_DARK_BLUE: + +.. rst-class:: classref-constant + +**DARK_BLUE** = ``Color(0, 0, 0.54509807, 1)`` :ref:`🔗` + +Dark blue color. + +.. _class_Color_constant_DARK_CYAN: + +.. rst-class:: classref-constant + +**DARK_CYAN** = ``Color(0, 0.54509807, 0.54509807, 1)`` :ref:`🔗` + +Dark cyan color. + +.. _class_Color_constant_DARK_GOLDENROD: + +.. rst-class:: classref-constant + +**DARK_GOLDENROD** = ``Color(0.72156864, 0.5254902, 0.043137256, 1)`` :ref:`🔗` + +Dark goldenrod color. + +.. _class_Color_constant_DARK_GRAY: + +.. rst-class:: classref-constant + +**DARK_GRAY** = ``Color(0.6627451, 0.6627451, 0.6627451, 1)`` :ref:`🔗` + +Dark gray color. + +.. _class_Color_constant_DARK_GREEN: + +.. rst-class:: classref-constant + +**DARK_GREEN** = ``Color(0, 0.39215687, 0, 1)`` :ref:`🔗` + +Dark green color. + +.. _class_Color_constant_DARK_KHAKI: + +.. rst-class:: classref-constant + +**DARK_KHAKI** = ``Color(0.7411765, 0.7176471, 0.41960785, 1)`` :ref:`🔗` + +Dark khaki color. + +.. _class_Color_constant_DARK_MAGENTA: + +.. rst-class:: classref-constant + +**DARK_MAGENTA** = ``Color(0.54509807, 0, 0.54509807, 1)`` :ref:`🔗` + +Dark magenta color. + +.. _class_Color_constant_DARK_OLIVE_GREEN: + +.. rst-class:: classref-constant + +**DARK_OLIVE_GREEN** = ``Color(0.33333334, 0.41960785, 0.18431373, 1)`` :ref:`🔗` + +Dark olive green color. + +.. _class_Color_constant_DARK_ORANGE: + +.. rst-class:: classref-constant + +**DARK_ORANGE** = ``Color(1, 0.54901963, 0, 1)`` :ref:`🔗` + +Dark orange color. + +.. _class_Color_constant_DARK_ORCHID: + +.. rst-class:: classref-constant + +**DARK_ORCHID** = ``Color(0.6, 0.19607843, 0.8, 1)`` :ref:`🔗` + +Dark orchid color. + +.. _class_Color_constant_DARK_RED: + +.. rst-class:: classref-constant + +**DARK_RED** = ``Color(0.54509807, 0, 0, 1)`` :ref:`🔗` + +Dark red color. + +.. _class_Color_constant_DARK_SALMON: + +.. rst-class:: classref-constant + +**DARK_SALMON** = ``Color(0.9137255, 0.5882353, 0.47843137, 1)`` :ref:`🔗` + +Dark salmon color. + +.. _class_Color_constant_DARK_SEA_GREEN: + +.. rst-class:: classref-constant + +**DARK_SEA_GREEN** = ``Color(0.56078434, 0.7372549, 0.56078434, 1)`` :ref:`🔗` + +Dark sea green color. + +.. _class_Color_constant_DARK_SLATE_BLUE: + +.. rst-class:: classref-constant + +**DARK_SLATE_BLUE** = ``Color(0.28235295, 0.23921569, 0.54509807, 1)`` :ref:`🔗` + +Dark slate blue color. + +.. _class_Color_constant_DARK_SLATE_GRAY: + +.. rst-class:: classref-constant + +**DARK_SLATE_GRAY** = ``Color(0.18431373, 0.30980393, 0.30980393, 1)`` :ref:`🔗` + +Dark slate gray color. + +.. _class_Color_constant_DARK_TURQUOISE: + +.. rst-class:: classref-constant + +**DARK_TURQUOISE** = ``Color(0, 0.80784315, 0.81960785, 1)`` :ref:`🔗` + +Dark turquoise color. + +.. _class_Color_constant_DARK_VIOLET: + +.. rst-class:: classref-constant + +**DARK_VIOLET** = ``Color(0.5803922, 0, 0.827451, 1)`` :ref:`🔗` + +Dark violet color. + +.. _class_Color_constant_DEEP_PINK: + +.. rst-class:: classref-constant + +**DEEP_PINK** = ``Color(1, 0.078431375, 0.5764706, 1)`` :ref:`🔗` + +Deep pink color. + +.. _class_Color_constant_DEEP_SKY_BLUE: + +.. rst-class:: classref-constant + +**DEEP_SKY_BLUE** = ``Color(0, 0.7490196, 1, 1)`` :ref:`🔗` + +Deep sky blue color. + +.. _class_Color_constant_DIM_GRAY: + +.. rst-class:: classref-constant + +**DIM_GRAY** = ``Color(0.4117647, 0.4117647, 0.4117647, 1)`` :ref:`🔗` + +Dim gray color. + +.. _class_Color_constant_DODGER_BLUE: + +.. rst-class:: classref-constant + +**DODGER_BLUE** = ``Color(0.11764706, 0.5647059, 1, 1)`` :ref:`🔗` + +Dodger blue color. + +.. _class_Color_constant_FIREBRICK: + +.. rst-class:: classref-constant + +**FIREBRICK** = ``Color(0.69803923, 0.13333334, 0.13333334, 1)`` :ref:`🔗` + +Firebrick color. + +.. _class_Color_constant_FLORAL_WHITE: + +.. rst-class:: classref-constant + +**FLORAL_WHITE** = ``Color(1, 0.98039216, 0.9411765, 1)`` :ref:`🔗` + +Floral white color. + +.. _class_Color_constant_FOREST_GREEN: + +.. rst-class:: classref-constant + +**FOREST_GREEN** = ``Color(0.13333334, 0.54509807, 0.13333334, 1)`` :ref:`🔗` + +Forest green color. + +.. _class_Color_constant_FUCHSIA: + +.. rst-class:: classref-constant + +**FUCHSIA** = ``Color(1, 0, 1, 1)`` :ref:`🔗` + +Fuchsia color. + +.. _class_Color_constant_GAINSBORO: + +.. rst-class:: classref-constant + +**GAINSBORO** = ``Color(0.8627451, 0.8627451, 0.8627451, 1)`` :ref:`🔗` + +Gainsboro color. + +.. _class_Color_constant_GHOST_WHITE: + +.. rst-class:: classref-constant + +**GHOST_WHITE** = ``Color(0.972549, 0.972549, 1, 1)`` :ref:`🔗` + +Ghost white color. + +.. _class_Color_constant_GOLD: + +.. rst-class:: classref-constant + +**GOLD** = ``Color(1, 0.84313726, 0, 1)`` :ref:`🔗` + +Gold color. + +.. _class_Color_constant_GOLDENROD: + +.. rst-class:: classref-constant + +**GOLDENROD** = ``Color(0.85490197, 0.64705884, 0.1254902, 1)`` :ref:`🔗` + +Goldenrod color. + +.. _class_Color_constant_GRAY: + +.. rst-class:: classref-constant + +**GRAY** = ``Color(0.74509805, 0.74509805, 0.74509805, 1)`` :ref:`🔗` + +Gray color. + +.. _class_Color_constant_GREEN: + +.. rst-class:: classref-constant + +**GREEN** = ``Color(0, 1, 0, 1)`` :ref:`🔗` + +Green color. + +.. _class_Color_constant_GREEN_YELLOW: + +.. rst-class:: classref-constant + +**GREEN_YELLOW** = ``Color(0.6784314, 1, 0.18431373, 1)`` :ref:`🔗` + +Green yellow color. + +.. _class_Color_constant_HONEYDEW: + +.. rst-class:: classref-constant + +**HONEYDEW** = ``Color(0.9411765, 1, 0.9411765, 1)`` :ref:`🔗` + +Honeydew color. + +.. _class_Color_constant_HOT_PINK: + +.. rst-class:: classref-constant + +**HOT_PINK** = ``Color(1, 0.4117647, 0.7058824, 1)`` :ref:`🔗` + +Hot pink color. + +.. _class_Color_constant_INDIAN_RED: + +.. rst-class:: classref-constant + +**INDIAN_RED** = ``Color(0.8039216, 0.36078432, 0.36078432, 1)`` :ref:`🔗` + +Indian red color. + +.. _class_Color_constant_INDIGO: + +.. rst-class:: classref-constant + +**INDIGO** = ``Color(0.29411766, 0, 0.50980395, 1)`` :ref:`🔗` + +Indigo color. + +.. _class_Color_constant_IVORY: + +.. rst-class:: classref-constant + +**IVORY** = ``Color(1, 1, 0.9411765, 1)`` :ref:`🔗` + +Ivory color. + +.. _class_Color_constant_KHAKI: + +.. rst-class:: classref-constant + +**KHAKI** = ``Color(0.9411765, 0.9019608, 0.54901963, 1)`` :ref:`🔗` + +Khaki color. + +.. _class_Color_constant_LAVENDER: + +.. rst-class:: classref-constant + +**LAVENDER** = ``Color(0.9019608, 0.9019608, 0.98039216, 1)`` :ref:`🔗` + +Lavender color. + +.. _class_Color_constant_LAVENDER_BLUSH: + +.. rst-class:: classref-constant + +**LAVENDER_BLUSH** = ``Color(1, 0.9411765, 0.9607843, 1)`` :ref:`🔗` + +Lavender blush color. + +.. _class_Color_constant_LAWN_GREEN: + +.. rst-class:: classref-constant + +**LAWN_GREEN** = ``Color(0.4862745, 0.9882353, 0, 1)`` :ref:`🔗` + +Lawn green color. + +.. _class_Color_constant_LEMON_CHIFFON: + +.. rst-class:: classref-constant + +**LEMON_CHIFFON** = ``Color(1, 0.98039216, 0.8039216, 1)`` :ref:`🔗` + +Lemon chiffon color. + +.. _class_Color_constant_LIGHT_BLUE: + +.. rst-class:: classref-constant + +**LIGHT_BLUE** = ``Color(0.6784314, 0.84705883, 0.9019608, 1)`` :ref:`🔗` + +Light blue color. + +.. _class_Color_constant_LIGHT_CORAL: + +.. rst-class:: classref-constant + +**LIGHT_CORAL** = ``Color(0.9411765, 0.5019608, 0.5019608, 1)`` :ref:`🔗` + +Light coral color. + +.. _class_Color_constant_LIGHT_CYAN: + +.. rst-class:: classref-constant + +**LIGHT_CYAN** = ``Color(0.8784314, 1, 1, 1)`` :ref:`🔗` + +Light cyan color. + +.. _class_Color_constant_LIGHT_GOLDENROD: + +.. rst-class:: classref-constant + +**LIGHT_GOLDENROD** = ``Color(0.98039216, 0.98039216, 0.8235294, 1)`` :ref:`🔗` + +Light goldenrod color. + +.. _class_Color_constant_LIGHT_GRAY: + +.. rst-class:: classref-constant + +**LIGHT_GRAY** = ``Color(0.827451, 0.827451, 0.827451, 1)`` :ref:`🔗` + +Light gray color. + +.. _class_Color_constant_LIGHT_GREEN: + +.. rst-class:: classref-constant + +**LIGHT_GREEN** = ``Color(0.5647059, 0.93333334, 0.5647059, 1)`` :ref:`🔗` + +Light green color. + +.. _class_Color_constant_LIGHT_PINK: + +.. rst-class:: classref-constant + +**LIGHT_PINK** = ``Color(1, 0.7137255, 0.75686276, 1)`` :ref:`🔗` + +Light pink color. + +.. _class_Color_constant_LIGHT_SALMON: + +.. rst-class:: classref-constant + +**LIGHT_SALMON** = ``Color(1, 0.627451, 0.47843137, 1)`` :ref:`🔗` + +Light salmon color. + +.. _class_Color_constant_LIGHT_SEA_GREEN: + +.. rst-class:: classref-constant + +**LIGHT_SEA_GREEN** = ``Color(0.1254902, 0.69803923, 0.6666667, 1)`` :ref:`🔗` + +Light sea green color. + +.. _class_Color_constant_LIGHT_SKY_BLUE: + +.. rst-class:: classref-constant + +**LIGHT_SKY_BLUE** = ``Color(0.5294118, 0.80784315, 0.98039216, 1)`` :ref:`🔗` + +Light sky blue color. + +.. _class_Color_constant_LIGHT_SLATE_GRAY: + +.. rst-class:: classref-constant + +**LIGHT_SLATE_GRAY** = ``Color(0.46666667, 0.53333336, 0.6, 1)`` :ref:`🔗` + +Light slate gray color. + +.. _class_Color_constant_LIGHT_STEEL_BLUE: + +.. rst-class:: classref-constant + +**LIGHT_STEEL_BLUE** = ``Color(0.6901961, 0.76862746, 0.87058824, 1)`` :ref:`🔗` + +Light steel blue color. + +.. _class_Color_constant_LIGHT_YELLOW: + +.. rst-class:: classref-constant + +**LIGHT_YELLOW** = ``Color(1, 1, 0.8784314, 1)`` :ref:`🔗` + +Light yellow color. + +.. _class_Color_constant_LIME: + +.. rst-class:: classref-constant + +**LIME** = ``Color(0, 1, 0, 1)`` :ref:`🔗` + +Lime color. + +.. _class_Color_constant_LIME_GREEN: + +.. rst-class:: classref-constant + +**LIME_GREEN** = ``Color(0.19607843, 0.8039216, 0.19607843, 1)`` :ref:`🔗` + +Lime green color. + +.. _class_Color_constant_LINEN: + +.. rst-class:: classref-constant + +**LINEN** = ``Color(0.98039216, 0.9411765, 0.9019608, 1)`` :ref:`🔗` + +Linen color. + +.. _class_Color_constant_MAGENTA: + +.. rst-class:: classref-constant + +**MAGENTA** = ``Color(1, 0, 1, 1)`` :ref:`🔗` + +Magenta color. + +.. _class_Color_constant_MAROON: + +.. rst-class:: classref-constant + +**MAROON** = ``Color(0.6901961, 0.1882353, 0.3764706, 1)`` :ref:`🔗` + +Maroon color. + +.. _class_Color_constant_MEDIUM_AQUAMARINE: + +.. rst-class:: classref-constant + +**MEDIUM_AQUAMARINE** = ``Color(0.4, 0.8039216, 0.6666667, 1)`` :ref:`🔗` + +Medium aquamarine color. + +.. _class_Color_constant_MEDIUM_BLUE: + +.. rst-class:: classref-constant + +**MEDIUM_BLUE** = ``Color(0, 0, 0.8039216, 1)`` :ref:`🔗` + +Medium blue color. + +.. _class_Color_constant_MEDIUM_ORCHID: + +.. rst-class:: classref-constant + +**MEDIUM_ORCHID** = ``Color(0.7294118, 0.33333334, 0.827451, 1)`` :ref:`🔗` + +Medium orchid color. + +.. _class_Color_constant_MEDIUM_PURPLE: + +.. rst-class:: classref-constant + +**MEDIUM_PURPLE** = ``Color(0.5764706, 0.4392157, 0.85882354, 1)`` :ref:`🔗` + +Medium purple color. + +.. _class_Color_constant_MEDIUM_SEA_GREEN: + +.. rst-class:: classref-constant + +**MEDIUM_SEA_GREEN** = ``Color(0.23529412, 0.7019608, 0.44313726, 1)`` :ref:`🔗` + +Medium sea green color. + +.. _class_Color_constant_MEDIUM_SLATE_BLUE: + +.. rst-class:: classref-constant + +**MEDIUM_SLATE_BLUE** = ``Color(0.48235294, 0.40784314, 0.93333334, 1)`` :ref:`🔗` + +Medium slate blue color. + +.. _class_Color_constant_MEDIUM_SPRING_GREEN: + +.. rst-class:: classref-constant + +**MEDIUM_SPRING_GREEN** = ``Color(0, 0.98039216, 0.6039216, 1)`` :ref:`🔗` + +Medium spring green color. + +.. _class_Color_constant_MEDIUM_TURQUOISE: + +.. rst-class:: classref-constant + +**MEDIUM_TURQUOISE** = ``Color(0.28235295, 0.81960785, 0.8, 1)`` :ref:`🔗` + +Medium turquoise color. + +.. _class_Color_constant_MEDIUM_VIOLET_RED: + +.. rst-class:: classref-constant + +**MEDIUM_VIOLET_RED** = ``Color(0.78039217, 0.08235294, 0.52156866, 1)`` :ref:`🔗` + +Medium violet red color. + +.. _class_Color_constant_MIDNIGHT_BLUE: + +.. rst-class:: classref-constant + +**MIDNIGHT_BLUE** = ``Color(0.09803922, 0.09803922, 0.4392157, 1)`` :ref:`🔗` + +Midnight blue color. + +.. _class_Color_constant_MINT_CREAM: + +.. rst-class:: classref-constant + +**MINT_CREAM** = ``Color(0.9607843, 1, 0.98039216, 1)`` :ref:`🔗` + +Mint cream color. + +.. _class_Color_constant_MISTY_ROSE: + +.. rst-class:: classref-constant + +**MISTY_ROSE** = ``Color(1, 0.89411765, 0.88235295, 1)`` :ref:`🔗` + +Misty rose color. + +.. _class_Color_constant_MOCCASIN: + +.. rst-class:: classref-constant + +**MOCCASIN** = ``Color(1, 0.89411765, 0.70980394, 1)`` :ref:`🔗` + +Moccasin color. + +.. _class_Color_constant_NAVAJO_WHITE: + +.. rst-class:: classref-constant + +**NAVAJO_WHITE** = ``Color(1, 0.87058824, 0.6784314, 1)`` :ref:`🔗` + +Navajo white color. + +.. _class_Color_constant_NAVY_BLUE: + +.. rst-class:: classref-constant + +**NAVY_BLUE** = ``Color(0, 0, 0.5019608, 1)`` :ref:`🔗` + +Navy blue color. + +.. _class_Color_constant_OLD_LACE: + +.. rst-class:: classref-constant + +**OLD_LACE** = ``Color(0.99215686, 0.9607843, 0.9019608, 1)`` :ref:`🔗` + +Old lace color. + +.. _class_Color_constant_OLIVE: + +.. rst-class:: classref-constant + +**OLIVE** = ``Color(0.5019608, 0.5019608, 0, 1)`` :ref:`🔗` + +Olive color. + +.. _class_Color_constant_OLIVE_DRAB: + +.. rst-class:: classref-constant + +**OLIVE_DRAB** = ``Color(0.41960785, 0.5568628, 0.13725491, 1)`` :ref:`🔗` + +Olive drab color. + +.. _class_Color_constant_ORANGE: + +.. rst-class:: classref-constant + +**ORANGE** = ``Color(1, 0.64705884, 0, 1)`` :ref:`🔗` + +Orange color. + +.. _class_Color_constant_ORANGE_RED: + +.. rst-class:: classref-constant + +**ORANGE_RED** = ``Color(1, 0.27058825, 0, 1)`` :ref:`🔗` + +Orange red color. + +.. _class_Color_constant_ORCHID: + +.. rst-class:: classref-constant + +**ORCHID** = ``Color(0.85490197, 0.4392157, 0.8392157, 1)`` :ref:`🔗` + +Orchid color. + +.. _class_Color_constant_PALE_GOLDENROD: + +.. rst-class:: classref-constant + +**PALE_GOLDENROD** = ``Color(0.93333334, 0.9098039, 0.6666667, 1)`` :ref:`🔗` + +Pale goldenrod color. + +.. _class_Color_constant_PALE_GREEN: + +.. rst-class:: classref-constant + +**PALE_GREEN** = ``Color(0.59607846, 0.9843137, 0.59607846, 1)`` :ref:`🔗` + +Pale green color. + +.. _class_Color_constant_PALE_TURQUOISE: + +.. rst-class:: classref-constant + +**PALE_TURQUOISE** = ``Color(0.6862745, 0.93333334, 0.93333334, 1)`` :ref:`🔗` + +Pale turquoise color. + +.. _class_Color_constant_PALE_VIOLET_RED: + +.. rst-class:: classref-constant + +**PALE_VIOLET_RED** = ``Color(0.85882354, 0.4392157, 0.5764706, 1)`` :ref:`🔗` + +Pale violet red color. + +.. _class_Color_constant_PAPAYA_WHIP: + +.. rst-class:: classref-constant + +**PAPAYA_WHIP** = ``Color(1, 0.9372549, 0.8352941, 1)`` :ref:`🔗` + +Papaya whip color. + +.. _class_Color_constant_PEACH_PUFF: + +.. rst-class:: classref-constant + +**PEACH_PUFF** = ``Color(1, 0.85490197, 0.7254902, 1)`` :ref:`🔗` + +Peach puff color. + +.. _class_Color_constant_PERU: + +.. rst-class:: classref-constant + +**PERU** = ``Color(0.8039216, 0.52156866, 0.24705882, 1)`` :ref:`🔗` + +Peru color. + +.. _class_Color_constant_PINK: + +.. rst-class:: classref-constant + +**PINK** = ``Color(1, 0.7529412, 0.79607844, 1)`` :ref:`🔗` + +Pink color. + +.. _class_Color_constant_PLUM: + +.. rst-class:: classref-constant + +**PLUM** = ``Color(0.8666667, 0.627451, 0.8666667, 1)`` :ref:`🔗` + +Plum color. + +.. _class_Color_constant_POWDER_BLUE: + +.. rst-class:: classref-constant + +**POWDER_BLUE** = ``Color(0.6901961, 0.8784314, 0.9019608, 1)`` :ref:`🔗` + +Powder blue color. + +.. _class_Color_constant_PURPLE: + +.. rst-class:: classref-constant + +**PURPLE** = ``Color(0.627451, 0.1254902, 0.9411765, 1)`` :ref:`🔗` + +Purple color. + +.. _class_Color_constant_REBECCA_PURPLE: + +.. rst-class:: classref-constant + +**REBECCA_PURPLE** = ``Color(0.4, 0.2, 0.6, 1)`` :ref:`🔗` + +Rebecca purple color. + +.. _class_Color_constant_RED: + +.. rst-class:: classref-constant + +**RED** = ``Color(1, 0, 0, 1)`` :ref:`🔗` + +Red color. + +.. _class_Color_constant_ROSY_BROWN: + +.. rst-class:: classref-constant + +**ROSY_BROWN** = ``Color(0.7372549, 0.56078434, 0.56078434, 1)`` :ref:`🔗` + +Rosy brown color. + +.. _class_Color_constant_ROYAL_BLUE: + +.. rst-class:: classref-constant + +**ROYAL_BLUE** = ``Color(0.25490198, 0.4117647, 0.88235295, 1)`` :ref:`🔗` + +Royal blue color. + +.. _class_Color_constant_SADDLE_BROWN: + +.. rst-class:: classref-constant + +**SADDLE_BROWN** = ``Color(0.54509807, 0.27058825, 0.07450981, 1)`` :ref:`🔗` + +Saddle brown color. + +.. _class_Color_constant_SALMON: + +.. rst-class:: classref-constant + +**SALMON** = ``Color(0.98039216, 0.5019608, 0.44705883, 1)`` :ref:`🔗` + +Salmon color. + +.. _class_Color_constant_SANDY_BROWN: + +.. rst-class:: classref-constant + +**SANDY_BROWN** = ``Color(0.95686275, 0.6431373, 0.3764706, 1)`` :ref:`🔗` + +Sandy brown color. + +.. _class_Color_constant_SEA_GREEN: + +.. rst-class:: classref-constant + +**SEA_GREEN** = ``Color(0.18039216, 0.54509807, 0.34117648, 1)`` :ref:`🔗` + +Sea green color. + +.. _class_Color_constant_SEASHELL: + +.. rst-class:: classref-constant + +**SEASHELL** = ``Color(1, 0.9607843, 0.93333334, 1)`` :ref:`🔗` + +Seashell color. + +.. _class_Color_constant_SIENNA: + +.. rst-class:: classref-constant + +**SIENNA** = ``Color(0.627451, 0.32156864, 0.1764706, 1)`` :ref:`🔗` + +Sienna color. + +.. _class_Color_constant_SILVER: + +.. rst-class:: classref-constant + +**SILVER** = ``Color(0.7529412, 0.7529412, 0.7529412, 1)`` :ref:`🔗` + +Silver color. + +.. _class_Color_constant_SKY_BLUE: + +.. rst-class:: classref-constant + +**SKY_BLUE** = ``Color(0.5294118, 0.80784315, 0.92156863, 1)`` :ref:`🔗` + +Sky blue color. + +.. _class_Color_constant_SLATE_BLUE: + +.. rst-class:: classref-constant + +**SLATE_BLUE** = ``Color(0.41568628, 0.3529412, 0.8039216, 1)`` :ref:`🔗` + +Slate blue color. + +.. _class_Color_constant_SLATE_GRAY: + +.. rst-class:: classref-constant + +**SLATE_GRAY** = ``Color(0.4392157, 0.5019608, 0.5647059, 1)`` :ref:`🔗` + +Slate gray color. + +.. _class_Color_constant_SNOW: + +.. rst-class:: classref-constant + +**SNOW** = ``Color(1, 0.98039216, 0.98039216, 1)`` :ref:`🔗` + +Snow color. + +.. _class_Color_constant_SPRING_GREEN: + +.. rst-class:: classref-constant + +**SPRING_GREEN** = ``Color(0, 1, 0.49803922, 1)`` :ref:`🔗` + +Spring green color. + +.. _class_Color_constant_STEEL_BLUE: + +.. rst-class:: classref-constant + +**STEEL_BLUE** = ``Color(0.27450982, 0.50980395, 0.7058824, 1)`` :ref:`🔗` + +Steel blue color. + +.. _class_Color_constant_TAN: + +.. rst-class:: classref-constant + +**TAN** = ``Color(0.8235294, 0.7058824, 0.54901963, 1)`` :ref:`🔗` + +Tan color. + +.. _class_Color_constant_TEAL: + +.. rst-class:: classref-constant + +**TEAL** = ``Color(0, 0.5019608, 0.5019608, 1)`` :ref:`🔗` + +Teal color. + +.. _class_Color_constant_THISTLE: + +.. rst-class:: classref-constant + +**THISTLE** = ``Color(0.84705883, 0.7490196, 0.84705883, 1)`` :ref:`🔗` + +Thistle color. + +.. _class_Color_constant_TOMATO: -You can also create a color from standardized color names by using :ref:`@GDScript.ColorN` or directly using the color constants defined here. The standardized color set is based on the `X11 color names `_. +.. rst-class:: classref-constant -Properties ----------- +**TOMATO** = ``Color(1, 0.3882353, 0.2784314, 1)`` :ref:`🔗` -+---------------------------+------------------------------------+---------+ -| :ref:`float` | :ref:`a` | ``1.0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`int` | :ref:`a8` | ``255`` | -+---------------------------+------------------------------------+---------+ -| :ref:`float` | :ref:`b` | ``0.0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`int` | :ref:`b8` | ``0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`float` | :ref:`g` | ``0.0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`int` | :ref:`g8` | ``0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`float` | :ref:`h` | ``0.0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`float` | :ref:`r` | ``0.0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`int` | :ref:`r8` | ``0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`float` | :ref:`s` | ``0.0`` | -+---------------------------+------------------------------------+---------+ -| :ref:`float` | :ref:`v` | ``0.0`` | -+---------------------------+------------------------------------+---------+ +Tomato color. -Methods -------- +.. _class_Color_constant_TRANSPARENT: -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`Color` **(** :ref:`String` from **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`Color` **(** :ref:`int` from **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`Color` **(** :ref:`float` r, :ref:`float` g, :ref:`float` b **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`Color` **(** :ref:`float` r, :ref:`float` g, :ref:`float` b, :ref:`float` a **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`blend` **(** :ref:`Color` over **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`contrasted` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`darkened` **(** :ref:`float` amount **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`from_hsv` **(** :ref:`float` h, :ref:`float` s, :ref:`float` v, :ref:`float` a=1.0 **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`inverted` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_equal_approx` **(** :ref:`Color` color **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`lightened` **(** :ref:`float` amount **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`linear_interpolate` **(** :ref:`Color` b, :ref:`float` t **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`to_abgr32` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`to_abgr64` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`to_argb32` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`to_argb64` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`to_html` **(** :ref:`bool` with_alpha=true **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`to_rgba32` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`to_rgba64` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. rst-class:: classref-constant -Constants ---------- +**TRANSPARENT** = ``Color(1, 1, 1, 0)`` :ref:`🔗` -.. _class_Color_constant_aliceblue: +Transparent color (white with zero alpha). -.. _class_Color_constant_antiquewhite: +.. _class_Color_constant_TURQUOISE: -.. _class_Color_constant_aqua: +.. rst-class:: classref-constant -.. _class_Color_constant_aquamarine: +**TURQUOISE** = ``Color(0.2509804, 0.8784314, 0.8156863, 1)`` :ref:`🔗` -.. _class_Color_constant_azure: +Turquoise color. -.. _class_Color_constant_beige: +.. _class_Color_constant_VIOLET: -.. _class_Color_constant_bisque: +.. rst-class:: classref-constant -.. _class_Color_constant_black: +**VIOLET** = ``Color(0.93333334, 0.50980395, 0.93333334, 1)`` :ref:`🔗` -.. _class_Color_constant_blanchedalmond: +Violet color. -.. _class_Color_constant_blue: +.. _class_Color_constant_WEB_GRAY: -.. _class_Color_constant_blueviolet: +.. rst-class:: classref-constant -.. _class_Color_constant_brown: +**WEB_GRAY** = ``Color(0.5019608, 0.5019608, 0.5019608, 1)`` :ref:`🔗` -.. _class_Color_constant_burlywood: +Web gray color. -.. _class_Color_constant_cadetblue: +.. _class_Color_constant_WEB_GREEN: -.. _class_Color_constant_chartreuse: +.. rst-class:: classref-constant -.. _class_Color_constant_chocolate: +**WEB_GREEN** = ``Color(0, 0.5019608, 0, 1)`` :ref:`🔗` -.. _class_Color_constant_coral: +Web green color. -.. _class_Color_constant_cornflower: +.. _class_Color_constant_WEB_MAROON: -.. _class_Color_constant_cornsilk: +.. rst-class:: classref-constant -.. _class_Color_constant_crimson: +**WEB_MAROON** = ``Color(0.5019608, 0, 0, 1)`` :ref:`🔗` -.. _class_Color_constant_cyan: +Web maroon color. -.. _class_Color_constant_darkblue: +.. _class_Color_constant_WEB_PURPLE: -.. _class_Color_constant_darkcyan: +.. rst-class:: classref-constant -.. _class_Color_constant_darkgoldenrod: +**WEB_PURPLE** = ``Color(0.5019608, 0, 0.5019608, 1)`` :ref:`🔗` -.. _class_Color_constant_darkgray: +Web purple color. -.. _class_Color_constant_darkgreen: +.. _class_Color_constant_WHEAT: -.. _class_Color_constant_darkkhaki: +.. rst-class:: classref-constant -.. _class_Color_constant_darkmagenta: +**WHEAT** = ``Color(0.9607843, 0.87058824, 0.7019608, 1)`` :ref:`🔗` -.. _class_Color_constant_darkolivegreen: +Wheat color. -.. _class_Color_constant_darkorange: +.. _class_Color_constant_WHITE: -.. _class_Color_constant_darkorchid: +.. rst-class:: classref-constant -.. _class_Color_constant_darkred: +**WHITE** = ``Color(1, 1, 1, 1)`` :ref:`🔗` -.. _class_Color_constant_darksalmon: +White color. -.. _class_Color_constant_darkseagreen: +.. _class_Color_constant_WHITE_SMOKE: -.. _class_Color_constant_darkslateblue: +.. rst-class:: classref-constant -.. _class_Color_constant_darkslategray: +**WHITE_SMOKE** = ``Color(0.9607843, 0.9607843, 0.9607843, 1)`` :ref:`🔗` -.. _class_Color_constant_darkturquoise: +White smoke color. -.. _class_Color_constant_darkviolet: +.. _class_Color_constant_YELLOW: -.. _class_Color_constant_deeppink: +.. rst-class:: classref-constant -.. _class_Color_constant_deepskyblue: +**YELLOW** = ``Color(1, 1, 0, 1)`` :ref:`🔗` -.. _class_Color_constant_dimgray: +Yellow color. -.. _class_Color_constant_dodgerblue: +.. _class_Color_constant_YELLOW_GREEN: -.. _class_Color_constant_firebrick: +.. rst-class:: classref-constant -.. _class_Color_constant_floralwhite: +**YELLOW_GREEN** = ``Color(0.6039216, 0.8039216, 0.19607843, 1)`` :ref:`🔗` -.. _class_Color_constant_forestgreen: +Yellow green color. -.. _class_Color_constant_fuchsia: +.. rst-class:: classref-section-separator -.. _class_Color_constant_gainsboro: +---- -.. _class_Color_constant_ghostwhite: +.. rst-class:: classref-descriptions-group -.. _class_Color_constant_gold: +Property Descriptions +--------------------- -.. _class_Color_constant_goldenrod: +.. _class_Color_property_a: -.. _class_Color_constant_gray: +.. rst-class:: classref-property -.. _class_Color_constant_green: +:ref:`float` **a** = ``1.0`` :ref:`🔗` -.. _class_Color_constant_greenyellow: +The color's alpha component, typically on the range of 0 to 1. A value of 0 means that the color is fully transparent. A value of 1 means that the color is fully opaque. -.. _class_Color_constant_honeydew: +\ **Note:** The alpha channel is always stored with linear encoding, regardless of the encoding of the other color channels. The :ref:`linear_to_srgb()` and :ref:`srgb_to_linear()` methods do not affect the alpha channel. -.. _class_Color_constant_hotpink: +.. rst-class:: classref-item-separator -.. _class_Color_constant_indianred: +---- -.. _class_Color_constant_indigo: +.. _class_Color_property_a8: -.. _class_Color_constant_ivory: +.. rst-class:: classref-property -.. _class_Color_constant_khaki: +:ref:`int` **a8** = ``255`` :ref:`🔗` -.. _class_Color_constant_lavender: +Wrapper for :ref:`a` that uses the range 0 to 255, instead of 0 to 1. -.. _class_Color_constant_lavenderblush: +.. rst-class:: classref-item-separator -.. _class_Color_constant_lawngreen: +---- -.. _class_Color_constant_lemonchiffon: +.. _class_Color_property_b: -.. _class_Color_constant_lightblue: +.. rst-class:: classref-property -.. _class_Color_constant_lightcoral: +:ref:`float` **b** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_lightcyan: +The color's blue component, typically on the range of 0 to 1. -.. _class_Color_constant_lightgoldenrod: +.. rst-class:: classref-item-separator -.. _class_Color_constant_lightgray: +---- -.. _class_Color_constant_lightgreen: +.. _class_Color_property_b8: -.. _class_Color_constant_lightpink: +.. rst-class:: classref-property -.. _class_Color_constant_lightsalmon: +:ref:`int` **b8** = ``0`` :ref:`🔗` -.. _class_Color_constant_lightseagreen: +Wrapper for :ref:`b` that uses the range 0 to 255, instead of 0 to 1. -.. _class_Color_constant_lightskyblue: +.. rst-class:: classref-item-separator -.. _class_Color_constant_lightslategray: +---- -.. _class_Color_constant_lightsteelblue: +.. _class_Color_property_g: -.. _class_Color_constant_lightyellow: +.. rst-class:: classref-property -.. _class_Color_constant_lime: +:ref:`float` **g** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_limegreen: +The color's green component, typically on the range of 0 to 1. -.. _class_Color_constant_linen: +.. rst-class:: classref-item-separator -.. _class_Color_constant_magenta: +---- -.. _class_Color_constant_maroon: +.. _class_Color_property_g8: -.. _class_Color_constant_mediumaquamarine: +.. rst-class:: classref-property -.. _class_Color_constant_mediumblue: +:ref:`int` **g8** = ``0`` :ref:`🔗` -.. _class_Color_constant_mediumorchid: +Wrapper for :ref:`g` that uses the range 0 to 255, instead of 0 to 1. -.. _class_Color_constant_mediumpurple: +.. rst-class:: classref-item-separator -.. _class_Color_constant_mediumseagreen: +---- -.. _class_Color_constant_mediumslateblue: +.. _class_Color_property_h: -.. _class_Color_constant_mediumspringgreen: +.. rst-class:: classref-property -.. _class_Color_constant_mediumturquoise: +:ref:`float` **h** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_mediumvioletred: +The HSV hue of this color, on the range 0 to 1. -.. _class_Color_constant_midnightblue: +.. rst-class:: classref-item-separator -.. _class_Color_constant_mintcream: +---- -.. _class_Color_constant_mistyrose: +.. _class_Color_property_ok_hsl_h: -.. _class_Color_constant_moccasin: +.. rst-class:: classref-property -.. _class_Color_constant_navajowhite: +:ref:`float` **ok_hsl_h** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_navyblue: +The OKHSL hue of this color, on the range 0 to 1. -.. _class_Color_constant_oldlace: +.. rst-class:: classref-item-separator -.. _class_Color_constant_olive: +---- -.. _class_Color_constant_olivedrab: +.. _class_Color_property_ok_hsl_l: -.. _class_Color_constant_orange: +.. rst-class:: classref-property -.. _class_Color_constant_orangered: +:ref:`float` **ok_hsl_l** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_orchid: +The OKHSL lightness of this color, on the range 0 to 1. -.. _class_Color_constant_palegoldenrod: +.. rst-class:: classref-item-separator -.. _class_Color_constant_palegreen: +---- -.. _class_Color_constant_paleturquoise: +.. _class_Color_property_ok_hsl_s: -.. _class_Color_constant_palevioletred: +.. rst-class:: classref-property -.. _class_Color_constant_papayawhip: +:ref:`float` **ok_hsl_s** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_peachpuff: +The OKHSL saturation of this color, on the range 0 to 1. -.. _class_Color_constant_peru: +.. rst-class:: classref-item-separator -.. _class_Color_constant_pink: +---- -.. _class_Color_constant_plum: +.. _class_Color_property_r: -.. _class_Color_constant_powderblue: +.. rst-class:: classref-property -.. _class_Color_constant_purple: +:ref:`float` **r** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_rebeccapurple: +The color's red component, typically on the range of 0 to 1. -.. _class_Color_constant_red: +.. rst-class:: classref-item-separator -.. _class_Color_constant_rosybrown: +---- -.. _class_Color_constant_royalblue: +.. _class_Color_property_r8: -.. _class_Color_constant_saddlebrown: +.. rst-class:: classref-property -.. _class_Color_constant_salmon: +:ref:`int` **r8** = ``0`` :ref:`🔗` -.. _class_Color_constant_sandybrown: +Wrapper for :ref:`r` that uses the range 0 to 255, instead of 0 to 1. -.. _class_Color_constant_seagreen: +.. rst-class:: classref-item-separator -.. _class_Color_constant_seashell: +---- -.. _class_Color_constant_sienna: +.. _class_Color_property_s: -.. _class_Color_constant_silver: +.. rst-class:: classref-property -.. _class_Color_constant_skyblue: +:ref:`float` **s** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_slateblue: +The HSV saturation of this color, on the range 0 to 1. -.. _class_Color_constant_slategray: +.. rst-class:: classref-item-separator -.. _class_Color_constant_snow: +---- -.. _class_Color_constant_springgreen: +.. _class_Color_property_v: -.. _class_Color_constant_steelblue: +.. rst-class:: classref-property -.. _class_Color_constant_tan: +:ref:`float` **v** = ``0.0`` :ref:`🔗` -.. _class_Color_constant_teal: +The HSV value (brightness) of this color, on the range 0 to 1. -.. _class_Color_constant_thistle: +.. rst-class:: classref-section-separator -.. _class_Color_constant_tomato: +---- -.. _class_Color_constant_transparent: +.. rst-class:: classref-descriptions-group -.. _class_Color_constant_turquoise: +Constructor Descriptions +------------------------ -.. _class_Color_constant_violet: +.. _class_Color_constructor_Color: -.. _class_Color_constant_webgray: +.. rst-class:: classref-constructor -.. _class_Color_constant_webgreen: +:ref:`Color` **Color**\ (\ ) :ref:`🔗` -.. _class_Color_constant_webmaroon: +Constructs a default **Color** from opaque black. This is the same as :ref:`BLACK`. -.. _class_Color_constant_webpurple: +\ **Note:** In C#, this constructs a **Color** with all of its components set to ``0.0`` (transparent black). -.. _class_Color_constant_wheat: +.. rst-class:: classref-item-separator -.. _class_Color_constant_white: +---- -.. _class_Color_constant_whitesmoke: +.. rst-class:: classref-constructor -.. _class_Color_constant_yellow: +:ref:`Color` **Color**\ (\ from\: :ref:`Color`, alpha\: :ref:`float`\ ) -.. _class_Color_constant_yellowgreen: +Constructs a **Color** from the existing color, with :ref:`a` set to the given ``alpha`` value. -- **aliceblue** = **Color( 0.94, 0.97, 1, 1 )** --- Alice blue color. -- **antiquewhite** = **Color( 0.98, 0.92, 0.84, 1 )** --- Antique white color. +.. tabs:: -- **aqua** = **Color( 0, 1, 1, 1 )** --- Aqua color. + .. code-tab:: gdscript -- **aquamarine** = **Color( 0.5, 1, 0.83, 1 )** --- Aquamarine color. + var red = Color(Color.RED, 0.2) # 20% opaque red. -- **azure** = **Color( 0.94, 1, 1, 1 )** --- Azure color. + .. code-tab:: csharp -- **beige** = **Color( 0.96, 0.96, 0.86, 1 )** --- Beige color. + var red = new Color(Colors.Red, 0.2f); // 20% opaque red. -- **bisque** = **Color( 1, 0.89, 0.77, 1 )** --- Bisque color. -- **black** = **Color( 0, 0, 0, 1 )** --- Black color. -- **blanchedalmond** = **Color( 1, 0.92, 0.8, 1 )** --- Blanche almond color. +.. rst-class:: classref-item-separator -- **blue** = **Color( 0, 0, 1, 1 )** --- Blue color. +---- -- **blueviolet** = **Color( 0.54, 0.17, 0.89, 1 )** --- Blue violet color. +.. rst-class:: classref-constructor -- **brown** = **Color( 0.65, 0.16, 0.16, 1 )** --- Brown color. +:ref:`Color` **Color**\ (\ from\: :ref:`Color`\ ) -- **burlywood** = **Color( 0.87, 0.72, 0.53, 1 )** --- Burly wood color. +Constructs a **Color** as a copy of the given **Color**. -- **cadetblue** = **Color( 0.37, 0.62, 0.63, 1 )** --- Cadet blue color. +.. rst-class:: classref-item-separator -- **chartreuse** = **Color( 0.5, 1, 0, 1 )** --- Chartreuse color. +---- -- **chocolate** = **Color( 0.82, 0.41, 0.12, 1 )** --- Chocolate color. +.. rst-class:: classref-constructor -- **coral** = **Color( 1, 0.5, 0.31, 1 )** --- Coral color. +:ref:`Color` **Color**\ (\ code\: :ref:`String`\ ) -- **cornflower** = **Color( 0.39, 0.58, 0.93, 1 )** --- Cornflower color. +Constructs a **Color** either from an HTML color code or from a standardized color name. The supported color names are the same as the constants. -- **cornsilk** = **Color( 1, 0.97, 0.86, 1 )** --- Corn silk color. +.. rst-class:: classref-item-separator -- **crimson** = **Color( 0.86, 0.08, 0.24, 1 )** --- Crimson color. +---- -- **cyan** = **Color( 0, 1, 1, 1 )** --- Cyan color. +.. rst-class:: classref-constructor -- **darkblue** = **Color( 0, 0, 0.55, 1 )** --- Dark blue color. +:ref:`Color` **Color**\ (\ code\: :ref:`String`, alpha\: :ref:`float`\ ) -- **darkcyan** = **Color( 0, 0.55, 0.55, 1 )** --- Dark cyan color. +Constructs a **Color** either from an HTML color code or from a standardized color name, with ``alpha`` on the range of 0.0 to 1.0. The supported color names are the same as the constants. -- **darkgoldenrod** = **Color( 0.72, 0.53, 0.04, 1 )** --- Dark goldenrod color. +.. rst-class:: classref-item-separator -- **darkgray** = **Color( 0.66, 0.66, 0.66, 1 )** --- Dark gray color. +---- -- **darkgreen** = **Color( 0, 0.39, 0, 1 )** --- Dark green color. +.. rst-class:: classref-constructor -- **darkkhaki** = **Color( 0.74, 0.72, 0.42, 1 )** --- Dark khaki color. +:ref:`Color` **Color**\ (\ r\: :ref:`float`, g\: :ref:`float`, b\: :ref:`float`\ ) -- **darkmagenta** = **Color( 0.55, 0, 0.55, 1 )** --- Dark magenta color. +Constructs a **Color** from RGB values, typically between 0.0 and 1.0. :ref:`a` is set to 1.0. -- **darkolivegreen** = **Color( 0.33, 0.42, 0.18, 1 )** --- Dark olive green color. -- **darkorange** = **Color( 1, 0.55, 0, 1 )** --- Dark orange color. +.. tabs:: -- **darkorchid** = **Color( 0.6, 0.2, 0.8, 1 )** --- Dark orchid color. + .. code-tab:: gdscript -- **darkred** = **Color( 0.55, 0, 0, 1 )** --- Dark red color. + var color = Color(0.2, 1.0, 0.7) # Similar to `Color8(51, 255, 178, 255)` -- **darksalmon** = **Color( 0.91, 0.59, 0.48, 1 )** --- Dark salmon color. + .. code-tab:: csharp -- **darkseagreen** = **Color( 0.56, 0.74, 0.56, 1 )** --- Dark sea green color. + var color = new Color(0.2f, 1.0f, 0.7f); // Similar to `Color.Color8(51, 255, 178, 255)` -- **darkslateblue** = **Color( 0.28, 0.24, 0.55, 1 )** --- Dark slate blue color. -- **darkslategray** = **Color( 0.18, 0.31, 0.31, 1 )** --- Dark slate gray color. -- **darkturquoise** = **Color( 0, 0.81, 0.82, 1 )** --- Dark turquoise color. +.. rst-class:: classref-item-separator -- **darkviolet** = **Color( 0.58, 0, 0.83, 1 )** --- Dark violet color. +---- -- **deeppink** = **Color( 1, 0.08, 0.58, 1 )** --- Deep pink color. +.. rst-class:: classref-constructor -- **deepskyblue** = **Color( 0, 0.75, 1, 1 )** --- Deep sky blue color. +:ref:`Color` **Color**\ (\ r\: :ref:`float`, g\: :ref:`float`, b\: :ref:`float`, a\: :ref:`float`\ ) -- **dimgray** = **Color( 0.41, 0.41, 0.41, 1 )** --- Dim gray color. +Constructs a **Color** from RGBA values, typically between 0.0 and 1.0. -- **dodgerblue** = **Color( 0.12, 0.56, 1, 1 )** --- Dodger blue color. -- **firebrick** = **Color( 0.7, 0.13, 0.13, 1 )** --- Firebrick color. +.. tabs:: -- **floralwhite** = **Color( 1, 0.98, 0.94, 1 )** --- Floral white color. + .. code-tab:: gdscript -- **forestgreen** = **Color( 0.13, 0.55, 0.13, 1 )** --- Forest green color. + var color = Color(0.2, 1.0, 0.7, 0.8) # Similar to `Color8(51, 255, 178, 204)` -- **fuchsia** = **Color( 1, 0, 1, 1 )** --- Fuchsia color. + .. code-tab:: csharp -- **gainsboro** = **Color( 0.86, 0.86, 0.86, 1 )** --- Gainsboro color. + var color = new Color(0.2f, 1.0f, 0.7f, 0.8f); // Similar to `Color.Color8(51, 255, 178, 255, 204)` -- **ghostwhite** = **Color( 0.97, 0.97, 1, 1 )** --- Ghost white color. -- **gold** = **Color( 1, 0.84, 0, 1 )** --- Gold color. -- **goldenrod** = **Color( 0.85, 0.65, 0.13, 1 )** --- Goldenrod color. +.. rst-class:: classref-section-separator -- **gray** = **Color( 0.75, 0.75, 0.75, 1 )** --- Gray color. +---- -- **green** = **Color( 0, 1, 0, 1 )** --- Green color. +.. rst-class:: classref-descriptions-group -- **greenyellow** = **Color( 0.68, 1, 0.18, 1 )** --- Green yellow color. +Method Descriptions +------------------- -- **honeydew** = **Color( 0.94, 1, 0.94, 1 )** --- Honeydew color. +.. _class_Color_method_blend: -- **hotpink** = **Color( 1, 0.41, 0.71, 1 )** --- Hot pink color. +.. rst-class:: classref-method -- **indianred** = **Color( 0.8, 0.36, 0.36, 1 )** --- Indian red color. +:ref:`Color` **blend**\ (\ over\: :ref:`Color`\ ) |const| :ref:`🔗` -- **indigo** = **Color( 0.29, 0, 0.51, 1 )** --- Indigo color. +Returns a new color resulting from overlaying this color over the given color. In a painting program, you can imagine it as the ``over`` color painted over this color (including alpha). -- **ivory** = **Color( 1, 1, 0.94, 1 )** --- Ivory color. -- **khaki** = **Color( 0.94, 0.9, 0.55, 1 )** --- Khaki color. +.. tabs:: -- **lavender** = **Color( 0.9, 0.9, 0.98, 1 )** --- Lavender color. + .. code-tab:: gdscript -- **lavenderblush** = **Color( 1, 0.94, 0.96, 1 )** --- Lavender blush color. + var bg = Color(0.0, 1.0, 0.0, 0.5) # Green with alpha of 50% + var fg = Color(1.0, 0.0, 0.0, 0.5) # Red with alpha of 50% + var blended_color = bg.blend(fg) # Brown with alpha of 75% -- **lawngreen** = **Color( 0.49, 0.99, 0, 1 )** --- Lawn green color. + .. code-tab:: csharp -- **lemonchiffon** = **Color( 1, 0.98, 0.8, 1 )** --- Lemon chiffon color. + var bg = new Color(0.0f, 1.0f, 0.0f, 0.5f); // Green with alpha of 50% + var fg = new Color(1.0f, 0.0f, 0.0f, 0.5f); // Red with alpha of 50% + Color blendedColor = bg.Blend(fg); // Brown with alpha of 75% -- **lightblue** = **Color( 0.68, 0.85, 0.9, 1 )** --- Light blue color. -- **lightcoral** = **Color( 0.94, 0.5, 0.5, 1 )** --- Light coral color. -- **lightcyan** = **Color( 0.88, 1, 1, 1 )** --- Light cyan color. +.. rst-class:: classref-item-separator -- **lightgoldenrod** = **Color( 0.98, 0.98, 0.82, 1 )** --- Light goldenrod color. +---- -- **lightgray** = **Color( 0.83, 0.83, 0.83, 1 )** --- Light gray color. +.. _class_Color_method_clamp: -- **lightgreen** = **Color( 0.56, 0.93, 0.56, 1 )** --- Light green color. +.. rst-class:: classref-method -- **lightpink** = **Color( 1, 0.71, 0.76, 1 )** --- Light pink color. +:ref:`Color` **clamp**\ (\ min\: :ref:`Color` = Color(0, 0, 0, 0), max\: :ref:`Color` = Color(1, 1, 1, 1)\ ) |const| :ref:`🔗` -- **lightsalmon** = **Color( 1, 0.63, 0.48, 1 )** --- Light salmon color. +Returns a new color with all components clamped between the components of ``min`` and ``max``, by running :ref:`@GlobalScope.clamp()` on each component. -- **lightseagreen** = **Color( 0.13, 0.7, 0.67, 1 )** --- Light sea green color. +.. rst-class:: classref-item-separator -- **lightskyblue** = **Color( 0.53, 0.81, 0.98, 1 )** --- Light sky blue color. +---- -- **lightslategray** = **Color( 0.47, 0.53, 0.6, 1 )** --- Light slate gray color. +.. _class_Color_method_darkened: -- **lightsteelblue** = **Color( 0.69, 0.77, 0.87, 1 )** --- Light steel blue color. +.. rst-class:: classref-method -- **lightyellow** = **Color( 1, 1, 0.88, 1 )** --- Light yellow color. +:ref:`Color` **darkened**\ (\ amount\: :ref:`float`\ ) |const| :ref:`🔗` -- **lime** = **Color( 0, 1, 0, 1 )** --- Lime color. +Returns a new color resulting from making this color darker by the specified ``amount`` (ratio from 0.0 to 1.0). See also :ref:`lightened()`. -- **limegreen** = **Color( 0.2, 0.8, 0.2, 1 )** --- Lime green color. -- **linen** = **Color( 0.98, 0.94, 0.9, 1 )** --- Linen color. +.. tabs:: -- **magenta** = **Color( 1, 0, 1, 1 )** --- Magenta color. + .. code-tab:: gdscript -- **maroon** = **Color( 0.69, 0.19, 0.38, 1 )** --- Maroon color. + var green = Color(0.0, 1.0, 0.0) + var darkgreen = green.darkened(0.2) # 20% darker than regular green -- **mediumaquamarine** = **Color( 0.4, 0.8, 0.67, 1 )** --- Medium aquamarine color. + .. code-tab:: csharp -- **mediumblue** = **Color( 0, 0, 0.8, 1 )** --- Medium blue color. + var green = new Color(0.0f, 1.0f, 0.0f); + Color darkgreen = green.Darkened(0.2f); // 20% darker than regular green -- **mediumorchid** = **Color( 0.73, 0.33, 0.83, 1 )** --- Medium orchid color. -- **mediumpurple** = **Color( 0.58, 0.44, 0.86, 1 )** --- Medium purple color. -- **mediumseagreen** = **Color( 0.24, 0.7, 0.44, 1 )** --- Medium sea green color. +.. rst-class:: classref-item-separator -- **mediumslateblue** = **Color( 0.48, 0.41, 0.93, 1 )** --- Medium slate blue color. +---- -- **mediumspringgreen** = **Color( 0, 0.98, 0.6, 1 )** --- Medium spring green color. +.. _class_Color_method_from_hsv: -- **mediumturquoise** = **Color( 0.28, 0.82, 0.8, 1 )** --- Medium turquoise color. +.. rst-class:: classref-method -- **mediumvioletred** = **Color( 0.78, 0.08, 0.52, 1 )** --- Medium violet red color. +:ref:`Color` **from_hsv**\ (\ h\: :ref:`float`, s\: :ref:`float`, v\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| :ref:`🔗` -- **midnightblue** = **Color( 0.1, 0.1, 0.44, 1 )** --- Midnight blue color. +Constructs a color from an `HSV profile `__. The hue (``h``), saturation (``s``), and value (``v``) are typically between 0.0 and 1.0. -- **mintcream** = **Color( 0.96, 1, 0.98, 1 )** --- Mint cream color. -- **mistyrose** = **Color( 1, 0.89, 0.88, 1 )** --- Misty rose color. +.. tabs:: -- **moccasin** = **Color( 1, 0.89, 0.71, 1 )** --- Moccasin color. + .. code-tab:: gdscript -- **navajowhite** = **Color( 1, 0.87, 0.68, 1 )** --- Navajo white color. + var color = Color.from_hsv(0.58, 0.5, 0.79, 0.8) -- **navyblue** = **Color( 0, 0, 0.5, 1 )** --- Navy blue color. + .. code-tab:: csharp -- **oldlace** = **Color( 0.99, 0.96, 0.9, 1 )** --- Old lace color. + var color = Color.FromHsv(0.58f, 0.5f, 0.79f, 0.8f); -- **olive** = **Color( 0.5, 0.5, 0, 1 )** --- Olive color. -- **olivedrab** = **Color( 0.42, 0.56, 0.14, 1 )** --- Olive drab color. -- **orange** = **Color( 1, 0.65, 0, 1 )** --- Orange color. +.. rst-class:: classref-item-separator -- **orangered** = **Color( 1, 0.27, 0, 1 )** --- Orange red color. +---- -- **orchid** = **Color( 0.85, 0.44, 0.84, 1 )** --- Orchid color. +.. _class_Color_method_from_ok_hsl: -- **palegoldenrod** = **Color( 0.93, 0.91, 0.67, 1 )** --- Pale goldenrod color. +.. rst-class:: classref-method -- **palegreen** = **Color( 0.6, 0.98, 0.6, 1 )** --- Pale green color. +:ref:`Color` **from_ok_hsl**\ (\ h\: :ref:`float`, s\: :ref:`float`, l\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| :ref:`🔗` -- **paleturquoise** = **Color( 0.69, 0.93, 0.93, 1 )** --- Pale turquoise color. +Constructs a color from an `OK HSL profile `__. The hue (``h``), saturation (``s``), and lightness (``l``) are typically between 0.0 and 1.0. -- **palevioletred** = **Color( 0.86, 0.44, 0.58, 1 )** --- Pale violet red color. -- **papayawhip** = **Color( 1, 0.94, 0.84, 1 )** --- Papaya whip color. +.. tabs:: -- **peachpuff** = **Color( 1, 0.85, 0.73, 1 )** --- Peach puff color. + .. code-tab:: gdscript -- **peru** = **Color( 0.8, 0.52, 0.25, 1 )** --- Peru color. + var color = Color.from_ok_hsl(0.58, 0.5, 0.79, 0.8) -- **pink** = **Color( 1, 0.75, 0.8, 1 )** --- Pink color. + .. code-tab:: csharp -- **plum** = **Color( 0.87, 0.63, 0.87, 1 )** --- Plum color. + var color = Color.FromOkHsl(0.58f, 0.5f, 0.79f, 0.8f); -- **powderblue** = **Color( 0.69, 0.88, 0.9, 1 )** --- Powder blue color. -- **purple** = **Color( 0.63, 0.13, 0.94, 1 )** --- Purple color. -- **rebeccapurple** = **Color( 0.4, 0.2, 0.6, 1 )** --- Rebecca purple color. +.. rst-class:: classref-item-separator -- **red** = **Color( 1, 0, 0, 1 )** --- Red color. +---- -- **rosybrown** = **Color( 0.74, 0.56, 0.56, 1 )** --- Rosy brown color. +.. _class_Color_method_from_rgba8: -- **royalblue** = **Color( 0.25, 0.41, 0.88, 1 )** --- Royal blue color. +.. rst-class:: classref-method -- **saddlebrown** = **Color( 0.55, 0.27, 0.07, 1 )** --- Saddle brown color. +:ref:`Color` **from_rgba8**\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) |static| :ref:`🔗` -- **salmon** = **Color( 0.98, 0.5, 0.45, 1 )** --- Salmon color. +Returns a **Color** constructed from red (``r8``), green (``g8``), blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by ``255.0`` for their final value. -- **sandybrown** = **Color( 0.96, 0.64, 0.38, 1 )** --- Sandy brown color. +:: -- **seagreen** = **Color( 0.18, 0.55, 0.34, 1 )** --- Sea green color. + var red = Color.from_rgba8(255, 0, 0) # Same as Color(1, 0, 0). + var dark_blue = Color.from_rgba8(0, 0, 51) # Same as Color(0, 0, 0.2). + var my_color = Color.from_rgba8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4). -- **seashell** = **Color( 1, 0.96, 0.93, 1 )** --- Seashell color. +\ **Note:** Due to the lower precision of :ref:`from_rgba8()` compared to the standard **Color** constructor, a color created with :ref:`from_rgba8()` will generally not be equal to the same color created with the standard **Color** constructor. Use :ref:`is_equal_approx()` for comparisons to avoid issues with floating-point precision error. -- **sienna** = **Color( 0.63, 0.32, 0.18, 1 )** --- Sienna color. +.. rst-class:: classref-item-separator -- **silver** = **Color( 0.75, 0.75, 0.75, 1 )** --- Silver color. +---- -- **skyblue** = **Color( 0.53, 0.81, 0.92, 1 )** --- Sky blue color. +.. _class_Color_method_from_rgbe9995: -- **slateblue** = **Color( 0.42, 0.35, 0.8, 1 )** --- Slate blue color. +.. rst-class:: classref-method -- **slategray** = **Color( 0.44, 0.5, 0.56, 1 )** --- Slate gray color. +:ref:`Color` **from_rgbe9995**\ (\ rgbe\: :ref:`int`\ ) |static| :ref:`🔗` -- **snow** = **Color( 1, 0.98, 0.98, 1 )** --- Snow color. +Decodes a **Color** from an RGBE9995 format integer. See :ref:`Image.FORMAT_RGBE9995`. -- **springgreen** = **Color( 0, 1, 0.5, 1 )** --- Spring green color. +.. rst-class:: classref-item-separator -- **steelblue** = **Color( 0.27, 0.51, 0.71, 1 )** --- Steel blue color. +---- -- **tan** = **Color( 0.82, 0.71, 0.55, 1 )** --- Tan color. +.. _class_Color_method_from_string: -- **teal** = **Color( 0, 0.5, 0.5, 1 )** --- Teal color. +.. rst-class:: classref-method -- **thistle** = **Color( 0.85, 0.75, 0.85, 1 )** --- Thistle color. +:ref:`Color` **from_string**\ (\ str\: :ref:`String`, default\: :ref:`Color`\ ) |static| :ref:`🔗` -- **tomato** = **Color( 1, 0.39, 0.28, 1 )** --- Tomato color. +Creates a **Color** from the given string, which can be either an HTML color code or a named color (case-insensitive). Returns ``default`` if the color cannot be inferred from the string. -- **transparent** = **Color( 1, 1, 1, 0 )** --- Transparent color (white with no alpha). +If you want to create a color from String in a constant expression, use the equivalent constructor instead (i.e. ``Color("color string")``). -- **turquoise** = **Color( 0.25, 0.88, 0.82, 1 )** --- Turquoise color. +.. rst-class:: classref-item-separator -- **violet** = **Color( 0.93, 0.51, 0.93, 1 )** --- Violet color. +---- -- **webgray** = **Color( 0.5, 0.5, 0.5, 1 )** --- Web gray color. +.. _class_Color_method_get_luminance: -- **webgreen** = **Color( 0, 0.5, 0, 1 )** --- Web green color. +.. rst-class:: classref-method -- **webmaroon** = **Color( 0.5, 0, 0, 1 )** --- Web maroon color. +:ref:`float` **get_luminance**\ (\ ) |const| :ref:`🔗` -- **webpurple** = **Color( 0.5, 0, 0.5, 1 )** --- Web purple color. +Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclusive). This is useful when determining light or dark color. Colors with a luminance smaller than 0.5 can be generally considered dark. -- **wheat** = **Color( 0.96, 0.87, 0.7, 1 )** --- Wheat color. +\ **Note:** :ref:`get_luminance()` relies on the color using linear encoding to return an accurate relative luminance value. If the color uses the default nonlinear sRGB encoding, use :ref:`srgb_to_linear()` to convert it to linear encoding first. -- **white** = **Color( 1, 1, 1, 1 )** --- White color. +.. rst-class:: classref-item-separator -- **whitesmoke** = **Color( 0.96, 0.96, 0.96, 1 )** --- White smoke color. +---- -- **yellow** = **Color( 1, 1, 0, 1 )** --- Yellow color. +.. _class_Color_method_hex: -- **yellowgreen** = **Color( 0.6, 0.8, 0.2, 1 )** --- Yellow green color. +.. rst-class:: classref-method -Property Descriptions ---------------------- +:ref:`Color` **hex**\ (\ hex\: :ref:`int`\ ) |static| :ref:`🔗` -.. _class_Color_property_a: +Returns the **Color** associated with the provided ``hex`` integer in 32-bit RGBA format (8 bits per channel). This method is the inverse of :ref:`to_rgba32()`. -- :ref:`float` **a** +In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRGGBBAA"``). -+-----------+---------+ -| *Default* | ``1.0`` | -+-----------+---------+ -Alpha value (range 0 to 1). +.. tabs:: + + .. code-tab:: gdscript + + var red = Color.hex(0xff0000ff) + var dark_cyan = Color.hex(0x008b8bff) + var my_color = Color.hex(0xbbefd2a4) + + .. code-tab:: csharp + + var red = new Color(0xff0000ff); + var dark_cyan = new Color(0x008b8bff); + var my_color = new Color(0xbbefd2a4); + + + +If you want to use hex notation in a constant expression, use the equivalent constructor instead (i.e. ``Color(0xRRGGBBAA)``). + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_a8: +.. _class_Color_method_hex64: + +.. rst-class:: classref-method -- :ref:`int` **a8** +:ref:`Color` **hex64**\ (\ hex\: :ref:`int`\ ) |static| :ref:`🔗` -+-----------+---------+ -| *Default* | ``255`` | -+-----------+---------+ +Returns the **Color** associated with the provided ``hex`` integer in 64-bit RGBA format (16 bits per channel). This method is the inverse of :ref:`to_rgba64()`. -Alpha value (range 0 to 255). +In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRRRGGGGBBBBAAAA"``). + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_b: +.. _class_Color_method_html: + +.. rst-class:: classref-method + +:ref:`Color` **html**\ (\ rgba\: :ref:`String`\ ) |static| :ref:`🔗` + +Returns a new color from ``rgba``, an HTML hexadecimal color string. ``rgba`` is not case-sensitive, and may be prefixed by a hash sign (``#``). + +\ ``rgba`` must be a valid three-digit or six-digit hexadecimal color string, and may contain an alpha channel value. If ``rgba`` does not contain an alpha channel value, an alpha channel value of 1.0 is applied. If ``rgba`` is invalid, returns an empty color. -- :ref:`float` **b** -+-----------+---------+ -| *Default* | ``0.0`` | -+-----------+---------+ +.. tabs:: -Blue value (range 0 to 1). + .. code-tab:: gdscript + + var blue = Color.html("#0000ff") # blue is Color(0.0, 0.0, 1.0, 1.0) + var green = Color.html("#0F0") # green is Color(0.0, 1.0, 0.0, 1.0) + var col = Color.html("663399cc") # col is Color(0.4, 0.2, 0.6, 0.8) + + .. code-tab:: csharp + + var blue = Color.FromHtml("#0000ff"); // blue is Color(0.0, 0.0, 1.0, 1.0) + var green = Color.FromHtml("#0F0"); // green is Color(0.0, 1.0, 0.0, 1.0) + var col = Color.FromHtml("663399cc"); // col is Color(0.4, 0.2, 0.6, 0.8) + + + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_b8: +.. _class_Color_method_html_is_valid: + +.. rst-class:: classref-method + +:ref:`bool` **html_is_valid**\ (\ color\: :ref:`String`\ ) |static| :ref:`🔗` + +Returns ``true`` if ``color`` is a valid HTML hexadecimal color string. The string must be a hexadecimal value (case-insensitive) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign (``#``). This method is identical to :ref:`String.is_valid_html_color()`. + + +.. tabs:: + + .. code-tab:: gdscript + + Color.html_is_valid("#55aaFF") # Returns true + Color.html_is_valid("#55AAFF20") # Returns true + Color.html_is_valid("55AAFF") # Returns true + Color.html_is_valid("#F2C") # Returns true + + Color.html_is_valid("#AABBC") # Returns false + Color.html_is_valid("#55aaFF5") # Returns false + + .. code-tab:: csharp -- :ref:`int` **b8** + Color.HtmlIsValid("#55AAFF"); // Returns true + Color.HtmlIsValid("#55AAFF20"); // Returns true + Color.HtmlIsValid("55AAFF"); // Returns true + Color.HtmlIsValid("#F2C"); // Returns true -+-----------+-------+ -| *Default* | ``0`` | -+-----------+-------+ + Color.HtmlIsValid("#AABBC"); // Returns false + Color.HtmlIsValid("#55aaFF5"); // Returns false -Blue value (range 0 to 255). + + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_g: +.. _class_Color_method_inverted: + +.. rst-class:: classref-method + +:ref:`Color` **inverted**\ (\ ) |const| :ref:`🔗` + +Returns the color with its :ref:`r`, :ref:`g`, and :ref:`b` components inverted (``(1 - r, 1 - g, 1 - b, a)``). + -- :ref:`float` **g** +.. tabs:: -+-----------+---------+ -| *Default* | ``0.0`` | -+-----------+---------+ + .. code-tab:: gdscript -Green value (range 0 to 1). + var black = Color.WHITE.inverted() + var color = Color(0.3, 0.4, 0.9) + var inverted_color = color.inverted() # Equivalent to `Color(0.7, 0.6, 0.1)` + + .. code-tab:: csharp + + var black = Colors.White.Inverted(); + var color = new Color(0.3f, 0.4f, 0.9f); + Color invertedColor = color.Inverted(); // Equivalent to `new Color(0.7f, 0.6f, 0.1f)` + + + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_g8: +.. _class_Color_method_is_equal_approx: + +.. rst-class:: classref-method -- :ref:`int` **g8** +:ref:`bool` **is_equal_approx**\ (\ to\: :ref:`Color`\ ) |const| :ref:`🔗` -+-----------+-------+ -| *Default* | ``0`` | -+-----------+-------+ +Returns ``true`` if this color and ``to`` are approximately equal, by running :ref:`@GlobalScope.is_equal_approx()` on each component. -Green value (range 0 to 255). +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_h: +.. _class_Color_method_lerp: + +.. rst-class:: classref-method + +:ref:`Color` **lerp**\ (\ to\: :ref:`Color`, weight\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns the linear interpolation between this color's components and ``to``'s components. The interpolation factor ``weight`` should be between 0.0 and 1.0 (inclusive). See also :ref:`@GlobalScope.lerp()`. + + +.. tabs:: + + .. code-tab:: gdscript + + var red = Color(1.0, 0.0, 0.0) + var aqua = Color(0.0, 1.0, 0.8) -- :ref:`float` **h** + red.lerp(aqua, 0.2) # Returns Color(0.8, 0.2, 0.16) + red.lerp(aqua, 0.5) # Returns Color(0.5, 0.5, 0.4) + red.lerp(aqua, 1.0) # Returns Color(0.0, 1.0, 0.8) -+-----------+---------+ -| *Default* | ``0.0`` | -+-----------+---------+ + .. code-tab:: csharp -HSV hue value (range 0 to 1). + var red = new Color(1.0f, 0.0f, 0.0f); + var aqua = new Color(0.0f, 1.0f, 0.8f); + + red.Lerp(aqua, 0.2f); // Returns Color(0.8f, 0.2f, 0.16f) + red.Lerp(aqua, 0.5f); // Returns Color(0.5f, 0.5f, 0.4f) + red.Lerp(aqua, 1.0f); // Returns Color(0.0f, 1.0f, 0.8f) + + + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_r: +.. _class_Color_method_lightened: + +.. rst-class:: classref-method + +:ref:`Color` **lightened**\ (\ amount\: :ref:`float`\ ) |const| :ref:`🔗` -- :ref:`float` **r** +Returns a new color resulting from making this color lighter by the specified ``amount``, which should be a ratio from 0.0 to 1.0. See also :ref:`darkened()`. -+-----------+---------+ -| *Default* | ``0.0`` | -+-----------+---------+ -Red value (range 0 to 1). +.. tabs:: + + .. code-tab:: gdscript + + var green = Color(0.0, 1.0, 0.0) + var light_green = green.lightened(0.2) # 20% lighter than regular green + + .. code-tab:: csharp + + var green = new Color(0.0f, 1.0f, 0.0f); + Color lightGreen = green.Lightened(0.2f); // 20% lighter than regular green + + + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_r8: +.. _class_Color_method_linear_to_srgb: + +.. rst-class:: classref-method -- :ref:`int` **r8** +:ref:`Color` **linear_to_srgb**\ (\ ) |const| :ref:`🔗` -+-----------+-------+ -| *Default* | ``0`` | -+-----------+-------+ +Returns a copy of the color that is encoded using the `nonlinear sRGB transfer function `__. This method requires the original color to use linear encoding. See also :ref:`srgb_to_linear()` which performs the opposite operation. -Red value (range 0 to 255). +\ **Note:** The color's :ref:`a`\ lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the encoding of the other color channels. + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_s: +.. _class_Color_method_srgb_to_linear: -- :ref:`float` **s** +.. rst-class:: classref-method -+-----------+---------+ -| *Default* | ``0.0`` | -+-----------+---------+ +:ref:`Color` **srgb_to_linear**\ (\ ) |const| :ref:`🔗` -HSV saturation value (range 0 to 1). +Returns a copy of the color that uses linear encoding. This method requires the original color to be encoded using the `nonlinear sRGB transfer function `__. See also :ref:`linear_to_srgb()` which performs the opposite operation. + +\ **Note:** The color's :ref:`a`\ lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the encoding of the other color channels. + +.. rst-class:: classref-item-separator ---- -.. _class_Color_property_v: +.. _class_Color_method_to_abgr32: -- :ref:`float` **v** +.. rst-class:: classref-method -+-----------+---------+ -| *Default* | ``0.0`` | -+-----------+---------+ +:ref:`int` **to_abgr32**\ (\ ) |const| :ref:`🔗` -HSV value (range 0 to 1). +Returns the color converted to a 32-bit integer in ABGR format (each component is 8 bits). ABGR is the reversed version of the default RGBA format. -Method Descriptions -------------------- -.. _class_Color_method_Color: +.. tabs:: -- :ref:`Color` **Color** **(** :ref:`String` from **)** + .. code-tab:: gdscript -Constructs a color from an HTML hexadecimal color string in ARGB or RGB format. See also :ref:`@GDScript.ColorN`. + var color = Color(1, 0.5, 0.2) + print(color.to_abgr32()) # Prints 4281565439 -:: + .. code-tab:: csharp + + var color = new Color(1.0f, 0.5f, 0.2f); + GD.Print(color.ToAbgr32()); // Prints 4281565439 - # Each of the following creates the same color RGBA(178, 217, 10, 255). - var c1 = Color("#ffb2d90a") # ARGB format with "#". - var c2 = Color("ffb2d90a") # ARGB format. - var c3 = Color("#b2d90a") # RGB format with "#". - var c4 = Color("b2d90a") # RGB format. + + +.. rst-class:: classref-item-separator ---- -- :ref:`Color` **Color** **(** :ref:`int` from **)** +.. _class_Color_method_to_abgr64: -Constructs a color from a 32-bit integer (each byte represents a component of the RGBA profile). +.. rst-class:: classref-method + +:ref:`int` **to_abgr64**\ (\ ) |const| :ref:`🔗` + +Returns the color converted to a 64-bit integer in ABGR format (each component is 16 bits). ABGR is the reversed version of the default RGBA format. + + +.. tabs:: + + .. code-tab:: gdscript + + var color = Color(1, 0.5, 0.2) + print(color.to_abgr64()) # Prints -225178692812801 + + .. code-tab:: csharp + + var color = new Color(1.0f, 0.5f, 0.2f); + GD.Print(color.ToAbgr64()); // Prints -225178692812801 -:: - var c = Color(274) # Equivalent to RGBA(0, 0, 1, 18) + +.. rst-class:: classref-item-separator ---- -- :ref:`Color` **Color** **(** :ref:`float` r, :ref:`float` g, :ref:`float` b **)** +.. _class_Color_method_to_argb32: + +.. rst-class:: classref-method -Constructs a color from an RGB profile using values between 0 and 1. Alpha will always be 1. +:ref:`int` **to_argb32**\ (\ ) |const| :ref:`🔗` -:: +Returns the color converted to a 32-bit integer in ARGB format (each component is 8 bits). ARGB is more compatible with DirectX. + + +.. tabs:: + + .. code-tab:: gdscript + + var color = Color(1, 0.5, 0.2) + print(color.to_argb32()) # Prints 4294934323 - var c = Color(0.2, 1.0, 0.7) # Equivalent to RGBA(51, 255, 178, 255) + .. code-tab:: csharp + + var color = new Color(1.0f, 0.5f, 0.2f); + GD.Print(color.ToArgb32()); // Prints 4294934323 + + + +.. rst-class:: classref-item-separator ---- -- :ref:`Color` **Color** **(** :ref:`float` r, :ref:`float` g, :ref:`float` b, :ref:`float` a **)** +.. _class_Color_method_to_argb64: -Constructs a color from an RGBA profile using values between 0 and 1. +.. rst-class:: classref-method + +:ref:`int` **to_argb64**\ (\ ) |const| :ref:`🔗` + +Returns the color converted to a 64-bit integer in ARGB format (each component is 16 bits). ARGB is more compatible with DirectX. -:: - var c = Color(0.2, 1.0, 0.7, 0.8) # Equivalent to RGBA(51, 255, 178, 204) +.. tabs:: + + .. code-tab:: gdscript + + var color = Color(1, 0.5, 0.2) + print(color.to_argb64()) # Prints -2147470541 + + .. code-tab:: csharp + + var color = new Color(1.0f, 0.5f, 0.2f); + GD.Print(color.ToArgb64()); // Prints -2147470541 + + + +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_blend: +.. _class_Color_method_to_html: -- :ref:`Color` **blend** **(** :ref:`Color` over **)** +.. rst-class:: classref-method -Returns a new color resulting from blending this color over another. If the color is opaque, the result is also opaque. The second color may have a range of alpha values. +:ref:`String` **to_html**\ (\ with_alpha\: :ref:`bool` = true\ ) |const| :ref:`🔗` -:: +Returns the color converted to an HTML hexadecimal color :ref:`String` in RGBA format, without the hash (``#``) prefix. - var bg = Color(0.0, 1.0, 0.0, 0.5) # Green with alpha of 50% - var fg = Color(1.0, 0.0, 0.0, 0.5) # Red with alpha of 50% - var blended_color = bg.blend(fg) # Brown with alpha of 75% +Setting ``with_alpha`` to ``false``, excludes alpha from the hexadecimal string, using RGB format instead of RGBA format. + + +.. tabs:: + + .. code-tab:: gdscript + + var white = Color(1, 1, 1, 0.5) + var with_alpha = white.to_html() # Returns "ffffff7f" + var without_alpha = white.to_html(false) # Returns "ffffff" + + .. code-tab:: csharp + + var white = new Color(1, 1, 1, 0.5f); + string withAlpha = white.ToHtml(); // Returns "ffffff7f" + string withoutAlpha = white.ToHtml(false); // Returns "ffffff" + + + +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_contrasted: +.. _class_Color_method_to_rgba32: -- :ref:`Color` **contrasted** **(** **)** +.. rst-class:: classref-method + +:ref:`int` **to_rgba32**\ (\ ) |const| :ref:`🔗` + +Returns the color converted to a 32-bit integer in RGBA format (each component is 8 bits). RGBA is Godot's default format. This method is the inverse of :ref:`hex()`. + + +.. tabs:: + + .. code-tab:: gdscript + + var color = Color(1, 0.5, 0.2) + print(color.to_rgba32()) # Prints 4286526463 + + .. code-tab:: csharp + + var color = new Color(1, 0.5f, 0.2f); + GD.Print(color.ToRgba32()); // Prints 4286526463 -Returns the most contrasting color. -:: - var c = Color(0.3, 0.4, 0.9) - var contrasted_color = c.contrasted() # Equivalent to RGBA(204, 229, 102, 255) +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_darkened: +.. _class_Color_method_to_rgba64: -- :ref:`Color` **darkened** **(** :ref:`float` amount **)** +.. rst-class:: classref-method -Returns a new color resulting from making this color darker by the specified percentage (ratio from 0 to 1). +:ref:`int` **to_rgba64**\ (\ ) |const| :ref:`🔗` -:: +Returns the color converted to a 64-bit integer in RGBA format (each component is 16 bits). RGBA is Godot's default format. This method is the inverse of :ref:`hex64()`. - var green = Color(0.0, 1.0, 0.0) - var darkgreen = green.darkened(0.2) # 20% darker than regular green + +.. tabs:: + + .. code-tab:: gdscript + + var color = Color(1, 0.5, 0.2) + print(color.to_rgba64()) # Prints -140736629309441 + + .. code-tab:: csharp + + var color = new Color(1, 0.5f, 0.2f); + GD.Print(color.ToRgba64()); // Prints -140736629309441 + + + +.. rst-class:: classref-section-separator ---- -.. _class_Color_method_from_hsv: +.. rst-class:: classref-descriptions-group -- :ref:`Color` **from_hsv** **(** :ref:`float` h, :ref:`float` s, :ref:`float` v, :ref:`float` a=1.0 **)** +Operator Descriptions +--------------------- -Constructs a color from an HSV profile. ``h``, ``s``, and ``v`` are values between 0 and 1. +.. _class_Color_operator_neq_Color: -:: +.. rst-class:: classref-operator - var c = Color.from_hsv(0.58, 0.5, 0.79, 0.8) # Equivalent to HSV(210, 50, 79, 0.8) or Color8(100, 151, 201, 0.8) +:ref:`bool` **operator !=**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` + +Returns ``true`` if the colors are not exactly equal. + +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. + +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_inverted: +.. _class_Color_operator_mul_Color: -- :ref:`Color` **inverted** **(** **)** +.. rst-class:: classref-operator -Returns the inverted color ``(1 - r, 1 - g, 1 - b, a)``. +:ref:`Color` **operator ***\ (\ right\: :ref:`Color`\ ) :ref:`🔗` -:: +Multiplies each component of the **Color** by the components of the given **Color**. - var c = Color(0.3, 0.4, 0.9) - var inverted_color = c.inverted() # A color of an RGBA(178, 153, 26, 255) +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_is_equal_approx: +.. _class_Color_operator_mul_float: + +.. rst-class:: classref-operator + +:ref:`Color` **operator ***\ (\ right\: :ref:`float`\ ) :ref:`🔗` -- :ref:`bool` **is_equal_approx** **(** :ref:`Color` color **)** +Multiplies each component of the **Color** by the given :ref:`float`. -Returns ``true`` if this color and ``color`` are approximately equal, by running :ref:`@GDScript.is_equal_approx` on each component. +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_lightened: +.. _class_Color_operator_mul_int: -- :ref:`Color` **lightened** **(** :ref:`float` amount **)** +.. rst-class:: classref-operator -Returns a new color resulting from making this color lighter by the specified percentage (ratio from 0 to 1). +:ref:`Color` **operator ***\ (\ right\: :ref:`int`\ ) :ref:`🔗` -:: +Multiplies each component of the **Color** by the given :ref:`int`. - var green = Color(0.0, 1.0, 0.0) - var lightgreen = green.lightened(0.2) # 20% lighter than regular green +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_linear_interpolate: +.. _class_Color_operator_sum_Color: -- :ref:`Color` **linear_interpolate** **(** :ref:`Color` b, :ref:`float` t **)** +.. rst-class:: classref-operator -Returns the linear interpolation with another color. The interpolation factor ``t`` is between 0 and 1. +:ref:`Color` **operator +**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` -:: +Adds each component of the **Color** with the components of the given **Color**. - var c1 = Color(1.0, 0.0, 0.0) - var c2 = Color(0.0, 1.0, 0.0) - var li_c = c1.linear_interpolate(c2, 0.5) # A color of an RGBA(128, 128, 0, 255) +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_to_abgr32: +.. _class_Color_operator_dif_Color: -- :ref:`int` **to_abgr32** **(** **)** +.. rst-class:: classref-operator -Returns the color's 32-bit integer in ABGR format (each byte represents a component of the ABGR profile). ABGR is the reversed version of the default format. +:ref:`Color` **operator -**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` -:: +Subtracts each component of the **Color** by the components of the given **Color**. - var c = Color(1, 0.5, 0.2) - print(c.to_abgr32()) # Prints 4281565439 +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_to_abgr64: +.. _class_Color_operator_div_Color: -- :ref:`int` **to_abgr64** **(** **)** +.. rst-class:: classref-operator -Returns the color's 64-bit integer in ABGR format (each word represents a component of the ABGR profile). ABGR is the reversed version of the default format. +:ref:`Color` **operator /**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` -:: +Divides each component of the **Color** by the components of the given **Color**. - var c = Color(1, 0.5, 0.2) - print(c.to_abgr64()) # Prints -225178692812801 +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_to_argb32: +.. _class_Color_operator_div_float: -- :ref:`int` **to_argb32** **(** **)** +.. rst-class:: classref-operator -Returns the color's 32-bit integer in ARGB format (each byte represents a component of the ARGB profile). ARGB is more compatible with DirectX. +:ref:`Color` **operator /**\ (\ right\: :ref:`float`\ ) :ref:`🔗` -:: +Divides each component of the **Color** by the given :ref:`float`. - var c = Color(1, 0.5, 0.2) - print(c.to_argb32()) # Prints 4294934323 +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_to_argb64: +.. _class_Color_operator_div_int: -- :ref:`int` **to_argb64** **(** **)** +.. rst-class:: classref-operator -Returns the color's 64-bit integer in ARGB format (each word represents a component of the ARGB profile). ARGB is more compatible with DirectX. +:ref:`Color` **operator /**\ (\ right\: :ref:`int`\ ) :ref:`🔗` -:: +Divides each component of the **Color** by the given :ref:`int`. - var c = Color(1, 0.5, 0.2) - print(c.to_argb64()) # Prints -2147470541 +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_to_html: +.. _class_Color_operator_eq_Color: -- :ref:`String` **to_html** **(** :ref:`bool` with_alpha=true **)** +.. rst-class:: classref-operator -Returns the color's HTML hexadecimal color string in ARGB format (ex: ``ff34f822``). +:ref:`bool` **operator ==**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` -Setting ``with_alpha`` to ``false`` excludes alpha from the hexadecimal string. +Returns ``true`` if the colors are exactly equal. -:: +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. - var c = Color(1, 1, 1, 0.5) - var s1 = c.to_html() # Returns "7fffffff" - var s2 = c.to_html(false) # Returns "ffffff" +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_to_rgba32: +.. _class_Color_operator_idx_int: -- :ref:`int` **to_rgba32** **(** **)** +.. rst-class:: classref-operator -Returns the color's 32-bit integer in RGBA format (each byte represents a component of the RGBA profile). RGBA is Godot's default format. +:ref:`float` **operator []**\ (\ index\: :ref:`int`\ ) :ref:`🔗` -:: +Access color components using their index. ``[0]`` is equivalent to :ref:`r`, ``[1]`` is equivalent to :ref:`g`, ``[2]`` is equivalent to :ref:`b`, and ``[3]`` is equivalent to :ref:`a`. - var c = Color(1, 0.5, 0.2) - print(c.to_rgba32()) # Prints 4286526463 +.. rst-class:: classref-item-separator ---- -.. _class_Color_method_to_rgba64: +.. _class_Color_operator_unplus: -- :ref:`int` **to_rgba64** **(** **)** +.. rst-class:: classref-operator -Returns the color's 64-bit integer in RGBA format (each word represents a component of the RGBA profile). RGBA is Godot's default format. +:ref:`Color` **operator unary+**\ (\ ) :ref:`🔗` -:: +Returns the same value as if the ``+`` was not there. Unary ``+`` does nothing, but sometimes it can make your code more readable. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Color_operator_unminus: + +.. rst-class:: classref-operator + +:ref:`Color` **operator unary-**\ (\ ) :ref:`🔗` - var c = Color(1, 0.5, 0.2) - print(c.to_rgba64()) # Prints -140736629309441 +Inverts the given color. This is equivalent to ``Color.WHITE - c`` or ``Color(1 - c.r, 1 - c.g, 1 - c.b, 1 - c.a)``. Unlike with :ref:`inverted()`, the :ref:`a` component is inverted, too. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_colorpalette.rst b/classes/class_colorpalette.rst new file mode 100644 index 00000000000..fcffacd9bc5 --- /dev/null +++ b/classes/class_colorpalette.rst @@ -0,0 +1,68 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ColorPalette.xml. + +.. _class_ColorPalette: + +ColorPalette +============ + +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +A resource class for managing a palette of colors, which can be loaded and saved using :ref:`ColorPicker`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +The **ColorPalette** resource is designed to store and manage a collection of colors. This resource is useful in scenarios where a predefined set of colors is required, such as for creating themes, designing user interfaces, or managing game assets. The built-in :ref:`ColorPicker` control can also make use of **ColorPalette** without additional code. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------------------------+---------------------------------------------------+------------------------+ + | :ref:`PackedColorArray` | :ref:`colors` | ``PackedColorArray()`` | + +-------------------------------------------------+---------------------------------------------------+------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_ColorPalette_property_colors: + +.. rst-class:: classref-property + +:ref:`PackedColorArray` **colors** = ``PackedColorArray()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_colors**\ (\ value\: :ref:`PackedColorArray`\ ) +- :ref:`PackedColorArray` **get_colors**\ (\ ) + +A :ref:`PackedColorArray` containing the colors in the palette. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedColorArray` for more details. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_colorpicker.rst b/classes/class_colorpicker.rst index 1bb92c6b961..b2289e4dd90 100644 --- a/classes/class_colorpicker.rst +++ b/classes/class_colorpicker.rst @@ -1,246 +1,934 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ColorPicker.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ColorPicker.xml. .. _class_ColorPicker: ColorPicker =========== -**Inherits:** :ref:`BoxContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` +**Inherits:** :ref:`VBoxContainer` **<** :ref:`BoxContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Color picker control. +A widget that provides an interface for selecting or modifying a color. + +.. rst-class:: classref-introduction-group Description ----------- -Displays a color picker widget. Useful for selecting a color from an RGB/RGBA colorspace. +A widget that provides an interface for selecting or modifying a color. It can optionally provide functionalities like a color sampler (eyedropper), color modes, and presets. + +\ **Note:** This control is the color picker widget itself. You can use a :ref:`ColorPickerButton` instead if you need a button that brings up a **ColorPicker** in a popup. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Tween Interpolation Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+--------------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`color` | ``Color( 1, 1, 1, 1 )`` | -+---------------------------+--------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`deferred_mode` | ``false`` | -+---------------------------+--------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`edit_alpha` | ``true`` | -+---------------------------+--------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`hsv_mode` | ``false`` | -+---------------------------+--------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`presets_enabled` | ``true`` | -+---------------------------+--------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`presets_visible` | ``true`` | -+---------------------------+--------------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`raw_mode` | ``false`` | -+---------------------------+--------------------------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`can_add_swatches` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`color` | ``Color(1, 1, 1, 1)`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`ColorModeType` | :ref:`color_mode` | ``0`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`color_modes_visible` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`deferred_mode` | ``false`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`edit_alpha` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`edit_intensity` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`hex_visible` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`PickerShapeType` | :ref:`picker_shape` | ``0`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`presets_visible` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`sampler_visible` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`sliders_visible` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_preset` **(** :ref:`Color` color **)** | -+-------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| void | :ref:`erase_preset` **(** :ref:`Color` color **)** | -+-------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| :ref:`PackedColorArray` | :ref:`get_presets` **(** **)** const | -+-------------------------------------------------+--------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_preset`\ (\ color\: :ref:`Color`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_recent_preset`\ (\ color\: :ref:`Color`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`erase_preset`\ (\ color\: :ref:`Color`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`erase_recent_preset`\ (\ color\: :ref:`Color`\ ) | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedColorArray` | :ref:`get_presets`\ (\ ) |const| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedColorArray` | :ref:`get_recent_presets`\ (\ ) |const| | + +-------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Theme Properties ---------------- -+-----------------------------------+----------------------+-----+ -| :ref:`Texture2D` | add_preset | | -+-----------------------------------+----------------------+-----+ -| :ref:`Texture2D` | color_hue | | -+-----------------------------------+----------------------+-----+ -| :ref:`Texture2D` | color_sample | | -+-----------------------------------+----------------------+-----+ -| :ref:`int` | h_width | 30 | -+-----------------------------------+----------------------+-----+ -| :ref:`int` | label_width | 10 | -+-----------------------------------+----------------------+-----+ -| :ref:`int` | margin | 4 | -+-----------------------------------+----------------------+-----+ -| :ref:`Texture2D` | overbright_indicator | | -+-----------------------------------+----------------------+-----+ -| :ref:`Texture2D` | preset_bg | | -+-----------------------------------+----------------------+-----+ -| :ref:`Texture2D` | screen_picker | | -+-----------------------------------+----------------------+-----+ -| :ref:`int` | sv_height | 256 | -+-----------------------------------+----------------------+-----+ -| :ref:`int` | sv_width | 256 | -+-----------------------------------+----------------------+-----+ +.. table:: + :widths: auto + + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Color` | :ref:`focused_not_editing_cursor_color` | ``Color(1, 1, 1, 0.275)`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`center_slider_grabbers` | ``1`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`h_width` | ``30`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`label_width` | ``10`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`margin` | ``4`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`sv_height` | ``256`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`sv_width` | ``256`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`add_preset` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`bar_arrow` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`color_hue` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`color_script` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`expanded_arrow` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`folded_arrow` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`menu_option` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`overbright_indicator` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`picker_cursor` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`picker_cursor_bg` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`sample_bg` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`sample_revert` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`screen_picker` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`shape_circle` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`shape_rect` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`shape_rect_wheel` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`StyleBox` | :ref:`picker_focus_circle` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`StyleBox` | :ref:`picker_focus_rectangle` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`StyleBox` | :ref:`sample_focus` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_ColorPicker_signal_color_changed: -- **color_changed** **(** :ref:`Color` color **)** +.. rst-class:: classref-signal + +**color_changed**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Emitted when the color is changed. +.. rst-class:: classref-item-separator + ---- .. _class_ColorPicker_signal_preset_added: -- **preset_added** **(** :ref:`Color` color **)** +.. rst-class:: classref-signal + +**preset_added**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Emitted when a preset is added. +.. rst-class:: classref-item-separator + ---- .. _class_ColorPicker_signal_preset_removed: -- **preset_removed** **(** :ref:`Color` color **)** +.. rst-class:: classref-signal + +**preset_removed**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Emitted when a preset is removed. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_ColorPicker_ColorModeType: + +.. rst-class:: classref-enumeration + +enum **ColorModeType**: :ref:`🔗` + +.. _class_ColorPicker_constant_MODE_RGB: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorModeType` **MODE_RGB** = ``0`` + +Allows editing the color with Red/Green/Blue sliders in sRGB color space. + +.. _class_ColorPicker_constant_MODE_HSV: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorModeType` **MODE_HSV** = ``1`` + +Allows editing the color with Hue/Saturation/Value sliders. + +.. _class_ColorPicker_constant_MODE_RAW: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorModeType` **MODE_RAW** = ``2`` + +**Deprecated:** This is replaced by :ref:`MODE_LINEAR`. + + + +.. _class_ColorPicker_constant_MODE_LINEAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorModeType` **MODE_LINEAR** = ``2`` + +Allows editing the color with Red/Green/Blue sliders in linear color space. + +.. _class_ColorPicker_constant_MODE_OKHSL: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorModeType` **MODE_OKHSL** = ``3`` + +Allows editing the color with Hue/Saturation/Lightness sliders. + +OKHSL is a new color space similar to HSL but that better match perception by leveraging the Oklab color space which is designed to be simple to use, while doing a good job at predicting perceived lightness, chroma and hue. + +\ `Okhsv and Okhsl color spaces `__ + +.. rst-class:: classref-item-separator + +---- + +.. _enum_ColorPicker_PickerShapeType: + +.. rst-class:: classref-enumeration + +enum **PickerShapeType**: :ref:`🔗` + +.. _class_ColorPicker_constant_SHAPE_HSV_RECTANGLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_HSV_RECTANGLE** = ``0`` + +HSV Color Model rectangle color space. + +.. _class_ColorPicker_constant_SHAPE_HSV_WHEEL: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_HSV_WHEEL** = ``1`` + +HSV Color Model rectangle color space with a wheel. + +.. _class_ColorPicker_constant_SHAPE_VHS_CIRCLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_VHS_CIRCLE** = ``2`` + +HSV Color Model circle color space. Use Saturation as a radius. + +.. _class_ColorPicker_constant_SHAPE_OKHSL_CIRCLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_OKHSL_CIRCLE** = ``3`` + +HSL OK Color Model circle color space. + +.. _class_ColorPicker_constant_SHAPE_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_NONE** = ``4`` + +The color space shape and the shape select button are hidden. Can't be selected from the shapes popup. + +.. _class_ColorPicker_constant_SHAPE_OK_HS_RECTANGLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_OK_HS_RECTANGLE** = ``5`` + +OKHSL Color Model rectangle with constant lightness. + +.. _class_ColorPicker_constant_SHAPE_OK_HL_RECTANGLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_OK_HL_RECTANGLE** = ``6`` + +OKHSL Color Model rectangle with constant saturation. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Property Descriptions --------------------- +.. _class_ColorPicker_property_can_add_swatches: + +.. rst-class:: classref-property + +:ref:`bool` **can_add_swatches** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_can_add_swatches**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **are_swatches_enabled**\ (\ ) + +If ``true``, it's possible to add presets under Swatches. If ``false``, the button to add presets is disabled. + +.. rst-class:: classref-item-separator + +---- + .. _class_ColorPicker_property_color: -- :ref:`Color` **color** +.. rst-class:: classref-property + +:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` -+-----------+-------------------------+ -| *Default* | ``Color( 1, 1, 1, 1 )`` | -+-----------+-------------------------+ -| *Setter* | set_pick_color(value) | -+-----------+-------------------------+ -| *Getter* | get_pick_color() | -+-----------+-------------------------+ +.. rst-class:: classref-property-setget + +- |void| **set_pick_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_pick_color**\ (\ ) The currently selected color. +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_property_color_mode: + +.. rst-class:: classref-property + +:ref:`ColorModeType` **color_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_color_mode**\ (\ value\: :ref:`ColorModeType`\ ) +- :ref:`ColorModeType` **get_color_mode**\ (\ ) + +The currently selected color mode. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_property_color_modes_visible: + +.. rst-class:: classref-property + +:ref:`bool` **color_modes_visible** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_modes_visible**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **are_modes_visible**\ (\ ) + +If ``true``, the color mode buttons are visible. + +.. rst-class:: classref-item-separator + ---- .. _class_ColorPicker_property_deferred_mode: -- :ref:`bool` **deferred_mode** +.. rst-class:: classref-property -+-----------+--------------------------+ -| *Default* | ``false`` | -+-----------+--------------------------+ -| *Setter* | set_deferred_mode(value) | -+-----------+--------------------------+ -| *Getter* | is_deferred_mode() | -+-----------+--------------------------+ +:ref:`bool` **deferred_mode** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_deferred_mode**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_deferred_mode**\ (\ ) If ``true``, the color will apply only after the user releases the mouse button, otherwise it will apply immediately even in mouse motion event (which can cause performance issues). +.. rst-class:: classref-item-separator + ---- .. _class_ColorPicker_property_edit_alpha: -- :ref:`bool` **edit_alpha** +.. rst-class:: classref-property + +:ref:`bool` **edit_alpha** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_edit_alpha**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_editing_alpha**\ (\ ) + +If ``true``, shows an alpha channel slider (opacity). + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_property_edit_intensity: -+-----------+-----------------------+ -| *Default* | ``true`` | -+-----------+-----------------------+ -| *Setter* | set_edit_alpha(value) | -+-----------+-----------------------+ -| *Getter* | is_editing_alpha() | -+-----------+-----------------------+ +.. rst-class:: classref-property -If ``true``, shows an alpha channel slider (transparency). +:ref:`bool` **edit_intensity** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_edit_intensity**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_editing_intensity**\ (\ ) + +If ``true``, shows an intensity slider. The intensity is applied as follows: convert the color to linear encoding, multiply it by ``2 ** intensity``, and then convert it back to nonlinear sRGB encoding. + +.. rst-class:: classref-item-separator ---- -.. _class_ColorPicker_property_hsv_mode: +.. _class_ColorPicker_property_hex_visible: + +.. rst-class:: classref-property + +:ref:`bool` **hex_visible** = ``true`` :ref:`🔗` -- :ref:`bool` **hsv_mode** +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_hsv_mode(value) | -+-----------+---------------------+ -| *Getter* | is_hsv_mode() | -+-----------+---------------------+ +- |void| **set_hex_visible**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_hex_visible**\ (\ ) -If ``true``, allows editing the color with Hue/Saturation/Value sliders. +If ``true``, the hex color code input field is visible. -**Note:** Cannot be enabled if raw mode is on. +.. rst-class:: classref-item-separator ---- -.. _class_ColorPicker_property_presets_enabled: +.. _class_ColorPicker_property_picker_shape: -- :ref:`bool` **presets_enabled** +.. rst-class:: classref-property -+-----------+----------------------------+ -| *Default* | ``true`` | -+-----------+----------------------------+ -| *Setter* | set_presets_enabled(value) | -+-----------+----------------------------+ -| *Getter* | are_presets_enabled() | -+-----------+----------------------------+ +:ref:`PickerShapeType` **picker_shape** = ``0`` :ref:`🔗` -If ``true``, the "add preset" button is enabled. +.. rst-class:: classref-property-setget + +- |void| **set_picker_shape**\ (\ value\: :ref:`PickerShapeType`\ ) +- :ref:`PickerShapeType` **get_picker_shape**\ (\ ) + +The shape of the color space view. + +.. rst-class:: classref-item-separator ---- .. _class_ColorPicker_property_presets_visible: -- :ref:`bool` **presets_visible** +.. rst-class:: classref-property + +:ref:`bool` **presets_visible** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget -+-----------+----------------------------+ -| *Default* | ``true`` | -+-----------+----------------------------+ -| *Setter* | set_presets_visible(value) | -+-----------+----------------------------+ -| *Getter* | are_presets_visible() | -+-----------+----------------------------+ +- |void| **set_presets_visible**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **are_presets_visible**\ (\ ) -If ``true``, saved color presets are visible. +If ``true``, the Swatches and Recent Colors presets are visible. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_property_sampler_visible: + +.. rst-class:: classref-property + +:ref:`bool` **sampler_visible** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_sampler_visible**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_sampler_visible**\ (\ ) + +If ``true``, the color sampler and color preview are visible. + +.. rst-class:: classref-item-separator ---- -.. _class_ColorPicker_property_raw_mode: +.. _class_ColorPicker_property_sliders_visible: + +.. rst-class:: classref-property + +:ref:`bool` **sliders_visible** = ``true`` :ref:`🔗` -- :ref:`bool` **raw_mode** +.. rst-class:: classref-property-setget -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_raw_mode(value) | -+-----------+---------------------+ -| *Getter* | is_raw_mode() | -+-----------+---------------------+ +- |void| **set_sliders_visible**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **are_sliders_visible**\ (\ ) -If ``true``, allows the color R, G, B component values to go beyond 1.0, which can be used for certain special operations that require it (like tinting without darkening or rendering sprites in HDR). +If ``true``, the color sliders are visible. -**Note:** Cannot be enabled if HSV mode is on. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_ColorPicker_method_add_preset: -- void **add_preset** **(** :ref:`Color` color **)** +.. rst-class:: classref-method + +|void| **add_preset**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Adds the given color to a list of color presets. The presets are displayed in the color picker and the user will be able to select them. -**Note:** the presets list is only for *this* color picker. +\ **Note:** The presets list is only for *this* color picker. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_method_add_recent_preset: + +.. rst-class:: classref-method + +|void| **add_recent_preset**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` + +Adds the given color to a list of color recent presets so that it can be picked later. Recent presets are the colors that were picked recently, a new preset is automatically created and added to recent presets when you pick a new color. + +\ **Note:** The recent presets list is only for *this* color picker. + +.. rst-class:: classref-item-separator ---- .. _class_ColorPicker_method_erase_preset: -- void **erase_preset** **(** :ref:`Color` color **)** +.. rst-class:: classref-method + +|void| **erase_preset**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Removes the given color from the list of color presets of this color picker. +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_method_erase_recent_preset: + +.. rst-class:: classref-method + +|void| **erase_recent_preset**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` + +Removes the given color from the list of color recent presets of this color picker. + +.. rst-class:: classref-item-separator + ---- .. _class_ColorPicker_method_get_presets: -- :ref:`PackedColorArray` **get_presets** **(** **)** const +.. rst-class:: classref-method + +:ref:`PackedColorArray` **get_presets**\ (\ ) |const| :ref:`🔗` Returns the list of colors in the presets of the color picker. +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_method_get_recent_presets: + +.. rst-class:: classref-method + +:ref:`PackedColorArray` **get_recent_presets**\ (\ ) |const| :ref:`🔗` + +Returns the list of colors in the recent presets of the color picker. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Theme Property Descriptions +--------------------------- + +.. _class_ColorPicker_theme_color_focused_not_editing_cursor_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **focused_not_editing_cursor_color** = ``Color(1, 1, 1, 0.275)`` :ref:`🔗` + +Color of rectangle or circle drawn when a picker shape part is focused but not editable via keyboard or joypad. Displayed *over* the picker shape, so a partially transparent color should be used to ensure the picker shape remains visible. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_constant_center_slider_grabbers: + +.. rst-class:: classref-themeproperty + +:ref:`int` **center_slider_grabbers** = ``1`` :ref:`🔗` + +Overrides the :ref:`Slider.center_grabber` theme property of the sliders. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_constant_h_width: + +.. rst-class:: classref-themeproperty + +:ref:`int` **h_width** = ``30`` :ref:`🔗` + +The width of the hue selection slider. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_constant_label_width: + +.. rst-class:: classref-themeproperty + +:ref:`int` **label_width** = ``10`` :ref:`🔗` + +The minimum width of the color labels next to sliders. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_constant_margin: + +.. rst-class:: classref-themeproperty + +:ref:`int` **margin** = ``4`` :ref:`🔗` + +The margin around the **ColorPicker**. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_constant_sv_height: + +.. rst-class:: classref-themeproperty + +:ref:`int` **sv_height** = ``256`` :ref:`🔗` + +The height of the saturation-value selection box. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_constant_sv_width: + +.. rst-class:: classref-themeproperty + +:ref:`int` **sv_width** = ``256`` :ref:`🔗` + +The width of the saturation-value selection box. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_add_preset: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **add_preset** :ref:`🔗` + +The icon for the "Add Preset" button. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_bar_arrow: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **bar_arrow** :ref:`🔗` + +The texture for the arrow grabber. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_color_hue: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **color_hue** :ref:`🔗` + +Custom texture for the hue selection slider on the right. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_color_script: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **color_script** :ref:`🔗` + +The icon for the button that switches color text to hexadecimal. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_expanded_arrow: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **expanded_arrow** :ref:`🔗` + +The icon for color preset drop down menu when expanded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_folded_arrow: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **folded_arrow** :ref:`🔗` + +The icon for color preset drop down menu when folded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_menu_option: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **menu_option** :ref:`🔗` + +The icon for color preset option menu. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_overbright_indicator: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **overbright_indicator** :ref:`🔗` + +The indicator used to signalize that the color value is outside the 0-1 range. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_picker_cursor: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **picker_cursor** :ref:`🔗` + +The image displayed over the color box/circle (depending on the :ref:`picker_shape`), marking the currently selected color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_picker_cursor_bg: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **picker_cursor_bg** :ref:`🔗` + +The fill image displayed behind the picker cursor. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_sample_bg: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **sample_bg** :ref:`🔗` + +Background panel for the color preview box (visible when the color is translucent). + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_sample_revert: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **sample_revert** :ref:`🔗` + +The icon for the revert button (visible on the middle of the "old" color when it differs from the currently selected color). This icon is modulated with a dark color if the "old" color is bright enough, so the icon should be bright to ensure visibility in both scenarios. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_screen_picker: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **screen_picker** :ref:`🔗` + +The icon for the screen color picker button. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_shape_circle: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **shape_circle** :ref:`🔗` + +The icon for circular picker shapes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_shape_rect: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **shape_rect** :ref:`🔗` + +The icon for rectangular picker shapes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_icon_shape_rect_wheel: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **shape_rect_wheel** :ref:`🔗` + +The icon for rectangular wheel picker shapes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_style_picker_focus_circle: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **picker_focus_circle** :ref:`🔗` + +The :ref:`StyleBox` used when the circle-shaped part of the picker is focused. Displayed *over* the picker shape, so a partially transparent :ref:`StyleBox` should be used to ensure the picker shape remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_style_picker_focus_rectangle: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **picker_focus_rectangle** :ref:`🔗` + +The :ref:`StyleBox` used when the rectangle-shaped part of the picker is focused. Displayed *over* the picker shape, so a partially transparent :ref:`StyleBox` should be used to ensure the picker shape remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_style_sample_focus: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **sample_focus** :ref:`🔗` + +The :ref:`StyleBox` used for the old color sample part when it is focused. Displayed *over* the sample, so a partially transparent :ref:`StyleBox` should be used to ensure the picker shape remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_colorpickerbutton.rst b/classes/class_colorpickerbutton.rst index 3422a300cbb..bc8f4e5326e 100644 --- a/classes/class_colorpickerbutton.rst +++ b/classes/class_colorpickerbutton.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ColorPickerButton.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ColorPickerButton.xml. .. _class_ColorPickerButton: @@ -11,134 +12,225 @@ ColorPickerButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Button that pops out a :ref:`ColorPicker`. +A button that brings up a :ref:`ColorPicker` when pressed. + +.. rst-class:: classref-introduction-group Description ----------- -Encapsulates a :ref:`ColorPicker` making it accessible by pressing a button. Pressing the button will toggle the :ref:`ColorPicker` visibility. +Encapsulates a :ref:`ColorPicker`, making it accessible by pressing a button. Pressing the button will toggle the :ref:`ColorPicker`'s visibility. + +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + +\ **Note:** By default, the button may not be wide enough for the color preview swatch to be visible. Make sure to set :ref:`Control.custom_minimum_size` to a big enough value to give the button enough space. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `2D GD Paint Demo `__ + +- `GUI Drag And Drop Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`color` | ``Color( 0, 0, 0, 1 )`` | -+---------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`bool` | :ref:`edit_alpha` | ``true`` | -+---------------------------+----------------------------------------------------------------+-------------------------+ -| :ref:`bool` | toggle_mode | **O:** ``true`` | -+---------------------------+----------------------------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`color` | ``Color(0, 0, 0, 1)`` | + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`edit_alpha` | ``true`` | + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`edit_intensity` | ``true`` | + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | toggle_mode | ``true`` (overrides :ref:`BaseButton`) | + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+---------------------------------------+--------------------------------------------------------------------------+ -| :ref:`ColorPicker` | :ref:`get_picker` **(** **)** | -+---------------------------------------+--------------------------------------------------------------------------+ -| :ref:`PopupPanel` | :ref:`get_popup` **(** **)** | -+---------------------------------------+--------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------+--------------------------------------------------------------------+ + | :ref:`ColorPicker` | :ref:`get_picker`\ (\ ) | + +---------------------------------------+--------------------------------------------------------------------+ + | :ref:`PopupPanel` | :ref:`get_popup`\ (\ ) | + +---------------------------------------+--------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Theme Properties ---------------- -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`Texture2D` | bg | | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`StyleBox` | disabled | | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`StyleBox` | focus | | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`Font` | font | | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`Color` | font_color | Color( 1, 1, 1, 1 ) | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`Color` | font_color_disabled | Color( 0.9, 0.9, 0.9, 0.3 ) | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`Color` | font_color_hover | Color( 1, 1, 1, 1 ) | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`Color` | font_color_pressed | Color( 0.8, 0.8, 0.8, 1 ) | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`StyleBox` | hover | | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`int` | hseparation | 2 | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`StyleBox` | normal | | -+-----------------------------------+---------------------+-----------------------------+ -| :ref:`StyleBox` | pressed | | -+-----------------------------------+---------------------+-----------------------------+ +.. table:: + :widths: auto + + +-----------------------------------+--------------------------------------------------+ + | :ref:`Texture2D` | :ref:`bg` | + +-----------------------------------+--------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_ColorPickerButton_signal_color_changed: -- **color_changed** **(** :ref:`Color` color **)** +.. rst-class:: classref-signal + +**color_changed**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Emitted when the color changes. +.. rst-class:: classref-item-separator + ---- .. _class_ColorPickerButton_signal_picker_created: -- **picker_created** **(** **)** +.. rst-class:: classref-signal + +**picker_created**\ (\ ) :ref:`🔗` Emitted when the :ref:`ColorPicker` is created (the button is pressed for the first time). +.. rst-class:: classref-item-separator + ---- .. _class_ColorPickerButton_signal_popup_closed: -- **popup_closed** **(** **)** +.. rst-class:: classref-signal + +**popup_closed**\ (\ ) :ref:`🔗` Emitted when the :ref:`ColorPicker` is closed. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Property Descriptions --------------------- .. _class_ColorPickerButton_property_color: -- :ref:`Color` **color** +.. rst-class:: classref-property -+-----------+-------------------------+ -| *Default* | ``Color( 0, 0, 0, 1 )`` | -+-----------+-------------------------+ -| *Setter* | set_pick_color(value) | -+-----------+-------------------------+ -| *Getter* | get_pick_color() | -+-----------+-------------------------+ +:ref:`Color` **color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pick_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_pick_color**\ (\ ) The currently selected color. +.. rst-class:: classref-item-separator + ---- .. _class_ColorPickerButton_property_edit_alpha: -- :ref:`bool` **edit_alpha** +.. rst-class:: classref-property -+-----------+-----------------------+ -| *Default* | ``true`` | -+-----------+-----------------------+ -| *Setter* | set_edit_alpha(value) | -+-----------+-----------------------+ -| *Getter* | is_editing_alpha() | -+-----------+-----------------------+ +:ref:`bool` **edit_alpha** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_edit_alpha**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_editing_alpha**\ (\ ) If ``true``, the alpha channel in the displayed :ref:`ColorPicker` will be visible. +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPickerButton_property_edit_intensity: + +.. rst-class:: classref-property + +:ref:`bool` **edit_intensity** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_edit_intensity**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_editing_intensity**\ (\ ) + +If ``true``, the intensity slider in the displayed :ref:`ColorPicker` will be visible. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- .. _class_ColorPickerButton_method_get_picker: -- :ref:`ColorPicker` **get_picker** **(** **)** +.. rst-class:: classref-method + +:ref:`ColorPicker` **get_picker**\ (\ ) :ref:`🔗` Returns the :ref:`ColorPicker` that this node toggles. +\ **Warning:** This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`CanvasItem.visible` property. + +.. rst-class:: classref-item-separator + ---- .. _class_ColorPickerButton_method_get_popup: -- :ref:`PopupPanel` **get_popup** **(** **)** +.. rst-class:: classref-method + +:ref:`PopupPanel` **get_popup**\ (\ ) :ref:`🔗` Returns the control's :ref:`PopupPanel` which allows you to connect to popup signals. This allows you to handle events when the ColorPicker is shown or hidden. +\ **Warning:** This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`Window.visible` property. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Theme Property Descriptions +--------------------------- + +.. _class_ColorPickerButton_theme_icon_bg: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **bg** :ref:`🔗` + +The background of the color preview rect on the button. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_colorrect.rst b/classes/class_colorrect.rst index 3f858016bc9..aa2994f9b89 100644 --- a/classes/class_colorrect.rst +++ b/classes/class_colorrect.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ColorRect.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ColorRect.xml. .. _class_ColorRect: @@ -11,38 +12,62 @@ ColorRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Colored rectangle. +A control that displays a solid color rectangle. + +.. rst-class:: classref-introduction-group Description ----------- -Displays a colored rectangle. +Displays a rectangle filled with a solid :ref:`color`. If you need to display the border alone, consider using a :ref:`Panel` instead. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `2D Dodge The Creeps Demo `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+---------------------------+----------------------------------------------+-------------------------+ -| :ref:`Color` | :ref:`color` | ``Color( 1, 1, 1, 1 )`` | -+---------------------------+----------------------------------------------+-------------------------+ +.. table:: + :widths: auto + + +---------------------------+----------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`color` | ``Color(1, 1, 1, 1)`` | + +---------------------------+----------------------------------------------+-----------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_ColorRect_property_color: -- :ref:`Color` **color** +.. rst-class:: classref-property -+-----------+-------------------------+ -| *Default* | ``Color( 1, 1, 1, 1 )`` | -+-----------+-------------------------+ -| *Setter* | set_frame_color(value) | -+-----------+-------------------------+ -| *Getter* | get_frame_color() | -+-----------+-------------------------+ +:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` -The fill color. +.. rst-class:: classref-property-setget -:: +- |void| **set_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_color**\ (\ ) - $ColorRect.color = Color(1, 0, 0, 1) # Set ColorRect's color to red. +The fill color of the rectangle. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_compositor.rst b/classes/class_compositor.rst new file mode 100644 index 00000000000..17c99c06e0b --- /dev/null +++ b/classes/class_compositor.rst @@ -0,0 +1,75 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Compositor.xml. + +.. _class_Compositor: + +Compositor +========== + +**Experimental:** More customization of the rendering pipeline will be added in the future. + +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Stores attributes used to customize how a Viewport is rendered. + +.. rst-class:: classref-introduction-group + +Description +----------- + +The compositor resource stores attributes used to customize how a :ref:`Viewport` is rendered. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`The Compositor <../tutorials/rendering/compositor>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +------------------------------------------------------------------------------+-------------------------------------------------------------------------+--------+ + | :ref:`Array`\[:ref:`CompositorEffect`\] | :ref:`compositor_effects` | ``[]`` | + +------------------------------------------------------------------------------+-------------------------------------------------------------------------+--------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_Compositor_property_compositor_effects: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`CompositorEffect`\] **compositor_effects** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_compositor_effects**\ (\ value\: :ref:`Array`\[:ref:`CompositorEffect`\]\ ) +- :ref:`Array`\[:ref:`CompositorEffect`\] **get_compositor_effects**\ (\ ) + +The custom :ref:`CompositorEffect`\ s that are applied during rendering of viewports using this compositor. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_compositoreffect.rst b/classes/class_compositoreffect.rst new file mode 100644 index 00000000000..8a28c052053 --- /dev/null +++ b/classes/class_compositoreffect.rst @@ -0,0 +1,322 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CompositorEffect.xml. + +.. _class_CompositorEffect: + +CompositorEffect +================ + +**Experimental:** The implementation may change as more of the rendering internals are exposed over time. + +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +This resource allows for creating a custom rendering effect. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This resource defines a custom rendering effect that can be applied to :ref:`Viewport`\ s through the viewports' :ref:`Environment`. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. CompositorEffect is an abstract base class and must be extended to implement specific rendering logic. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`The Compositor <../tutorials/rendering/compositor>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`access_resolved_color` | + +---------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`access_resolved_depth` | + +---------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`EffectCallbackType` | :ref:`effect_callback_type` | + +---------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`enabled` | + +---------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`needs_motion_vectors` | + +---------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`needs_normal_roughness` | + +---------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`needs_separate_specular` | + +---------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +--------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_render_callback`\ (\ effect_callback_type\: :ref:`int`, render_data\: :ref:`RenderData`\ ) |virtual| | + +--------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_CompositorEffect_EffectCallbackType: + +.. rst-class:: classref-enumeration + +enum **EffectCallbackType**: :ref:`🔗` + +.. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_PRE_OPAQUE: + +.. rst-class:: classref-enumeration-constant + +:ref:`EffectCallbackType` **EFFECT_CALLBACK_TYPE_PRE_OPAQUE** = ``0`` + +The callback is called before our opaque rendering pass, but after depth prepass (if applicable). + +.. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_POST_OPAQUE: + +.. rst-class:: classref-enumeration-constant + +:ref:`EffectCallbackType` **EFFECT_CALLBACK_TYPE_POST_OPAQUE** = ``1`` + +The callback is called after our opaque rendering pass, but before our sky is rendered. + +.. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_POST_SKY: + +.. rst-class:: classref-enumeration-constant + +:ref:`EffectCallbackType` **EFFECT_CALLBACK_TYPE_POST_SKY** = ``2`` + +The callback is called after our sky is rendered, but before our back buffers are created (and if enabled, before subsurface scattering and/or screen space reflections). + +.. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_PRE_TRANSPARENT: + +.. rst-class:: classref-enumeration-constant + +:ref:`EffectCallbackType` **EFFECT_CALLBACK_TYPE_PRE_TRANSPARENT** = ``3`` + +The callback is called before our transparent rendering pass, but after our sky is rendered and we've created our back buffers. + +.. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_POST_TRANSPARENT: + +.. rst-class:: classref-enumeration-constant + +:ref:`EffectCallbackType` **EFFECT_CALLBACK_TYPE_POST_TRANSPARENT** = ``4`` + +The callback is called after our transparent rendering pass, but before any built-in post-processing effects and output to our render target. + +.. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`EffectCallbackType` **EFFECT_CALLBACK_TYPE_MAX** = ``5`` + +Represents the size of the :ref:`EffectCallbackType` enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CompositorEffect_property_access_resolved_color: + +.. rst-class:: classref-property + +:ref:`bool` **access_resolved_color** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_access_resolved_color**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_access_resolved_color**\ (\ ) + +If ``true`` and MSAA is enabled, this will trigger a color buffer resolve before the effect is run. + +\ **Note:** In :ref:`_render_callback()`, to access the resolved buffer use: + +:: + + var render_scene_buffers = render_data.get_render_scene_buffers() + var color_buffer = render_scene_buffers.get_texture("render_buffers", "color") + +.. rst-class:: classref-item-separator + +---- + +.. _class_CompositorEffect_property_access_resolved_depth: + +.. rst-class:: classref-property + +:ref:`bool` **access_resolved_depth** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_access_resolved_depth**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_access_resolved_depth**\ (\ ) + +If ``true`` and MSAA is enabled, this will trigger a depth buffer resolve before the effect is run. + +\ **Note:** In :ref:`_render_callback()`, to access the resolved buffer use: + +:: + + var render_scene_buffers = render_data.get_render_scene_buffers() + var depth_buffer = render_scene_buffers.get_texture("render_buffers", "depth") + +.. rst-class:: classref-item-separator + +---- + +.. _class_CompositorEffect_property_effect_callback_type: + +.. rst-class:: classref-property + +:ref:`EffectCallbackType` **effect_callback_type** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_effect_callback_type**\ (\ value\: :ref:`EffectCallbackType`\ ) +- :ref:`EffectCallbackType` **get_effect_callback_type**\ (\ ) + +The type of effect that is implemented, determines at what stage of rendering the callback is called. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CompositorEffect_property_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **enabled** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_enabled**\ (\ ) + +If ``true`` this rendering effect is applied to any viewport it is added to. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CompositorEffect_property_needs_motion_vectors: + +.. rst-class:: classref-property + +:ref:`bool` **needs_motion_vectors** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_needs_motion_vectors**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_needs_motion_vectors**\ (\ ) + +If ``true`` this triggers motion vectors being calculated during the opaque render state. + +\ **Note:** In :ref:`_render_callback()`, to access the motion vector buffer use: + +:: + + var render_scene_buffers = render_data.get_render_scene_buffers() + var motion_buffer = render_scene_buffers.get_velocity_texture() + +.. rst-class:: classref-item-separator + +---- + +.. _class_CompositorEffect_property_needs_normal_roughness: + +.. rst-class:: classref-property + +:ref:`bool` **needs_normal_roughness** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_needs_normal_roughness**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_needs_normal_roughness**\ (\ ) + +If ``true`` this triggers normal and roughness data to be output during our depth pre-pass, only applicable for the Forward+ renderer. + +\ **Note:** In :ref:`_render_callback()`, to access the roughness buffer use: + +:: + + var render_scene_buffers = render_data.get_render_scene_buffers() + var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness") + +The raw normal and roughness buffer is stored in an optimized format, different than the one available in Spatial shaders. When sampling the buffer, a conversion function must be applied. Use this function, copied from `here `__: + +:: + + vec4 normal_roughness_compatibility(vec4 p_normal_roughness) { + float roughness = p_normal_roughness.w; + if (roughness > 0.5) { + roughness = 1.0 - roughness; + } + roughness /= (127.0 / 255.0); + return vec4(normalize(p_normal_roughness.xyz * 2.0 - 1.0) * 0.5 + 0.5, roughness); + } + +.. rst-class:: classref-item-separator + +---- + +.. _class_CompositorEffect_property_needs_separate_specular: + +.. rst-class:: classref-property + +:ref:`bool` **needs_separate_specular** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_needs_separate_specular**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_needs_separate_specular**\ (\ ) + +If ``true`` this triggers specular data being rendered to a separate buffer and combined after effects have been applied, only applicable for the Forward+ renderer. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CompositorEffect_private_method__render_callback: + +.. rst-class:: classref-method + +|void| **_render_callback**\ (\ effect_callback_type\: :ref:`int`, render_data\: :ref:`RenderData`\ ) |virtual| :ref:`🔗` + +Implement this function with your custom rendering code. ``effect_callback_type`` should always match the effect callback type you've specified in :ref:`effect_callback_type`. ``render_data`` provides access to the rendering state, it is only valid during rendering and should not be stored. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_compressedcubemap.rst b/classes/class_compressedcubemap.rst new file mode 100644 index 00000000000..499f85aa779 --- /dev/null +++ b/classes/class_compressedcubemap.rst @@ -0,0 +1,48 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CompressedCubemap.xml. + +.. _class_CompressedCubemap: + +CompressedCubemap +================= + +**Inherits:** :ref:`CompressedTextureLayered` **<** :ref:`TextureLayered` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +An optionally compressed :ref:`Cubemap`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A cubemap that is loaded from a ``.ccube`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedCubemap** can use one of 4 compression methods: + +- Lossless (WebP or PNG, uncompressed on the GPU) + +- Lossy (WebP, uncompressed on the GPU) + +- VRAM Compressed (compressed on the GPU) + +- VRAM Uncompressed (uncompressed on the GPU) + +- Basis Universal (compressed on the GPU. Lower file sizes than VRAM Compressed, but slower to compress and lower quality than VRAM Compressed) + +Only **VRAM Compressed** actually reduces the memory usage on the GPU. The **Lossless** and **Lossy** compression methods will reduce the required storage on disk, but they will not reduce memory usage on the GPU as the texture is sent to the GPU uncompressed. + +Using **VRAM Compressed** also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless or lossy compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +See :ref:`Cubemap` for a general description of cubemaps. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_compressedcubemaparray.rst b/classes/class_compressedcubemaparray.rst new file mode 100644 index 00000000000..59df932dc2f --- /dev/null +++ b/classes/class_compressedcubemaparray.rst @@ -0,0 +1,48 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CompressedCubemapArray.xml. + +.. _class_CompressedCubemapArray: + +CompressedCubemapArray +====================== + +**Inherits:** :ref:`CompressedTextureLayered` **<** :ref:`TextureLayered` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +An optionally compressed :ref:`CubemapArray`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A cubemap array that is loaded from a ``.ccubearray`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedCubemapArray** can use one of 4 compression methods: + +- Lossless (WebP or PNG, uncompressed on the GPU) + +- Lossy (WebP, uncompressed on the GPU) + +- VRAM Compressed (compressed on the GPU) + +- VRAM Uncompressed (uncompressed on the GPU) + +- Basis Universal (compressed on the GPU. Lower file sizes than VRAM Compressed, but slower to compress and lower quality than VRAM Compressed) + +Only **VRAM Compressed** actually reduces the memory usage on the GPU. The **Lossless** and **Lossy** compression methods will reduce the required storage on disk, but they will not reduce memory usage on the GPU as the texture is sent to the GPU uncompressed. + +Using **VRAM Compressed** also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless or lossy compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +See :ref:`CubemapArray` for a general description of cubemap arrays. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_compressedtexture2d.rst b/classes/class_compressedtexture2d.rst new file mode 100644 index 00000000000..7f8356fff89 --- /dev/null +++ b/classes/class_compressedtexture2d.rst @@ -0,0 +1,111 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CompressedTexture2D.xml. + +.. _class_CompressedTexture2D: + +CompressedTexture2D +=================== + +**Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Texture with 2 dimensions, optionally compressed. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A texture that is loaded from a ``.ctex`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedTexture2D** can use one of 4 compression methods (including a lack of any compression): + +- Lossless (WebP or PNG, uncompressed on the GPU) + +- Lossy (WebP, uncompressed on the GPU) + +- VRAM Compressed (compressed on the GPU) + +- VRAM Uncompressed (uncompressed on the GPU) + +- Basis Universal (compressed on the GPU. Lower file sizes than VRAM Compressed, but slower to compress and lower quality than VRAM Compressed) + +Only **VRAM Compressed** actually reduces the memory usage on the GPU. The **Lossless** and **Lossy** compression methods will reduce the required storage on disk, but they will not reduce memory usage on the GPU as the texture is sent to the GPU uncompressed. + +Using **VRAM Compressed** also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless or lossy compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------+----------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`load_path` | ``""`` | + +-----------------------------+----------------------------------------------------------------+----------------------------------------------------------------------------------------+ + | :ref:`bool` | resource_local_to_scene | ``false`` (overrides :ref:`Resource`) | + +-----------------------------+----------------------------------------------------------------+----------------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`load`\ (\ path\: :ref:`String`\ ) | + +---------------------------------------+----------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CompressedTexture2D_property_load_path: + +.. rst-class:: classref-property + +:ref:`String` **load_path** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`Error` **load**\ (\ path\: :ref:`String`\ ) +- :ref:`String` **get_load_path**\ (\ ) + +The **CompressedTexture2D**'s file path to a ``.ctex`` file. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CompressedTexture2D_method_load: + +.. rst-class:: classref-method + +:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` + +Loads the texture from the specified ``path``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_compressedtexture2darray.rst b/classes/class_compressedtexture2darray.rst new file mode 100644 index 00000000000..2142a4ded4a --- /dev/null +++ b/classes/class_compressedtexture2darray.rst @@ -0,0 +1,48 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CompressedTexture2DArray.xml. + +.. _class_CompressedTexture2DArray: + +CompressedTexture2DArray +======================== + +**Inherits:** :ref:`CompressedTextureLayered` **<** :ref:`TextureLayered` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Array of 2-dimensional textures, optionally compressed. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A texture array that is loaded from a ``.ctexarray`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedTexture2DArray** can use one of 4 compression methods: + +- Lossless (WebP or PNG, uncompressed on the GPU) + +- Lossy (WebP, uncompressed on the GPU) + +- VRAM Compressed (compressed on the GPU) + +- VRAM Uncompressed (uncompressed on the GPU) + +- Basis Universal (compressed on the GPU. Lower file sizes than VRAM Compressed, but slower to compress and lower quality than VRAM Compressed) + +Only **VRAM Compressed** actually reduces the memory usage on the GPU. The **Lossless** and **Lossy** compression methods will reduce the required storage on disk, but they will not reduce memory usage on the GPU as the texture is sent to the GPU uncompressed. + +Using **VRAM Compressed** also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless or lossy compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +See :ref:`Texture2DArray` for a general description of texture arrays. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_compressedtexture3d.rst b/classes/class_compressedtexture3d.rst new file mode 100644 index 00000000000..32c06648ed9 --- /dev/null +++ b/classes/class_compressedtexture3d.rst @@ -0,0 +1,99 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CompressedTexture3D.xml. + +.. _class_CompressedTexture3D: + +CompressedTexture3D +=================== + +**Inherits:** :ref:`Texture3D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Texture with 3 dimensions, optionally compressed. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**CompressedTexture3D** is the VRAM-compressed counterpart of :ref:`ImageTexture3D`. The file extension for **CompressedTexture3D** files is ``.ctex3d``. This file format is internal to Godot; it is created by importing other image formats with the import system. + +\ **CompressedTexture3D** uses VRAM compression, which allows to reduce memory usage on the GPU when rendering the texture. This also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +See :ref:`Texture3D` for a general description of 3D textures. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------+----------------------------------------------------------------+--------+ + | :ref:`String` | :ref:`load_path` | ``""`` | + +-----------------------------+----------------------------------------------------------------+--------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+----------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`load`\ (\ path\: :ref:`String`\ ) | + +---------------------------------------+----------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CompressedTexture3D_property_load_path: + +.. rst-class:: classref-property + +:ref:`String` **load_path** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`Error` **load**\ (\ path\: :ref:`String`\ ) +- :ref:`String` **get_load_path**\ (\ ) + +The **CompressedTexture3D**'s file path to a ``.ctex3d`` file. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CompressedTexture3D_method_load: + +.. rst-class:: classref-method + +:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` + +Loads the texture from the specified ``path``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_compressedtexturelayered.rst b/classes/class_compressedtexturelayered.rst new file mode 100644 index 00000000000..463666444de --- /dev/null +++ b/classes/class_compressedtexturelayered.rst @@ -0,0 +1,97 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/CompressedTextureLayered.xml. + +.. _class_CompressedTextureLayered: + +CompressedTextureLayered +======================== + +**Inherits:** :ref:`TextureLayered` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +**Inherited By:** :ref:`CompressedCubemap`, :ref:`CompressedCubemapArray`, :ref:`CompressedTexture2DArray` + +Base class for texture arrays that can optionally be compressed. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Base class for :ref:`CompressedTexture2DArray` and :ref:`CompressedTexture3D`. Cannot be used directly, but contains all the functions necessary for accessing the derived resource types. See also :ref:`TextureLayered`. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------------+---------------------------------------------------------------------+--------+ + | :ref:`String` | :ref:`load_path` | ``""`` | + +-----------------------------+---------------------------------------------------------------------+--------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+---------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`load`\ (\ path\: :ref:`String`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CompressedTextureLayered_property_load_path: + +.. rst-class:: classref-property + +:ref:`String` **load_path** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`Error` **load**\ (\ path\: :ref:`String`\ ) +- :ref:`String` **get_load_path**\ (\ ) + +The path the texture should be loaded from. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_CompressedTextureLayered_method_load: + +.. rst-class:: classref-method + +:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` + +Loads the texture at ``path``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_concavepolygonshape.rst b/classes/class_concavepolygonshape.rst deleted file mode 100644 index fd120921a46..00000000000 --- a/classes/class_concavepolygonshape.rst +++ /dev/null @@ -1,48 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ConcavePolygonShape.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ConcavePolygonShape: - -ConcavePolygonShape -=================== - -**Inherits:** :ref:`Shape` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` - -Concave polygon shape. - -Description ------------ - -Concave polygon shape resource, which can be set into a :ref:`PhysicsBody` or area. This shape is created by feeding a list of triangles. - -Note: when used for collision, ``ConcavePolygonShape`` is intended to work with static :ref:`PhysicsBody` nodes like :ref:`StaticBody` and will not work with :ref:`KinematicBody` or :ref:`RigidBody` with a mode other than Static. - -Methods -------- - -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedVector3Array` | :ref:`get_faces` **(** **)** const | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_faces` **(** :ref:`PackedVector3Array` faces **)** | -+-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ - -Method Descriptions -------------------- - -.. _class_ConcavePolygonShape_method_get_faces: - -- :ref:`PackedVector3Array` **get_faces** **(** **)** const - -Returns the faces (an array of triangles). - ----- - -.. _class_ConcavePolygonShape_method_set_faces: - -- void **set_faces** **(** :ref:`PackedVector3Array` faces **)** - -Sets the faces (an array of triangles). - diff --git a/classes/class_concavepolygonshape2d.rst b/classes/class_concavepolygonshape2d.rst index 77acd0863e2..354a22c88dc 100644 --- a/classes/class_concavepolygonshape2d.rst +++ b/classes/class_concavepolygonshape2d.rst @@ -1,46 +1,76 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ConcavePolygonShape2D.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ConcavePolygonShape2D.xml. .. _class_ConcavePolygonShape2D: ConcavePolygonShape2D ===================== -**Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Concave polygon 2D shape resource for physics. +A 2D polyline shape used for physics collision. + +.. rst-class:: classref-introduction-group Description ----------- -Concave polygon 2D shape resource for physics. It is made out of segments and is optimal for complex polygonal concave collisions. However, it is not advised to use for :ref:`RigidBody2D` nodes. A CollisionPolygon2D in convex decomposition mode (solids) or several convex objects are advised for that instead. Otherwise, a concave polygon 2D shape is better for static collisions. +A 2D polyline shape, intended for use in physics. Used internally in :ref:`CollisionPolygon2D` when it's in :ref:`CollisionPolygon2D.BUILD_SEGMENTS` mode. + +Being just a collection of interconnected line segments, **ConcavePolygonShape2D** is the most freely configurable single 2D shape. It can be used to form polygons of any nature, or even shapes that don't enclose an area. However, **ConcavePolygonShape2D** is *hollow* even if the interconnected line segments do enclose an area, which often makes it unsuitable for physics or detection. + +\ **Note:** When used for collision, **ConcavePolygonShape2D** is intended to work with static :ref:`CollisionShape2D` nodes like :ref:`StaticBody2D` and will likely not behave well for :ref:`CharacterBody2D`\ s or :ref:`RigidBody2D`\ s in a mode other than Static. -The main difference between a :ref:`ConvexPolygonShape2D` and a ``ConcavePolygonShape2D`` is that a concave polygon assumes it is concave and uses a more complex method of collision detection, and a convex one forces itself to be convex in order to speed up collision detection. +\ **Warning:** Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. **ConcavePolygonShape2D** is hollow, so it won't detect a collision. + +\ **Performance:** Due to its complexity, **ConcavePolygonShape2D** is the slowest 2D collision shape to check collisions against. Its use should generally be limited to level geometry. If the polyline is closed, :ref:`CollisionPolygon2D`'s :ref:`CollisionPolygon2D.BUILD_SOLIDS` mode can be used, which decomposes the polygon into convex ones; see :ref:`ConvexPolygonShape2D`'s documentation for instructions. + +.. rst-class:: classref-reftable-group Properties ---------- -+-----------------------------------------------------+----------------------------------------------------------------+----------------------------+ -| :ref:`PackedVector2Array` | :ref:`segments` | ``PackedVector2Array( )`` | -+-----------------------------------------------------+----------------------------------------------------------------+----------------------------+ +.. table:: + :widths: auto + + +-----------------------------------------------------+----------------------------------------------------------------+--------------------------+ + | :ref:`PackedVector2Array` | :ref:`segments` | ``PackedVector2Array()`` | + +-----------------------------------------------------+----------------------------------------------------------------+--------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_ConcavePolygonShape2D_property_segments: -- :ref:`PackedVector2Array` **segments** +.. rst-class:: classref-property + +:ref:`PackedVector2Array` **segments** = ``PackedVector2Array()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_segments**\ (\ value\: :ref:`PackedVector2Array`\ ) +- :ref:`PackedVector2Array` **get_segments**\ (\ ) -+-----------+----------------------------+ -| *Default* | ``PackedVector2Array( )`` | -+-----------+----------------------------+ -| *Setter* | set_segments(value) | -+-----------+----------------------------+ -| *Getter* | get_segments() | -+-----------+----------------------------+ +The array of points that make up the **ConcavePolygonShape2D**'s line segments. The array (of length divisible by two) is naturally divided into pairs (one pair for each segment); each pair consists of the starting point of a segment and the endpoint of a segment. -The array of points that make up the ``ConcavePolygonShape2D``'s line segments. +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedVector2Array` for more details. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_concavepolygonshape3d.rst b/classes/class_concavepolygonshape3d.rst new file mode 100644 index 00000000000..e4d8714396d --- /dev/null +++ b/classes/class_concavepolygonshape3d.rst @@ -0,0 +1,124 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ConcavePolygonShape3D.xml. + +.. _class_ConcavePolygonShape3D: + +ConcavePolygonShape3D +===================== + +**Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +A 3D trimesh shape used for physics collision. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A 3D trimesh shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. + +Being just a collection of interconnected triangles, **ConcavePolygonShape3D** is the most freely configurable single 3D shape. It can be used to form polyhedra of any nature, or even shapes that don't enclose a volume. However, **ConcavePolygonShape3D** is *hollow* even if the interconnected triangles do enclose a volume, which often makes it unsuitable for physics or detection. + +\ **Note:** When used for collision, **ConcavePolygonShape3D** is intended to work with static :ref:`CollisionShape3D` nodes like :ref:`StaticBody3D` and will likely not behave well for :ref:`CharacterBody3D`\ s or :ref:`RigidBody3D`\ s in a mode other than Static. + +\ **Warning:** Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. **ConcavePolygonShape3D** is hollow, so it won't detect a collision. + +\ **Performance:** Due to its complexity, **ConcavePolygonShape3D** is the slowest 3D collision shape to check collisions against. Its use should generally be limited to level geometry. For convex geometry, :ref:`ConvexPolygonShape3D` should be used. For dynamic physics bodies that need concave collision, several :ref:`ConvexPolygonShape3D`\ s can be used to represent its collision by using convex decomposition; see :ref:`ConvexPolygonShape3D`'s documentation for instructions. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `3D Physics Tests Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`backface_collision` | ``false`` | + +-------------------------+------------------------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector3Array` | :ref:`get_faces`\ (\ ) |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_faces`\ (\ faces\: :ref:`PackedVector3Array`\ ) | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_ConcavePolygonShape3D_property_backface_collision: + +.. rst-class:: classref-property + +:ref:`bool` **backface_collision** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_backface_collision_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_backface_collision_enabled**\ (\ ) + +If set to ``true``, collisions occur on both sides of the concave shape faces. Otherwise they occur only along the face normals. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_ConcavePolygonShape3D_method_get_faces: + +.. rst-class:: classref-method + +:ref:`PackedVector3Array` **get_faces**\ (\ ) |const| :ref:`🔗` + +Returns the faces of the trimesh shape as an array of vertices. The array (of length divisible by three) is naturally divided into triples; each triple of vertices defines a triangle. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ConcavePolygonShape3D_method_set_faces: + +.. rst-class:: classref-method + +|void| **set_faces**\ (\ faces\: :ref:`PackedVector3Array`\ ) :ref:`🔗` + +Sets the faces of the trimesh shape from an array of vertices. The ``faces`` array should be composed of triples such that each triple of vertices defines a triangle. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_conetwistjoint.rst b/classes/class_conetwistjoint.rst deleted file mode 100644 index dc895133ef6..00000000000 --- a/classes/class_conetwistjoint.rst +++ /dev/null @@ -1,185 +0,0 @@ -:github_url: hide - -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ConeTwistJoint.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. - -.. _class_ConeTwistJoint: - -ConeTwistJoint -============== - -**Inherits:** :ref:`Joint` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` - -A twist joint between two 3D bodies. - -Description ------------ - -The joint can rotate the bodies across an axis defined by the local x-axes of the :ref:`Joint`. - -The twist axis is initiated as the X axis of the :ref:`Joint`. - -Once the Bodies swing, the twist axis is calculated as the middle of the x-axes of the Joint in the local space of the two Bodies. - -Properties ----------- - -+---------------------------+-------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`bias` | ``0.3`` | -+---------------------------+-------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`relaxation` | ``1.0`` | -+---------------------------+-------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`softness` | ``0.8`` | -+---------------------------+-------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`swing_span` | ``45.0`` | -+---------------------------+-------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`twist_span` | ``180.0`` | -+---------------------------+-------------------------------------------------------------+-----------+ - -Methods -------- - -+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_param` **(** :ref:`Param` param **)** const | -+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_param` **(** :ref:`Param` param, :ref:`float` value **)** | -+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - -Enumerations ------------- - -.. _enum_ConeTwistJoint_Param: - -.. _class_ConeTwistJoint_constant_PARAM_SWING_SPAN: - -.. _class_ConeTwistJoint_constant_PARAM_TWIST_SPAN: - -.. _class_ConeTwistJoint_constant_PARAM_BIAS: - -.. _class_ConeTwistJoint_constant_PARAM_SOFTNESS: - -.. _class_ConeTwistJoint_constant_PARAM_RELAXATION: - -.. _class_ConeTwistJoint_constant_PARAM_MAX: - -enum **Param**: - -- **PARAM_SWING_SPAN** = **0** --- Swing is rotation from side to side, around the axis perpendicular to the twist axis. - -The swing span defines, how much rotation will not get corrected along the swing axis. - -Could be defined as looseness in the ``ConeTwistJoint``. - -If below 0.05, this behavior is locked. - -- **PARAM_TWIST_SPAN** = **1** --- Twist is the rotation around the twist axis, this value defined how far the joint can twist. - -Twist is locked if below 0.05. - -- **PARAM_BIAS** = **2** --- The speed with which the swing or twist will take place. - -The higher, the faster. - -- **PARAM_SOFTNESS** = **3** --- The ease with which the joint starts to twist. If it's too low, it takes more force to start twisting the joint. - -- **PARAM_RELAXATION** = **4** --- Defines, how fast the swing- and twist-speed-difference on both sides gets synced. - -- **PARAM_MAX** = **5** --- Represents the size of the :ref:`Param` enum. - -Property Descriptions ---------------------- - -.. _class_ConeTwistJoint_property_bias: - -- :ref:`float` **bias** - -+-----------+------------------+ -| *Default* | ``0.3`` | -+-----------+------------------+ -| *Setter* | set_param(value) | -+-----------+------------------+ -| *Getter* | get_param() | -+-----------+------------------+ - -The speed with which the swing or twist will take place. - -The higher, the faster. - ----- - -.. _class_ConeTwistJoint_property_relaxation: - -- :ref:`float` **relaxation** - -+-----------+------------------+ -| *Default* | ``1.0`` | -+-----------+------------------+ -| *Setter* | set_param(value) | -+-----------+------------------+ -| *Getter* | get_param() | -+-----------+------------------+ - -Defines, how fast the swing- and twist-speed-difference on both sides gets synced. - ----- - -.. _class_ConeTwistJoint_property_softness: - -- :ref:`float` **softness** - -+-----------+------------------+ -| *Default* | ``0.8`` | -+-----------+------------------+ -| *Setter* | set_param(value) | -+-----------+------------------+ -| *Getter* | get_param() | -+-----------+------------------+ - -The ease with which the joint starts to twist. If it's too low, it takes more force to start twisting the joint. - ----- - -.. _class_ConeTwistJoint_property_swing_span: - -- :ref:`float` **swing_span** - -+-----------+----------+ -| *Default* | ``45.0`` | -+-----------+----------+ - -Swing is rotation from side to side, around the axis perpendicular to the twist axis. - -The swing span defines, how much rotation will not get corrected along the swing axis. - -Could be defined as looseness in the ``ConeTwistJoint``. - -If below 0.05, this behavior is locked. - ----- - -.. _class_ConeTwistJoint_property_twist_span: - -- :ref:`float` **twist_span** - -+-----------+-----------+ -| *Default* | ``180.0`` | -+-----------+-----------+ - -Twist is the rotation around the twist axis, this value defined how far the joint can twist. - -Twist is locked if below 0.05. - -Method Descriptions -------------------- - -.. _class_ConeTwistJoint_method_get_param: - -- :ref:`float` **get_param** **(** :ref:`Param` param **)** const - ----- - -.. _class_ConeTwistJoint_method_set_param: - -- void **set_param** **(** :ref:`Param` param, :ref:`float` value **)** - diff --git a/classes/class_conetwistjoint3d.rst b/classes/class_conetwistjoint3d.rst new file mode 100644 index 00000000000..044a00bb9a2 --- /dev/null +++ b/classes/class_conetwistjoint3d.rst @@ -0,0 +1,268 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ConeTwistJoint3D.xml. + +.. _class_ConeTwistJoint3D: + +ConeTwistJoint3D +================ + +**Inherits:** :ref:`Joint3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +A physics joint that connects two 3D physics bodies in a way that simulates a ball-and-socket joint. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A physics joint that connects two 3D physics bodies in a way that simulates a ball-and-socket joint. The twist axis is initiated as the X axis of the **ConeTwistJoint3D**. Once the physics bodies swing, the twist axis is calculated as the middle of the X axes of the joint in the local space of the two physics bodies. Useful for limbs like shoulders and hips, lamps hanging off a ceiling, etc. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`bias` | ``0.3`` | + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`relaxation` | ``1.0`` | + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`softness` | ``0.8`` | + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`swing_span` | ``0.7853982`` | + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`twist_span` | ``3.1415927`` | + +---------------------------+---------------------------------------------------------------+---------------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_param`\ (\ param\: :ref:`Param`\ ) |const| | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_param`\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_ConeTwistJoint3D_Param: + +.. rst-class:: classref-enumeration + +enum **Param**: :ref:`🔗` + +.. _class_ConeTwistJoint3D_constant_PARAM_SWING_SPAN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Param` **PARAM_SWING_SPAN** = ``0`` + +Swing is rotation from side to side, around the axis perpendicular to the twist axis. + +The swing span defines, how much rotation will not get corrected along the swing axis. + +Could be defined as looseness in the **ConeTwistJoint3D**. + +If below 0.05, this behavior is locked. + +.. _class_ConeTwistJoint3D_constant_PARAM_TWIST_SPAN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Param` **PARAM_TWIST_SPAN** = ``1`` + +Twist is the rotation around the twist axis, this value defined how far the joint can twist. + +Twist is locked if below 0.05. + +.. _class_ConeTwistJoint3D_constant_PARAM_BIAS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Param` **PARAM_BIAS** = ``2`` + +The speed with which the swing or twist will take place. + +The higher, the faster. + +.. _class_ConeTwistJoint3D_constant_PARAM_SOFTNESS: + +.. rst-class:: classref-enumeration-constant + +:ref:`Param` **PARAM_SOFTNESS** = ``3`` + +The ease with which the joint starts to twist. If it's too low, it takes more force to start twisting the joint. + +.. _class_ConeTwistJoint3D_constant_PARAM_RELAXATION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Param` **PARAM_RELAXATION** = ``4`` + +Defines, how fast the swing- and twist-speed-difference on both sides gets synced. + +.. _class_ConeTwistJoint3D_constant_PARAM_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`Param` **PARAM_MAX** = ``5`` + +Represents the size of the :ref:`Param` enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_ConeTwistJoint3D_property_bias: + +.. rst-class:: classref-property + +:ref:`float` **bias** = ``0.3`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_param**\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) +- :ref:`float` **get_param**\ (\ param\: :ref:`Param`\ ) |const| + +The speed with which the swing or twist will take place. + +The higher, the faster. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ConeTwistJoint3D_property_relaxation: + +.. rst-class:: classref-property + +:ref:`float` **relaxation** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_param**\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) +- :ref:`float` **get_param**\ (\ param\: :ref:`Param`\ ) |const| + +Defines, how fast the swing- and twist-speed-difference on both sides gets synced. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ConeTwistJoint3D_property_softness: + +.. rst-class:: classref-property + +:ref:`float` **softness** = ``0.8`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_param**\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) +- :ref:`float` **get_param**\ (\ param\: :ref:`Param`\ ) |const| + +The ease with which the joint starts to twist. If it's too low, it takes more force to start twisting the joint. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ConeTwistJoint3D_property_swing_span: + +.. rst-class:: classref-property + +:ref:`float` **swing_span** = ``0.7853982`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_param**\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) +- :ref:`float` **get_param**\ (\ param\: :ref:`Param`\ ) |const| + +Swing is rotation from side to side, around the axis perpendicular to the twist axis. + +The swing span defines, how much rotation will not get corrected along the swing axis. + +Could be defined as looseness in the **ConeTwistJoint3D**. + +If below 0.05, this behavior is locked. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ConeTwistJoint3D_property_twist_span: + +.. rst-class:: classref-property + +:ref:`float` **twist_span** = ``3.1415927`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_param**\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) +- :ref:`float` **get_param**\ (\ param\: :ref:`Param`\ ) |const| + +Twist is the rotation around the twist axis, this value defined how far the joint can twist. + +Twist is locked if below 0.05. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_ConeTwistJoint3D_method_get_param: + +.. rst-class:: classref-method + +:ref:`float` **get_param**\ (\ param\: :ref:`Param`\ ) |const| :ref:`🔗` + +Returns the value of the specified parameter. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ConeTwistJoint3D_method_set_param: + +.. rst-class:: classref-method + +|void| **set_param**\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) :ref:`🔗` + +Sets the value of the specified parameter. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_configfile.rst b/classes/class_configfile.rst index e0d775f0eba..5925b35cc54 100644 --- a/classes/class_configfile.rst +++ b/classes/class_configfile.rst @@ -1,218 +1,400 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ConfigFile.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ConfigFile.xml. .. _class_ConfigFile: ConfigFile ========== -**Inherits:** :ref:`Reference` **<** :ref:`Object` +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` Helper class to handle INI-style files. +.. rst-class:: classref-introduction-group + Description ----------- This helper class can be used to store :ref:`Variant` values on the filesystem using INI-style formatting. The stored values are identified by a section and a key: -:: +.. code:: text [section] some_key=42 - string_example="Hello World!" - a_vector=Vector3( 1, 0, 2 ) + string_example="Hello World3D!" + a_vector=Vector3(1, 0, 2) The stored data can be saved to or parsed from a file, though ConfigFile objects can also be used directly without accessing the filesystem. -The following example shows how to parse an INI-style file from the system, read its contents and store new values in it: +The following example shows how to create a simple **ConfigFile** and save it on disc: + + +.. tabs:: -:: + .. code-tab:: gdscript + # Create new ConfigFile object. var config = ConfigFile.new() - var err = config.load("user://settings.cfg") - if err == OK: # If not, something went wrong with the file loading - # Look for the display/width pair, and default to 1024 if missing - var screen_width = config.get_value("display", "width", 1024) - # Store a variable if and only if it hasn't been defined yet - if not config.has_section_key("audio", "mute"): - config.set_value("audio", "mute", false) - # Save the changes by overwriting the previous file - config.save("user://settings.cfg") + + # Store some values. + config.set_value("Player1", "player_name", "Steve") + config.set_value("Player1", "best_score", 10) + config.set_value("Player2", "player_name", "V3geta") + config.set_value("Player2", "best_score", 9001) + + # Save it to a file (overwrite if already exists). + config.save("user://scores.cfg") + + .. code-tab:: csharp + + // Create new ConfigFile object. + var config = new ConfigFile(); + + // Store some values. + config.SetValue("Player1", "player_name", "Steve"); + config.SetValue("Player1", "best_score", 10); + config.SetValue("Player2", "player_name", "V3geta"); + config.SetValue("Player2", "best_score", 9001); + + // Save it to a file (overwrite if already exists). + config.Save("user://scores.cfg"); + + + +This example shows how the above file could be loaded: + + +.. tabs:: + + .. code-tab:: gdscript + + var score_data = {} + var config = ConfigFile.new() + + # Load data from a file. + var err = config.load("user://scores.cfg") + + # If the file didn't load, ignore it. + if err != OK: + return + + # Iterate over all sections. + for player in config.get_sections(): + # Fetch the data for each section. + var player_name = config.get_value(player, "player_name") + var player_score = config.get_value(player, "best_score") + score_data[player_name] = player_score + + .. code-tab:: csharp + + var score_data = new Godot.Collections.Dictionary(); + var config = new ConfigFile(); + + // Load data from a file. + Error err = config.Load("user://scores.cfg"); + + // If the file didn't load, ignore it. + if (err != Error.Ok) + { + return; + } + + // Iterate over all sections. + foreach (String player in config.GetSections()) + { + // Fetch the data for each section. + var player_name = (String)config.GetValue(player, "player_name"); + var player_score = (int)config.GetValue(player, "best_score"); + score_data[player_name] = player_score; + } + + + +Any operation that mutates the ConfigFile such as :ref:`set_value()`, :ref:`clear()`, or :ref:`erase_section()`, only changes what is loaded in memory. If you want to write the change to a file, you have to save the changes with :ref:`save()`, :ref:`save_encrypted()`, or :ref:`save_encrypted_pass()`. Keep in mind that section and property names can't contain spaces. Anything after a space will be ignored on save and on load. ConfigFiles can also contain manually written comment lines starting with a semicolon (``;``). Those lines will be ignored when parsing the file. Note that comments will be lost when saving the ConfigFile. This can still be useful for dedicated server configuration files, which are typically never overwritten without explicit user action. +\ **Note:** The file extension given to a ConfigFile does not have any impact on its formatting or behavior. By convention, the ``.cfg`` extension is used here, but any other extension such as ``.ini`` is also valid. Since neither ``.cfg`` nor ``.ini`` are standardized, Godot's ConfigFile formatting may differ from files written by other programs. + +.. rst-class:: classref-reftable-group + Methods ------- -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`erase_section` **(** :ref:`String` section **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`erase_section_key` **(** :ref:`String` section, :ref:`String` key **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_section_keys` **(** :ref:`String` section **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_sections` **(** **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`get_value` **(** :ref:`String` section, :ref:`String` key, :ref:`Variant` default=null **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_section` **(** :ref:`String` section **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_section_key` **(** :ref:`String` section, :ref:`String` key **)** const | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`load` **(** :ref:`String` path **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`load_encrypted` **(** :ref:`String` path, :ref:`PackedByteArray` key **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`load_encrypted_pass` **(** :ref:`String` path, :ref:`String` password **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`parse` **(** :ref:`String` data **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`save` **(** :ref:`String` path **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`save_encrypted` **(** :ref:`String` path, :ref:`PackedByteArray` key **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`save_encrypted_pass` **(** :ref:`String` path, :ref:`String` password **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_value` **(** :ref:`String` section, :ref:`String` key, :ref:`Variant` value **)** | -+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear`\ (\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`encode_to_text`\ (\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`erase_section`\ (\ section\: :ref:`String`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`erase_section_key`\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_section_keys`\ (\ section\: :ref:`String`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_sections`\ (\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get_value`\ (\ section\: :ref:`String`, key\: :ref:`String`, default\: :ref:`Variant` = null\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_section`\ (\ section\: :ref:`String`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_section_key`\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`load`\ (\ path\: :ref:`String`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`load_encrypted`\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`load_encrypted_pass`\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`parse`\ (\ data\: :ref:`String`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`save`\ (\ path\: :ref:`String`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`save_encrypted`\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`save_encrypted_pass`\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_value`\ (\ section\: :ref:`String`, key\: :ref:`String`, value\: :ref:`Variant`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- +.. _class_ConfigFile_method_clear: + +.. rst-class:: classref-method + +|void| **clear**\ (\ ) :ref:`🔗` + +Removes the entire contents of the config. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ConfigFile_method_encode_to_text: + +.. rst-class:: classref-method + +:ref:`String` **encode_to_text**\ (\ ) |const| :ref:`🔗` + +Obtain the text version of this config file (the same text that would be written to a file). + +.. rst-class:: classref-item-separator + +---- + .. _class_ConfigFile_method_erase_section: -- void **erase_section** **(** :ref:`String` section **)** +.. rst-class:: classref-method + +|void| **erase_section**\ (\ section\: :ref:`String`\ ) :ref:`🔗` Deletes the specified section along with all the key-value pairs inside. Raises an error if the section does not exist. +.. rst-class:: classref-item-separator + ---- .. _class_ConfigFile_method_erase_section_key: -- void **erase_section_key** **(** :ref:`String` section, :ref:`String` key **)** +.. rst-class:: classref-method + +|void| **erase_section_key**\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) :ref:`🔗` Deletes the specified key in a section. Raises an error if either the section or the key do not exist. +.. rst-class:: classref-item-separator + ---- .. _class_ConfigFile_method_get_section_keys: -- :ref:`PackedStringArray` **get_section_keys** **(** :ref:`String` section **)** const +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_section_keys**\ (\ section\: :ref:`String`\ ) |const| :ref:`🔗` Returns an array of all defined key identifiers in the specified section. Raises an error and returns an empty array if the section does not exist. +.. rst-class:: classref-item-separator + ---- .. _class_ConfigFile_method_get_sections: -- :ref:`PackedStringArray` **get_sections** **(** **)** const +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_sections**\ (\ ) |const| :ref:`🔗` Returns an array of all defined section identifiers. +.. rst-class:: classref-item-separator + ---- .. _class_ConfigFile_method_get_value: -- :ref:`Variant` **get_value** **(** :ref:`String` section, :ref:`String` key, :ref:`Variant` default=null **)** const +.. rst-class:: classref-method + +:ref:`Variant` **get_value**\ (\ section\: :ref:`String`, key\: :ref:`String`, default\: :ref:`Variant` = null\ ) |const| :ref:`🔗` Returns the current value for the specified section and key. If either the section or the key do not exist, the method returns the fallback ``default`` value. If ``default`` is not specified or set to ``null``, an error is also raised. +.. rst-class:: classref-item-separator + ---- .. _class_ConfigFile_method_has_section: -- :ref:`bool` **has_section** **(** :ref:`String` section **)** const +.. rst-class:: classref-method + +:ref:`bool` **has_section**\ (\ section\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if the specified section exists. +.. rst-class:: classref-item-separator + ---- .. _class_ConfigFile_method_has_section_key: -- :ref:`bool` **has_section_key** **(** :ref:`String` section, :ref:`String` key **)** const +.. rst-class:: classref-method + +:ref:`bool` **has_section_key**\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if the specified section-key pair exists. +.. rst-class:: classref-item-separator + ---- .. _class_ConfigFile_method_load: -- :ref:`Error` **load** **(** :ref:`String` path **)** +.. rst-class:: classref-method + +:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` -Loads the config file specified as a parameter. The file's contents are parsed and loaded in the ``ConfigFile`` object which the method was called on. +Loads the config file specified as a parameter. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. -Returns one of the :ref:`Error` code constants (``OK`` on success). +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. + +.. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_load_encrypted: -- :ref:`Error` **load_encrypted** **(** :ref:`String` path, :ref:`PackedByteArray` key **)** +.. rst-class:: classref-method + +:ref:`Error` **load_encrypted**\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) :ref:`🔗` + +Loads the encrypted config file specified as a parameter, using the provided ``key`` to decrypt it. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. -Loads the encrypted config file specified as a parameter, using the provided ``key`` to decrypt it. The file's contents are parsed and loaded in the ``ConfigFile`` object which the method was called on. +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. -Returns one of the :ref:`Error` code constants (``OK`` on success). +.. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_load_encrypted_pass: -- :ref:`Error` **load_encrypted_pass** **(** :ref:`String` path, :ref:`String` password **)** +.. rst-class:: classref-method + +:ref:`Error` **load_encrypted_pass**\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) :ref:`🔗` + +Loads the encrypted config file specified as a parameter, using the provided ``password`` to decrypt it. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. -Loads the encrypted config file specified as a parameter, using the provided ``password`` to decrypt it. The file's contents are parsed and loaded in the ``ConfigFile`` object which the method was called on. +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. -Returns one of the :ref:`Error` code constants (``OK`` on success). +.. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_parse: -- :ref:`Error` **parse** **(** :ref:`String` data **)** +.. rst-class:: classref-method -Parses the the passed string as the contents of a config file. The string is parsed and loaded in the ConfigFile object which the method was called on. +:ref:`Error` **parse**\ (\ data\: :ref:`String`\ ) :ref:`🔗` -Returns one of the :ref:`Error` code constants (``OK`` on success). +Parses the passed string as the contents of a config file. The string is parsed and loaded in the ConfigFile object which the method was called on. + +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. + +.. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_save: -- :ref:`Error` **save** **(** :ref:`String` path **)** +.. rst-class:: classref-method + +:ref:`Error` **save**\ (\ path\: :ref:`String`\ ) :ref:`🔗` -Saves the contents of the ``ConfigFile`` object to the file specified as a parameter. The output file uses an INI-style structure. +Saves the contents of the **ConfigFile** object to the file specified as a parameter. The output file uses an INI-style structure. -Returns one of the :ref:`Error` code constants (``OK`` on success). +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. + +.. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_save_encrypted: -- :ref:`Error` **save_encrypted** **(** :ref:`String` path, :ref:`PackedByteArray` key **)** +.. rst-class:: classref-method + +:ref:`Error` **save_encrypted**\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) :ref:`🔗` -Saves the contents of the ``ConfigFile`` object to the AES-256 encrypted file specified as a parameter, using the provided ``key`` to encrypt it. The output file uses an INI-style structure. +Saves the contents of the **ConfigFile** object to the AES-256 encrypted file specified as a parameter, using the provided ``key`` to encrypt it. The output file uses an INI-style structure. -Returns one of the :ref:`Error` code constants (``OK`` on success). +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. + +.. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_save_encrypted_pass: -- :ref:`Error` **save_encrypted_pass** **(** :ref:`String` path, :ref:`String` password **)** +.. rst-class:: classref-method + +:ref:`Error` **save_encrypted_pass**\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) :ref:`🔗` -Saves the contents of the ``ConfigFile`` object to the AES-256 encrypted file specified as a parameter, using the provided ``password`` to encrypt it. The output file uses an INI-style structure. +Saves the contents of the **ConfigFile** object to the AES-256 encrypted file specified as a parameter, using the provided ``password`` to encrypt it. The output file uses an INI-style structure. -Returns one of the :ref:`Error` code constants (``OK`` on success). +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. + +.. rst-class:: classref-item-separator ---- .. _class_ConfigFile_method_set_value: -- void **set_value** **(** :ref:`String` section, :ref:`String` key, :ref:`Variant` value **)** +.. rst-class:: classref-method + +|void| **set_value**\ (\ section\: :ref:`String`, key\: :ref:`String`, value\: :ref:`Variant`\ ) :ref:`🔗` Assigns a value to the specified key of the specified section. If either the section or the key do not exist, they are created. Passing a ``null`` value deletes the specified key if it exists, and deletes the section if it ends up empty once the key has been removed. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_confirmationdialog.rst b/classes/class_confirmationdialog.rst index 38364f53958..d05027caff7 100644 --- a/classes/class_confirmationdialog.rst +++ b/classes/class_confirmationdialog.rst @@ -1,53 +1,122 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the ConfirmationDialog.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/ConfirmationDialog.xml. .. _class_ConfirmationDialog: ConfirmationDialog ================== -**Inherits:** :ref:`AcceptDialog` **<** :ref:`WindowDialog` **<** :ref:`Popup` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` +**Inherits:** :ref:`AcceptDialog` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -**Inherited By:** :ref:`EditorFileDialog`, :ref:`FileDialog`, :ref:`ScriptCreateDialog` +**Inherited By:** :ref:`EditorCommandPalette`, :ref:`EditorFileDialog`, :ref:`FileDialog`, :ref:`ScriptCreateDialog` -Dialog for confirmation of actions. +A dialog used for confirmation of actions. + +.. rst-class:: classref-introduction-group Description ----------- -Dialog for confirmation of actions. This dialog inherits from :ref:`AcceptDialog`, but has by default an OK and Cancel button (in host OS order). +A dialog used for confirmation of actions. This window is similar to :ref:`AcceptDialog`, but pressing its Cancel button can have a different outcome from pressing the OK button. The order of the two buttons varies depending on the host OS. To get cancel action, you can use: -:: - get_cancel().connect("pressed", self, "cancelled"). +.. tabs:: + + .. code-tab:: gdscript + + get_cancel_button().pressed.connect(_on_canceled) + + .. code-tab:: csharp + + GetCancelButton().Pressed += OnCanceled; + + + +\ **Note:** :ref:`AcceptDialog` is invisible by default. To make it visible, call one of the ``popup_*`` methods from :ref:`Window` on the node, such as :ref:`Window.popup_centered_clamped()`. + +.. rst-class:: classref-reftable-group Properties ---------- -+-------------------------------+---------------+--------------------------------+ -| :ref:`Vector2` | rect_min_size | **O:** ``Vector2( 200, 70 )`` | -+-------------------------------+---------------+--------------------------------+ -| :ref:`String` | window_title | **O:** ``"Please Confirm..."`` | -+-------------------------------+---------------+--------------------------------+ +.. table:: + :widths: auto + + +---------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`cancel_button_text` | ``"Cancel"`` | + +---------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ + | :ref:`Vector2i` | min_size | ``Vector2i(200, 70)`` (overrides :ref:`Window`) | + +---------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ + | :ref:`Vector2i` | size | ``Vector2i(200, 100)`` (overrides :ref:`Window`) | + +---------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ + | :ref:`String` | title | ``"Please Confirm..."`` (overrides :ref:`Window`) | + +---------------------------------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+-----------------------------+---------------------------------------------------------------------------+ -| :ref:`Button` | :ref:`get_cancel` **(** **)** | -+-----------------------------+---------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-----------------------------+-----------------------------------------------------------------------------------+ + | :ref:`Button` | :ref:`get_cancel_button`\ (\ ) | + +-----------------------------+-----------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_ConfirmationDialog_property_cancel_button_text: + +.. rst-class:: classref-property + +:ref:`String` **cancel_button_text** = ``"Cancel"`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_cancel_button_text**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_cancel_button_text**\ (\ ) + +The text displayed by the cancel button (see :ref:`get_cancel_button()`). + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- -.. _class_ConfirmationDialog_method_get_cancel: +.. _class_ConfirmationDialog_method_get_cancel_button: + +.. rst-class:: classref-method -- :ref:`Button` **get_cancel** **(** **)** +:ref:`Button` **get_cancel_button**\ (\ ) :ref:`🔗` Returns the cancel button. +\ **Warning:** This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`CanvasItem.visible` property. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_container.rst b/classes/class_container.rst index b15656dec24..7aa4d835398 100644 --- a/classes/class_container.rst +++ b/classes/class_container.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Container.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Container.xml. .. _class_Container: @@ -11,63 +12,171 @@ Container **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -**Inherited By:** :ref:`BoxContainer`, :ref:`CenterContainer`, :ref:`EditorProperty`, :ref:`GraphNode`, :ref:`GridContainer`, :ref:`MarginContainer`, :ref:`PanelContainer`, :ref:`ScrollContainer`, :ref:`SplitContainer`, :ref:`TabContainer`, :ref:`ViewportContainer` +**Inherited By:** :ref:`AspectRatioContainer`, :ref:`BoxContainer`, :ref:`CenterContainer`, :ref:`EditorProperty`, :ref:`FlowContainer`, :ref:`FoldableContainer`, :ref:`GraphElement`, :ref:`GridContainer`, :ref:`MarginContainer`, :ref:`PanelContainer`, :ref:`ScrollContainer`, :ref:`SplitContainer`, :ref:`SubViewportContainer`, :ref:`TabContainer` -Base node for containers. +Base class for all GUI containers. + +.. rst-class:: classref-introduction-group Description ----------- -Base node for containers. A ``Container`` contains other controls and automatically arranges them in a certain way. +Base class for all GUI containers. A **Container** automatically arranges its child controls in a certain way. This class can be inherited to make custom container types. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- -A Control can inherit this to create custom container classes. +- :doc:`Using Containers <../tutorials/ui/gui_containers>` + +.. rst-class:: classref-reftable-group Properties ---------- -+----------------------------------------------+--------------+--------------+ -| :ref:`MouseFilter` | mouse_filter | **O:** ``1`` | -+----------------------------------------------+--------------+--------------+ +.. table:: + :widths: auto + + +----------------------------------------------+--------------+-----------------------------------------------------------------------+ + | :ref:`MouseFilter` | mouse_filter | ``1`` (overrides :ref:`Control`) | + +----------------------------------------------+--------------+-----------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`fit_child_in_rect` **(** :ref:`Control` child, :ref:`Rect2` rect **)** | -+------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`queue_sort` **(** **)** | -+------+----------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`_get_allowed_size_flags_horizontal`\ (\ ) |virtual| |const| | + +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`_get_allowed_size_flags_vertical`\ (\ ) |virtual| |const| | + +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fit_child_in_rect`\ (\ child\: :ref:`Control`, rect\: :ref:`Rect2`\ ) | + +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`queue_sort`\ (\ ) | + +-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- +.. _class_Container_signal_pre_sort_children: + +.. rst-class:: classref-signal + +**pre_sort_children**\ (\ ) :ref:`🔗` + +Emitted when children are going to be sorted. + +.. rst-class:: classref-item-separator + +---- + .. _class_Container_signal_sort_children: -- **sort_children** **(** **)** +.. rst-class:: classref-signal + +**sort_children**\ (\ ) :ref:`🔗` Emitted when sorting the children is needed. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Constants --------- +.. _class_Container_constant_NOTIFICATION_PRE_SORT_CHILDREN: + +.. rst-class:: classref-constant + +**NOTIFICATION_PRE_SORT_CHILDREN** = ``50`` :ref:`🔗` + +Notification just before children are going to be sorted, in case there's something to process beforehand. + .. _class_Container_constant_NOTIFICATION_SORT_CHILDREN: -- **NOTIFICATION_SORT_CHILDREN** = **50** --- Notification for when sorting the children, it must be obeyed immediately. +.. rst-class:: classref-constant + +**NOTIFICATION_SORT_CHILDREN** = ``51`` :ref:`🔗` + +Notification for when sorting the children, it must be obeyed immediately. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Method Descriptions ------------------- +.. _class_Container_private_method__get_allowed_size_flags_horizontal: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **_get_allowed_size_flags_horizontal**\ (\ ) |virtual| |const| :ref:`🔗` + +Implement to return a list of allowed horizontal :ref:`SizeFlags` for child nodes. This doesn't technically prevent the usages of any other size flags, if your implementation requires that. This only limits the options available to the user in the Inspector dock. + +\ **Note:** Having no size flags is equal to having :ref:`Control.SIZE_SHRINK_BEGIN`. As such, this value is always implicitly allowed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Container_private_method__get_allowed_size_flags_vertical: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **_get_allowed_size_flags_vertical**\ (\ ) |virtual| |const| :ref:`🔗` + +Implement to return a list of allowed vertical :ref:`SizeFlags` for child nodes. This doesn't technically prevent the usages of any other size flags, if your implementation requires that. This only limits the options available to the user in the Inspector dock. + +\ **Note:** Having no size flags is equal to having :ref:`Control.SIZE_SHRINK_BEGIN`. As such, this value is always implicitly allowed. + +.. rst-class:: classref-item-separator + +---- + .. _class_Container_method_fit_child_in_rect: -- void **fit_child_in_rect** **(** :ref:`Control` child, :ref:`Rect2` rect **)** +.. rst-class:: classref-method + +|void| **fit_child_in_rect**\ (\ child\: :ref:`Control`, rect\: :ref:`Rect2`\ ) :ref:`🔗` Fit a child control in a given rect. This is mainly a helper for creating custom container classes. +.. rst-class:: classref-item-separator + ---- .. _class_Container_method_queue_sort: -- void **queue_sort** **(** **)** +.. rst-class:: classref-method + +|void| **queue_sort**\ (\ ) :ref:`🔗` Queue resort of the contained children. This is called automatically anyway, but can be called upon request. +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_control.rst b/classes/class_control.rst index 7e8d068c8a7..84a2b1408ca 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -1,8 +1,9 @@ :github_url: hide -.. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the Control.xml source instead. -.. The source is found in doc/classes or modules//doc_classes. +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Control.xml. .. _class_Control: @@ -11,1820 +12,3813 @@ Control **Inherits:** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -**Inherited By:** :ref:`BaseButton`, :ref:`ColorRect`, :ref:`Container`, :ref:`GraphEdit`, :ref:`ItemList`, :ref:`Label`, :ref:`LineEdit`, :ref:`NinePatchRect`, :ref:`Panel`, :ref:`Popup`, :ref:`Range`, :ref:`ReferenceRect`, :ref:`RichTextLabel`, :ref:`Separator`, :ref:`Tabs`, :ref:`TextEdit`, :ref:`TextureRect`, :ref:`Tree`, :ref:`VideoPlayer` +**Inherited By:** :ref:`BaseButton`, :ref:`ColorRect`, :ref:`Container`, :ref:`GraphEdit`, :ref:`ItemList`, :ref:`Label`, :ref:`LineEdit`, :ref:`MenuBar`, :ref:`NinePatchRect`, :ref:`Panel`, :ref:`Range`, :ref:`ReferenceRect`, :ref:`RichTextLabel`, :ref:`Separator`, :ref:`TabBar`, :ref:`TextEdit`, :ref:`TextureRect`, :ref:`Tree`, :ref:`VideoStreamPlayer` -All user interface nodes inherit from Control. A control's anchors and margins adapt its position and size relative to its parent. +Base class for all GUI controls. Adapts its position and size based on its parent control. + +.. rst-class:: classref-introduction-group Description ----------- -Base class for all UI-related nodes. ``Control`` features a bounding rectangle that defines its extents, an anchor position relative to its parent control or the current viewport, and margins that represent an offset to the anchor. The margins update automatically when the node, any of its parents, or the screen size change. +Base class for all UI-related nodes. **Control** features a bounding rectangle that defines its extents, an anchor position relative to its parent control or the current viewport, and offsets relative to the anchor. The offsets update automatically when the node, any of its parents, or the screen size change. + +For more information on Godot's UI system, anchors, offsets, and containers, see the related tutorials in the manual. To build flexible UIs, you'll need a mix of UI elements that inherit from **Control** and :ref:`Container` nodes. + +\ **Note:** Since both :ref:`Node2D` and **Control** inherit from :ref:`CanvasItem`, they share several concepts from the class such as the :ref:`CanvasItem.z_index` and :ref:`CanvasItem.visible` properties. + +\ **User Interface nodes and input**\ -For more information on Godot's UI system, anchors, margins, and containers, see the related tutorials in the manual. To build flexible UIs, you'll need a mix of UI elements that inherit from ``Control`` and :ref:`Container` nodes. +Godot propagates input events via viewports. Each :ref:`Viewport` is responsible for propagating :ref:`InputEvent`\ s to their child nodes. As the :ref:`SceneTree.root` is a :ref:`Window`, this already happens automatically for all UI elements in your game. -**User Interface nodes and input** +Input events are propagated through the :ref:`SceneTree` from the root node to all child nodes by calling :ref:`Node._input()`. For UI elements specifically, it makes more sense to override the virtual method :ref:`_gui_input()`, which filters out unrelated input events, such as by checking z-order, :ref:`mouse_filter`, focus, or if the event was inside of the control's bounding box. -Godot sends input events to the scene's root node first, by calling :ref:`Node._input`. :ref:`Node._input` forwards the event down the node tree to the nodes under the mouse cursor, or on keyboard focus. To do so, it calls :ref:`MainLoop._input_event`. Call :ref:`accept_event` so no other node receives the event. Once you accepted an input, it becomes handled so :ref:`Node._unhandled_input` will not process it. +Call :ref:`accept_event()` so no other node receives the event. Once you accept an input, it becomes handled so :ref:`Node._unhandled_input()` will not process it. -Only one ``Control`` node can be in keyboard focus. Only the node in focus will receive keyboard events. To get the focus, call :ref:`grab_focus`. ``Control`` nodes lose focus when another node grabs it, or if you hide the node in focus. +Only one **Control** node can be in focus. Only the node in focus will receive events. To get the focus, call :ref:`grab_focus()`. **Control** nodes lose focus when another node grabs it, or if you hide the node in focus. Focus will not be represented visually if gained via mouse/touch input, only appearing with keyboard/gamepad input (for accessibility), or via :ref:`grab_focus()`. -Sets :ref:`mouse_filter` to :ref:`MOUSE_FILTER_IGNORE` to tell a ``Control`` node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. +Sets :ref:`mouse_filter` to :ref:`MOUSE_FILTER_IGNORE` to tell a **Control** node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. -:ref:`Theme` resources change the Control's appearance. If you change the :ref:`Theme` on a ``Control`` node, it affects all of its children. To override some of the theme's parameters, call one of the ``add_*_override`` methods, like :ref:`add_font_override`. You can override the theme with the inspector. +\ :ref:`Theme` resources change the control's appearance. The :ref:`theme` of a **Control** node affects all of its direct and indirect children (as long as a chain of controls is uninterrupted). To override some of the theme items, call one of the ``add_theme_*_override`` methods, like :ref:`add_theme_font_override()`. You can also override theme items in the Inspector. + +\ **Note:** Theme items are *not* :ref:`Object` properties. This means you can't access their values using :ref:`Object.get()` and :ref:`Object.set()`. Instead, use the ``get_theme_*`` and ``add_theme_*_override`` methods provided by this class. + +.. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`../tutorials/ui/index` +- :doc:`GUI documentation index <../tutorials/ui/index>` + +- :doc:`Custom drawing in 2D <../tutorials/2d/custom_drawing_in_2d>` + +- :doc:`Control node gallery <../tutorials/ui/control_node_gallery>` -- :doc:`../tutorials/2d/custom_drawing_in_2d` +- :doc:`Multiple resolutions <../tutorials/rendering/multiple_resolutions>` + +- `All GUI Demos `__ + +.. rst-class:: classref-reftable-group Properties ---------- -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`anchor_bottom` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`anchor_left` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`anchor_right` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`anchor_top` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`FocusMode` | :ref:`focus_mode` | ``0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_neighbour_bottom` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_neighbour_left` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_neighbour_right` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_neighbour_top` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_next` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_previous` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`GrowDirection` | :ref:`grow_horizontal` | ``1`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`GrowDirection` | :ref:`grow_vertical` | ``1`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`String` | :ref:`hint_tooltip` | ``""`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`margin_bottom` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`margin_left` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`margin_right` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`margin_top` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`CursorShape` | :ref:`mouse_default_cursor_shape` | ``0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`MouseFilter` | :ref:`mouse_filter` | ``0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`rect_clip_content` | ``false`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_global_position` | | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_min_size` | ``Vector2( 0, 0 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_pivot_offset` | ``Vector2( 0, 0 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_position` | ``Vector2( 0, 0 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`rect_rotation` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_scale` | ``Vector2( 1, 1 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_size` | ``Vector2( 0, 0 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`size_flags_horizontal` | ``1`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`size_flags_stretch_ratio` | ``1.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`size_flags_vertical` | ``1`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Theme` | :ref:`theme` | | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ +.. table:: + :widths: auto + + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`NodePath`\] | :ref:`accessibility_controls_nodes` | ``[]`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`NodePath`\] | :ref:`accessibility_described_by_nodes` | ``[]`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`accessibility_description` | ``""`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`NodePath`\] | :ref:`accessibility_flow_to_nodes` | ``[]`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`NodePath`\] | :ref:`accessibility_labeled_by_nodes` | ``[]`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`AccessibilityLiveMode` | :ref:`accessibility_live` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`accessibility_name` | ``""`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`anchor_bottom` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`anchor_left` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`anchor_right` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`anchor_top` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`auto_translate` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`clip_contents` | ``false`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`custom_minimum_size` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`FocusBehaviorRecursive` | :ref:`focus_behavior_recursive` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`FocusMode` | :ref:`focus_mode` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_neighbor_bottom` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_neighbor_left` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_neighbor_right` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_neighbor_top` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_next` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_previous` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`global_position` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`GrowDirection` | :ref:`grow_horizontal` | ``1`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`GrowDirection` | :ref:`grow_vertical` | ``1`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`LayoutDirection` | :ref:`layout_direction` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`localize_numeral_system` | ``true`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`MouseBehaviorRecursive` | :ref:`mouse_behavior_recursive` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`CursorShape` | :ref:`mouse_default_cursor_shape` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`MouseFilter` | :ref:`mouse_filter` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`mouse_force_pass_scroll_events` | ``true`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`offset_bottom` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`offset_left` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`offset_right` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`offset_top` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`PhysicsInterpolationMode` | physics_interpolation_mode | ``2`` (overrides :ref:`Node`) | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`pivot_offset` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`pivot_offset_ratio` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`position` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`rotation` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`rotation_degrees` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`scale` | ``Vector2(1, 1)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Node` | :ref:`shortcut_context` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`size` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | |bitfield|\[:ref:`SizeFlags`\] | :ref:`size_flags_horizontal` | ``1`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`size_flags_stretch_ratio` | ``1.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | |bitfield|\[:ref:`SizeFlags`\] | :ref:`size_flags_vertical` | ``1`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Theme` | :ref:`theme` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`theme_type_variation` | ``&""`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`AutoTranslateMode` | :ref:`tooltip_auto_translate_mode` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`tooltip_text` | ``""`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. rst-class:: classref-reftable-group Methods ------- -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`_clips_input` **(** **)** virtual | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`_get_minimum_size` **(** **)** virtual | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`_gui_input` **(** :ref:`InputEvent` event **)** virtual | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Object` | :ref:`_make_custom_tooltip` **(** :ref:`String` for_text **)** virtual | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`accept_event` **(** **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_color_override` **(** :ref:`StringName` name, :ref:`Color` color **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_constant_override` **(** :ref:`StringName` name, :ref:`int` constant **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_font_override` **(** :ref:`StringName` name, :ref:`Font` font **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_icon_override` **(** :ref:`StringName` name, :ref:`Texture2D` texture **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_shader_override` **(** :ref:`StringName` name, :ref:`Shader` shader **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_stylebox_override` **(** :ref:`StringName` name, :ref:`StyleBox` stylebox **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`can_drop_data` **(** :ref:`Vector2` position, :ref:`Variant` data **)** virtual | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`drop_data` **(** :ref:`Vector2` position, :ref:`Variant` data **)** virtual | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`force_drag` **(** :ref:`Variant` data, :ref:`Control` preview **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_anchor` **(** :ref:`Margin` margin **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_begin` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`get_color` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_combined_minimum_size` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_constant` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`CursorShape` | :ref:`get_cursor_shape` **(** :ref:`Vector2` position=Vector2( 0, 0 ) **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`get_drag_data` **(** :ref:`Vector2` position **)** virtual | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_end` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`NodePath` | :ref:`get_focus_neighbour` **(** :ref:`Margin` margin **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Control` | :ref:`get_focus_owner` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Font` | :ref:`get_font` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Rect2` | :ref:`get_global_rect` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Texture2D` | :ref:`get_icon` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_margin` **(** :ref:`Margin` margin **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_minimum_size` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Vector2` | :ref:`get_parent_area_size` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Control` | :ref:`get_parent_control` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Rect2` | :ref:`get_rect` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_rotation` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StyleBox` | :ref:`get_stylebox` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_tooltip` **(** :ref:`Vector2` at_position=Vector2( 0, 0 ) **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`grab_click_focus` **(** **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`grab_focus` **(** **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_color` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_color_override` **(** :ref:`StringName` name **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_constant` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_constant_override` **(** :ref:`StringName` name **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_focus` **(** **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_font` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_font_override` **(** :ref:`StringName` name **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_icon` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_icon_override` **(** :ref:`StringName` name **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_point` **(** :ref:`Vector2` point **)** virtual | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_shader_override` **(** :ref:`StringName` name **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_stylebox` **(** :ref:`StringName` name, :ref:`StringName` type="" **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_stylebox_override` **(** :ref:`StringName` name **)** const | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`minimum_size_changed` **(** **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`release_focus` **(** **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_anchor` **(** :ref:`Margin` margin, :ref:`float` anchor, :ref:`bool` keep_margin=false, :ref:`bool` push_opposite_anchor=true **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_anchor_and_margin` **(** :ref:`Margin` margin, :ref:`float` anchor, :ref:`float` offset, :ref:`bool` push_opposite_anchor=false **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_anchors_and_margins_preset` **(** :ref:`LayoutPreset` preset, :ref:`LayoutPresetMode` resize_mode=0, :ref:`int` margin=0 **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_anchors_preset` **(** :ref:`LayoutPreset` preset, :ref:`bool` keep_margins=false **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_begin` **(** :ref:`Vector2` position **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_drag_forwarding` **(** :ref:`Control` target **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_drag_preview` **(** :ref:`Control` control **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_end` **(** :ref:`Vector2` position **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_focus_neighbour` **(** :ref:`Margin` margin, :ref:`NodePath` neighbour **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_global_position` **(** :ref:`Vector2` position, :ref:`bool` keep_margins=false **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_margin` **(** :ref:`Margin` margin, :ref:`float` offset **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_margins_preset` **(** :ref:`LayoutPreset` preset, :ref:`LayoutPresetMode` resize_mode=0, :ref:`int` margin=0 **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_position` **(** :ref:`Vector2` position, :ref:`bool` keep_margins=false **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_rotation` **(** :ref:`float` radians **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_size` **(** :ref:`Vector2` size, :ref:`bool` keep_margins=false **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`show_modal` **(** :ref:`bool` exclusive=false **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`warp_mouse` **(** :ref:`Vector2` to_position **)** | -+----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. table:: + :widths: auto + + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`_accessibility_get_contextual_info`\ (\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_can_drop_data`\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_drop_data`\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`_get_accessibility_container_name`\ (\ node\: :ref:`Node`\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`_get_drag_data`\ (\ at_position\: :ref:`Vector2`\ ) |virtual| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`_get_minimum_size`\ (\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`_get_tooltip`\ (\ at_position\: :ref:`Vector2`\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_gui_input`\ (\ event\: :ref:`InputEvent`\ ) |virtual| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_has_point`\ (\ point\: :ref:`Vector2`\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Object` | :ref:`_make_custom_tooltip`\ (\ for_text\: :ref:`String`\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Vector3i`\] | :ref:`_structured_text_parser`\ (\ args\: :ref:`Array`, text\: :ref:`String`\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`accept_event`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`accessibility_drag`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`accessibility_drop`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_theme_color_override`\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_theme_constant_override`\ (\ name\: :ref:`StringName`, constant\: :ref:`int`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_theme_font_override`\ (\ name\: :ref:`StringName`, font\: :ref:`Font`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_theme_font_size_override`\ (\ name\: :ref:`StringName`, font_size\: :ref:`int`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_theme_icon_override`\ (\ name\: :ref:`StringName`, texture\: :ref:`Texture2D`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_theme_stylebox_override`\ (\ name\: :ref:`StringName`, stylebox\: :ref:`StyleBox`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`begin_bulk_theme_override`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`end_bulk_theme_override`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Control` | :ref:`find_next_valid_focus`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Control` | :ref:`find_prev_valid_focus`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Control` | :ref:`find_valid_focus_neighbor`\ (\ side\: :ref:`Side`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`force_drag`\ (\ data\: :ref:`Variant`, preview\: :ref:`Control`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_anchor`\ (\ side\: :ref:`Side`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_begin`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_combined_minimum_size`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_combined_pivot_offset`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`CursorShape` | :ref:`get_cursor_shape`\ (\ position\: :ref:`Vector2` = Vector2(0, 0)\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_end`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FocusMode` | :ref:`get_focus_mode_with_override`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`get_focus_neighbor`\ (\ side\: :ref:`Side`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Rect2` | :ref:`get_global_rect`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_minimum_size`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`MouseFilter` | :ref:`get_mouse_filter_with_override`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_offset`\ (\ offset\: :ref:`Side`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_parent_area_size`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Control` | :ref:`get_parent_control`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Rect2` | :ref:`get_rect`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_screen_position`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`get_theme_color`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_theme_constant`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_theme_default_base_scale`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Font` | :ref:`get_theme_default_font`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_theme_default_font_size`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Font` | :ref:`get_theme_font`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_theme_font_size`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`get_theme_icon`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StyleBox` | :ref:`get_theme_stylebox`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_tooltip`\ (\ at_position\: :ref:`Vector2` = Vector2(0, 0)\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`grab_click_focus`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`grab_focus`\ (\ hide_focus\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_focus`\ (\ ignore_hidden_focus\: :ref:`bool` = false\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_color`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_color_override`\ (\ name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_constant`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_constant_override`\ (\ name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_font`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_font_override`\ (\ name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_font_size`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_font_size_override`\ (\ name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_icon`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_icon_override`\ (\ name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_stylebox`\ (\ name\: :ref:`StringName`, theme_type\: :ref:`StringName` = &""\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_theme_stylebox_override`\ (\ name\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_drag_successful`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_layout_rtl`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`release_focus`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_theme_color_override`\ (\ name\: :ref:`StringName`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_theme_constant_override`\ (\ name\: :ref:`StringName`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_theme_font_override`\ (\ name\: :ref:`StringName`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_theme_font_size_override`\ (\ name\: :ref:`StringName`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_theme_icon_override`\ (\ name\: :ref:`StringName`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_theme_stylebox_override`\ (\ name\: :ref:`StringName`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`reset_size`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_anchor`\ (\ side\: :ref:`Side`, anchor\: :ref:`float`, keep_offset\: :ref:`bool` = false, push_opposite_anchor\: :ref:`bool` = true\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_anchor_and_offset`\ (\ side\: :ref:`Side`, anchor\: :ref:`float`, offset\: :ref:`float`, push_opposite_anchor\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_anchors_and_offsets_preset`\ (\ preset\: :ref:`LayoutPreset`, resize_mode\: :ref:`LayoutPresetMode` = 0, margin\: :ref:`int` = 0\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_anchors_preset`\ (\ preset\: :ref:`LayoutPreset`, keep_offsets\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_begin`\ (\ position\: :ref:`Vector2`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_drag_forwarding`\ (\ drag_func\: :ref:`Callable`, can_drop_func\: :ref:`Callable`, drop_func\: :ref:`Callable`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_drag_preview`\ (\ control\: :ref:`Control`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_end`\ (\ position\: :ref:`Vector2`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_focus_neighbor`\ (\ side\: :ref:`Side`, neighbor\: :ref:`NodePath`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_global_position`\ (\ position\: :ref:`Vector2`, keep_offsets\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_offset`\ (\ side\: :ref:`Side`, offset\: :ref:`float`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_offsets_preset`\ (\ preset\: :ref:`LayoutPreset`, resize_mode\: :ref:`LayoutPresetMode` = 0, margin\: :ref:`int` = 0\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_position`\ (\ position\: :ref:`Vector2`, keep_offsets\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_size`\ (\ size\: :ref:`Vector2`, keep_offsets\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`update_minimum_size`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`warp_mouse`\ (\ position\: :ref:`Vector2`\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group Signals ------- .. _class_Control_signal_focus_entered: -- **focus_entered** **(** **)** +.. rst-class:: classref-signal + +**focus_entered**\ (\ ) :ref:`🔗` + +Emitted when the node gains focus. -Emitted when the node gains keyboard focus. +.. rst-class:: classref-item-separator ---- .. _class_Control_signal_focus_exited: -- **focus_exited** **(** **)** +.. rst-class:: classref-signal -Emitted when the node loses keyboard focus. +**focus_exited**\ (\ ) :ref:`🔗` + +Emitted when the node loses focus. + +.. rst-class:: classref-item-separator ---- .. _class_Control_signal_gui_input: -- **gui_input** **(** :ref:`InputEvent` event **)** +.. rst-class:: classref-signal + +**gui_input**\ (\ event\: :ref:`InputEvent`\ ) :ref:`🔗` Emitted when the node receives an :ref:`InputEvent`. +.. rst-class:: classref-item-separator + ---- .. _class_Control_signal_minimum_size_changed: -- **minimum_size_changed** **(** **)** +.. rst-class:: classref-signal + +**minimum_size_changed**\ (\ ) :ref:`🔗` Emitted when the node's minimum size changes. ----- +.. rst-class:: classref-item-separator -.. _class_Control_signal_modal_closed: +---- -- **modal_closed** **(** **)** +.. _class_Control_signal_mouse_entered: -Emitted when a modal ``Control`` is closed. See :ref:`show_modal`. +.. rst-class:: classref-signal ----- +**mouse_entered**\ (\ ) :ref:`🔗` -.. _class_Control_signal_mouse_entered: +Emitted when the mouse cursor enters the control's (or any child control's) visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. -- **mouse_entered** **(** **)** +\ **Note:** :ref:`CanvasItem.z_index` doesn't affect, which Control receives the signal. -Emitted when the mouse enters the control's ``Rect`` area, provided its :ref:`mouse_filter` lets the event reach it. +.. rst-class:: classref-item-separator ---- .. _class_Control_signal_mouse_exited: -- **mouse_exited** **(** **)** +.. rst-class:: classref-signal + +**mouse_exited**\ (\ ) :ref:`🔗` + +Emitted when the mouse cursor leaves the control's (and all child control's) visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. -Emitted when the mouse leaves the control's ``Rect`` area, provided its :ref:`mouse_filter` lets the event reach it. +\ **Note:** :ref:`CanvasItem.z_index` doesn't affect, which Control receives the signal. + +\ **Note:** If you want to check whether the mouse truly left the area, ignoring any top nodes, you can use code like this: + +:: + + func _on_mouse_exited(): + if not Rect2(Vector2(), size).has_point(get_local_mouse_position()): + # Not hovering over area. + +.. rst-class:: classref-item-separator ---- .. _class_Control_signal_resized: -- **resized** **(** **)** +.. rst-class:: classref-signal + +**resized**\ (\ ) :ref:`🔗` Emitted when the control changes size. +.. rst-class:: classref-item-separator + ---- .. _class_Control_signal_size_flags_changed: -- **size_flags_changed** **(** **)** +.. rst-class:: classref-signal + +**size_flags_changed**\ (\ ) :ref:`🔗` Emitted when one of the size flags changes. See :ref:`size_flags_horizontal` and :ref:`size_flags_vertical`. +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_signal_theme_changed: + +.. rst-class:: classref-signal + +**theme_changed**\ (\ ) :ref:`🔗` + +Emitted when the :ref:`NOTIFICATION_THEME_CHANGED` notification is sent. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Enumerations ------------ .. _enum_Control_FocusMode: +.. rst-class:: classref-enumeration + +enum **FocusMode**: :ref:`🔗` + .. _class_Control_constant_FOCUS_NONE: +.. rst-class:: classref-enumeration-constant + +:ref:`FocusMode` **FOCUS_NONE** = ``0`` + +The node cannot grab focus. Use with :ref:`focus_mode`. + .. _class_Control_constant_FOCUS_CLICK: +.. rst-class:: classref-enumeration-constant + +:ref:`FocusMode` **FOCUS_CLICK** = ``1`` + +The node can only grab focus on mouse clicks. Use with :ref:`focus_mode`. + .. _class_Control_constant_FOCUS_ALL: -enum **FocusMode**: +.. rst-class:: classref-enumeration-constant + +:ref:`FocusMode` **FOCUS_ALL** = ``2`` + +The node can grab focus on mouse click, using the arrows and the Tab keys on the keyboard, or using the D-pad buttons on a gamepad. Use with :ref:`focus_mode`. + +.. _class_Control_constant_FOCUS_ACCESSIBILITY: + +.. rst-class:: classref-enumeration-constant + +:ref:`FocusMode` **FOCUS_ACCESSIBILITY** = ``3`` + +The node can grab focus only when screen reader is active. Use with :ref:`focus_mode`. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_FocusBehaviorRecursive: + +.. rst-class:: classref-enumeration + +enum **FocusBehaviorRecursive**: :ref:`🔗` + +.. _class_Control_constant_FOCUS_BEHAVIOR_INHERITED: -- **FOCUS_NONE** = **0** --- The node cannot grab focus. Use with :ref:`focus_mode`. +.. rst-class:: classref-enumeration-constant -- **FOCUS_CLICK** = **1** --- The node can only grab focus on mouse clicks. Use with :ref:`focus_mode`. +:ref:`FocusBehaviorRecursive` **FOCUS_BEHAVIOR_INHERITED** = ``0`` -- **FOCUS_ALL** = **2** --- The node can grab focus on mouse click or using the arrows and the Tab keys on the keyboard. Use with :ref:`focus_mode`. +Inherits the :ref:`focus_behavior_recursive` from the parent control. If there is no parent control, this is the same as :ref:`FOCUS_BEHAVIOR_ENABLED`. + +.. _class_Control_constant_FOCUS_BEHAVIOR_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`FocusBehaviorRecursive` **FOCUS_BEHAVIOR_DISABLED** = ``1`` + +Prevents the control from getting focused. :ref:`get_focus_mode_with_override()` will return :ref:`FOCUS_NONE`. + +.. _class_Control_constant_FOCUS_BEHAVIOR_ENABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`FocusBehaviorRecursive` **FOCUS_BEHAVIOR_ENABLED** = ``2`` + +Allows the control to be focused, depending on the :ref:`focus_mode`. This can be used to ignore the parent's :ref:`focus_behavior_recursive`. :ref:`get_focus_mode_with_override()` will return the :ref:`focus_mode`. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_MouseBehaviorRecursive: + +.. rst-class:: classref-enumeration + +enum **MouseBehaviorRecursive**: :ref:`🔗` + +.. _class_Control_constant_MOUSE_BEHAVIOR_INHERITED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseBehaviorRecursive` **MOUSE_BEHAVIOR_INHERITED** = ``0`` + +Inherits the :ref:`mouse_behavior_recursive` from the parent control. If there is no parent control, this is the same as :ref:`MOUSE_BEHAVIOR_ENABLED`. + +.. _class_Control_constant_MOUSE_BEHAVIOR_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseBehaviorRecursive` **MOUSE_BEHAVIOR_DISABLED** = ``1`` + +Prevents the control from receiving mouse input. :ref:`get_mouse_filter_with_override()` will return :ref:`MOUSE_FILTER_IGNORE`. + +.. _class_Control_constant_MOUSE_BEHAVIOR_ENABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseBehaviorRecursive` **MOUSE_BEHAVIOR_ENABLED** = ``2`` + +Allows the control to be receive mouse input, depending on the :ref:`mouse_filter`. This can be used to ignore the parent's :ref:`mouse_behavior_recursive`. :ref:`get_mouse_filter_with_override()` will return the :ref:`mouse_filter`. + +.. rst-class:: classref-item-separator ---- .. _enum_Control_CursorShape: +.. rst-class:: classref-enumeration + +enum **CursorShape**: :ref:`🔗` + .. _class_Control_constant_CURSOR_ARROW: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_ARROW** = ``0`` + +Show the system's arrow mouse cursor when the user hovers the node. Use with :ref:`mouse_default_cursor_shape`. + .. _class_Control_constant_CURSOR_IBEAM: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_IBEAM** = ``1`` + +Show the system's I-beam mouse cursor when the user hovers the node. The I-beam pointer has a shape similar to "I". It tells the user they can highlight or insert text. + .. _class_Control_constant_CURSOR_POINTING_HAND: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_POINTING_HAND** = ``2`` + +Show the system's pointing hand mouse cursor when the user hovers the node. + .. _class_Control_constant_CURSOR_CROSS: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_CROSS** = ``3`` + +Show the system's cross mouse cursor when the user hovers the node. + .. _class_Control_constant_CURSOR_WAIT: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_WAIT** = ``4`` + +Show the system's wait mouse cursor when the user hovers the node. Often an hourglass. + .. _class_Control_constant_CURSOR_BUSY: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_BUSY** = ``5`` + +Show the system's busy mouse cursor when the user hovers the node. Often an arrow with a small hourglass. + .. _class_Control_constant_CURSOR_DRAG: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_DRAG** = ``6`` + +Show the system's drag mouse cursor, often a closed fist or a cross symbol, when the user hovers the node. It tells the user they're currently dragging an item, like a node in the Scene dock. + .. _class_Control_constant_CURSOR_CAN_DROP: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_CAN_DROP** = ``7`` + +Show the system's drop mouse cursor when the user hovers the node. It can be an open hand. It tells the user they can drop an item they're currently grabbing, like a node in the Scene dock. + .. _class_Control_constant_CURSOR_FORBIDDEN: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_FORBIDDEN** = ``8`` + +Show the system's forbidden mouse cursor when the user hovers the node. Often a crossed circle. + .. _class_Control_constant_CURSOR_VSIZE: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_VSIZE** = ``9`` + +Show the system's vertical resize mouse cursor when the user hovers the node. A double-headed vertical arrow. It tells the user they can resize the window or the panel vertically. + .. _class_Control_constant_CURSOR_HSIZE: +.. rst-class:: classref-enumeration-constant + +:ref:`CursorShape` **CURSOR_HSIZE** = ``10`` + +Show the system's horizontal resize mouse cursor when the user hovers the node. A double-headed horizontal arrow. It tells the user they can resize the window or the panel horizontally. + .. _class_Control_constant_CURSOR_BDIAGSIZE: -.. _class_Control_constant_CURSOR_FDIAGSIZE: +.. rst-class:: classref-enumeration-constant -.. _class_Control_constant_CURSOR_MOVE: +:ref:`CursorShape` **CURSOR_BDIAGSIZE** = ``11`` -.. _class_Control_constant_CURSOR_VSPLIT: +Show the system's window resize mouse cursor when the user hovers the node. The cursor is a double-headed arrow that goes from the bottom left to the top right. It tells the user they can resize the window or the panel both horizontally and vertically. -.. _class_Control_constant_CURSOR_HSPLIT: +.. _class_Control_constant_CURSOR_FDIAGSIZE: -.. _class_Control_constant_CURSOR_HELP: +.. rst-class:: classref-enumeration-constant -enum **CursorShape**: +:ref:`CursorShape` **CURSOR_FDIAGSIZE** = ``12`` -- **CURSOR_ARROW** = **0** --- Show the system's arrow mouse cursor when the user hovers the node. Use with :ref:`mouse_default_cursor_shape`. +Show the system's window resize mouse cursor when the user hovers the node. The cursor is a double-headed arrow that goes from the top left to the bottom right, the opposite of :ref:`CURSOR_BDIAGSIZE`. It tells the user they can resize the window or the panel both horizontally and vertically. -- **CURSOR_IBEAM** = **1** --- Show the system's I-beam mouse cursor when the user hovers the node. The I-beam pointer has a shape similar to "I". It tells the user they can highlight or insert text. +.. _class_Control_constant_CURSOR_MOVE: + +.. rst-class:: classref-enumeration-constant -- **CURSOR_POINTING_HAND** = **2** --- Show the system's pointing hand mouse cursor when the user hovers the node. +:ref:`CursorShape` **CURSOR_MOVE** = ``13`` -- **CURSOR_CROSS** = **3** --- Show the system's cross mouse cursor when the user hovers the node. +Show the system's move mouse cursor when the user hovers the node. It shows 2 double-headed arrows at a 90 degree angle. It tells the user they can move a UI element freely. -- **CURSOR_WAIT** = **4** --- Show the system's wait mouse cursor, often an hourglass, when the user hovers the node. +.. _class_Control_constant_CURSOR_VSPLIT: -- **CURSOR_BUSY** = **5** --- Show the system's busy mouse cursor when the user hovers the node. Often an hourglass. +.. rst-class:: classref-enumeration-constant -- **CURSOR_DRAG** = **6** --- Show the system's drag mouse cursor, often a closed fist or a cross symbol, when the user hovers the node. It tells the user they're currently dragging an item, like a node in the Scene dock. +:ref:`CursorShape` **CURSOR_VSPLIT** = ``14`` -- **CURSOR_CAN_DROP** = **7** --- Show the system's drop mouse cursor when the user hovers the node. It can be an open hand. It tells the user they can drop an item they're currently grabbing, like a node in the Scene dock. +Show the system's vertical split mouse cursor when the user hovers the node. On Windows, it's the same as :ref:`CURSOR_VSIZE`. -- **CURSOR_FORBIDDEN** = **8** --- Show the system's forbidden mouse cursor when the user hovers the node. Often a crossed circle. +.. _class_Control_constant_CURSOR_HSPLIT: -- **CURSOR_VSIZE** = **9** --- Show the system's vertical resize mouse cursor when the user hovers the node. A double-headed vertical arrow. It tells the user they can resize the window or the panel vertically. +.. rst-class:: classref-enumeration-constant -- **CURSOR_HSIZE** = **10** --- Show the system's horizontal resize mouse cursor when the user hovers the node. A double-headed horizontal arrow. It tells the user they can resize the window or the panel horizontally. +:ref:`CursorShape` **CURSOR_HSPLIT** = ``15`` -- **CURSOR_BDIAGSIZE** = **11** --- Show the system's window resize mouse cursor when the user hovers the node. The cursor is a double-headed arrow that goes from the bottom left to the top right. It tells the user they can resize the window or the panel both horizontally and vertically. +Show the system's horizontal split mouse cursor when the user hovers the node. On Windows, it's the same as :ref:`CURSOR_HSIZE`. -- **CURSOR_FDIAGSIZE** = **12** --- Show the system's window resize mouse cursor when the user hovers the node. The cursor is a double-headed arrow that goes from the top left to the bottom right, the opposite of :ref:`CURSOR_BDIAGSIZE`. It tells the user they can resize the window or the panel both horizontally and vertically. +.. _class_Control_constant_CURSOR_HELP: -- **CURSOR_MOVE** = **13** --- Show the system's move mouse cursor when the user hovers the node. It shows 2 double-headed arrows at a 90 degree angle. It tells the user they can move a UI element freely. +.. rst-class:: classref-enumeration-constant -- **CURSOR_VSPLIT** = **14** --- Show the system's vertical split mouse cursor when the user hovers the node. On Windows, it's the same as :ref:`CURSOR_VSIZE`. +:ref:`CursorShape` **CURSOR_HELP** = ``16`` -- **CURSOR_HSPLIT** = **15** --- Show the system's horizontal split mouse cursor when the user hovers the node. On Windows, it's the same as :ref:`CURSOR_HSIZE`. +Show the system's help mouse cursor when the user hovers the node, a question mark. -- **CURSOR_HELP** = **16** --- Show the system's help mouse cursor when the user hovers the node, a question mark. +.. rst-class:: classref-item-separator ---- .. _enum_Control_LayoutPreset: +.. rst-class:: classref-enumeration + +enum **LayoutPreset**: :ref:`🔗` + .. _class_Control_constant_PRESET_TOP_LEFT: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_TOP_LEFT** = ``0`` + +Snap all 4 anchors to the top-left of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_TOP_RIGHT: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_TOP_RIGHT** = ``1`` + +Snap all 4 anchors to the top-right of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_BOTTOM_LEFT: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_BOTTOM_LEFT** = ``2`` + +Snap all 4 anchors to the bottom-left of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_BOTTOM_RIGHT: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_BOTTOM_RIGHT** = ``3`` + +Snap all 4 anchors to the bottom-right of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_CENTER_LEFT: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_CENTER_LEFT** = ``4`` + +Snap all 4 anchors to the center of the left edge of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_CENTER_TOP: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_CENTER_TOP** = ``5`` + +Snap all 4 anchors to the center of the top edge of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_CENTER_RIGHT: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_CENTER_RIGHT** = ``6`` + +Snap all 4 anchors to the center of the right edge of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_CENTER_BOTTOM: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_CENTER_BOTTOM** = ``7`` + +Snap all 4 anchors to the center of the bottom edge of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_CENTER: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_CENTER** = ``8`` + +Snap all 4 anchors to the center of the parent control's bounds. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_LEFT_WIDE: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_LEFT_WIDE** = ``9`` + +Snap all 4 anchors to the left edge of the parent control. The left offset becomes relative to the left edge and the top offset relative to the top left corner of the node's parent. Use with :ref:`set_anchors_preset()`. + .. _class_Control_constant_PRESET_TOP_WIDE: -.. _class_Control_constant_PRESET_RIGHT_WIDE: +.. rst-class:: classref-enumeration-constant -.. _class_Control_constant_PRESET_BOTTOM_WIDE: +:ref:`LayoutPreset` **PRESET_TOP_WIDE** = ``10`` -.. _class_Control_constant_PRESET_VCENTER_WIDE: +Snap all 4 anchors to the top edge of the parent control. The left offset becomes relative to the top left corner, the top offset relative to the top edge, and the right offset relative to the top right corner of the node's parent. Use with :ref:`set_anchors_preset()`. -.. _class_Control_constant_PRESET_HCENTER_WIDE: +.. _class_Control_constant_PRESET_RIGHT_WIDE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPreset` **PRESET_RIGHT_WIDE** = ``11`` -.. _class_Control_constant_PRESET_WIDE: +Snap all 4 anchors to the right edge of the parent control. The right offset becomes relative to the right edge and the top offset relative to the top right corner of the node's parent. Use with :ref:`set_anchors_preset()`. -enum **LayoutPreset**: +.. _class_Control_constant_PRESET_BOTTOM_WIDE: -- **PRESET_TOP_LEFT** = **0** --- Snap all 4 anchors to the top-left of the parent control's bounds. Use with :ref:`set_anchors_preset`. +.. rst-class:: classref-enumeration-constant -- **PRESET_TOP_RIGHT** = **1** --- Snap all 4 anchors to the top-right of the parent control's bounds. Use with :ref:`set_anchors_preset`. +:ref:`LayoutPreset` **PRESET_BOTTOM_WIDE** = ``12`` -- **PRESET_BOTTOM_LEFT** = **2** --- Snap all 4 anchors to the bottom-left of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the bottom edge of the parent control. The left offset becomes relative to the bottom left corner, the bottom offset relative to the bottom edge, and the right offset relative to the bottom right corner of the node's parent. Use with :ref:`set_anchors_preset()`. -- **PRESET_BOTTOM_RIGHT** = **3** --- Snap all 4 anchors to the bottom-right of the parent control's bounds. Use with :ref:`set_anchors_preset`. +.. _class_Control_constant_PRESET_VCENTER_WIDE: -- **PRESET_CENTER_LEFT** = **4** --- Snap all 4 anchors to the center of the left edge of the parent control's bounds. Use with :ref:`set_anchors_preset`. +.. rst-class:: classref-enumeration-constant -- **PRESET_CENTER_TOP** = **5** --- Snap all 4 anchors to the center of the top edge of the parent control's bounds. Use with :ref:`set_anchors_preset`. +:ref:`LayoutPreset` **PRESET_VCENTER_WIDE** = ``13`` -- **PRESET_CENTER_RIGHT** = **6** --- Snap all 4 anchors to the center of the right edge of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to a vertical line that cuts the parent control in half. Use with :ref:`set_anchors_preset()`. -- **PRESET_CENTER_BOTTOM** = **7** --- Snap all 4 anchors to the center of the bottom edge of the parent control's bounds. Use with :ref:`set_anchors_preset`. +.. _class_Control_constant_PRESET_HCENTER_WIDE: -- **PRESET_CENTER** = **8** --- Snap all 4 anchors to the center of the parent control's bounds. Use with :ref:`set_anchors_preset`. +.. rst-class:: classref-enumeration-constant -- **PRESET_LEFT_WIDE** = **9** --- Snap all 4 anchors to the left edge of the parent control. The left margin becomes relative to the left edge and the top margin relative to the top left corner of the node's parent. Use with :ref:`set_anchors_preset`. +:ref:`LayoutPreset` **PRESET_HCENTER_WIDE** = ``14`` -- **PRESET_TOP_WIDE** = **10** --- Snap all 4 anchors to the top edge of the parent control. The left margin becomes relative to the top left corner, the top margin relative to the top edge, and the right margin relative to the top right corner of the node's parent. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to a horizontal line that cuts the parent control in half. Use with :ref:`set_anchors_preset()`. -- **PRESET_RIGHT_WIDE** = **11** --- Snap all 4 anchors to the right edge of the parent control. The right margin becomes relative to the right edge and the top margin relative to the top right corner of the node's parent. Use with :ref:`set_anchors_preset`. +.. _class_Control_constant_PRESET_FULL_RECT: -- **PRESET_BOTTOM_WIDE** = **12** --- Snap all 4 anchors to the bottom edge of the parent control. The left margin becomes relative to the bottom left corner, the bottom margin relative to the bottom edge, and the right margin relative to the bottom right corner of the node's parent. Use with :ref:`set_anchors_preset`. +.. rst-class:: classref-enumeration-constant -- **PRESET_VCENTER_WIDE** = **13** --- Snap all 4 anchors to a vertical line that cuts the parent control in half. Use with :ref:`set_anchors_preset`. +:ref:`LayoutPreset` **PRESET_FULL_RECT** = ``15`` -- **PRESET_HCENTER_WIDE** = **14** --- Snap all 4 anchors to a horizontal line that cuts the parent control in half. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the respective corners of the parent control. Set all 4 offsets to 0 after you applied this preset and the **Control** will fit its parent control. Use with :ref:`set_anchors_preset()`. -- **PRESET_WIDE** = **15** --- Snap all 4 anchors to the respective corners of the parent control. Set all 4 margins to 0 after you applied this preset and the ``Control`` will fit its parent control. This is equivalent to the "Full Rect" layout option in the editor. Use with :ref:`set_anchors_preset`. +.. rst-class:: classref-item-separator ---- .. _enum_Control_LayoutPresetMode: +.. rst-class:: classref-enumeration + +enum **LayoutPresetMode**: :ref:`🔗` + .. _class_Control_constant_PRESET_MODE_MINSIZE: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPresetMode` **PRESET_MODE_MINSIZE** = ``0`` + +The control will be resized to its minimum size. + .. _class_Control_constant_PRESET_MODE_KEEP_WIDTH: +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutPresetMode` **PRESET_MODE_KEEP_WIDTH** = ``1`` + +The control's width will not change. + .. _class_Control_constant_PRESET_MODE_KEEP_HEIGHT: -.. _class_Control_constant_PRESET_MODE_KEEP_SIZE: +.. rst-class:: classref-enumeration-constant -enum **LayoutPresetMode**: +:ref:`LayoutPresetMode` **PRESET_MODE_KEEP_HEIGHT** = ``2`` -- **PRESET_MODE_MINSIZE** = **0** --- The control will be resized to its minimum size. +The control's height will not change. -- **PRESET_MODE_KEEP_WIDTH** = **1** --- The control's width will not change. +.. _class_Control_constant_PRESET_MODE_KEEP_SIZE: + +.. rst-class:: classref-enumeration-constant -- **PRESET_MODE_KEEP_HEIGHT** = **2** --- The control's height will not change. +:ref:`LayoutPresetMode` **PRESET_MODE_KEEP_SIZE** = ``3`` -- **PRESET_MODE_KEEP_SIZE** = **3** --- The control's size will not change. +The control's size will not change. + +.. rst-class:: classref-item-separator ---- .. _enum_Control_SizeFlags: +.. rst-class:: classref-enumeration + +flags **SizeFlags**: :ref:`🔗` + +.. _class_Control_constant_SIZE_SHRINK_BEGIN: + +.. rst-class:: classref-enumeration-constant + +:ref:`SizeFlags` **SIZE_SHRINK_BEGIN** = ``0`` + +Tells the parent :ref:`Container` to align the node with its start, either the top or the left edge. It is mutually exclusive with :ref:`SIZE_FILL` and other shrink size flags, but can be used with :ref:`SIZE_EXPAND` in some containers. Use with :ref:`size_flags_horizontal` and :ref:`size_flags_vertical`. + +\ **Note:** Setting this flag is equal to not having any size flags. + .. _class_Control_constant_SIZE_FILL: +.. rst-class:: classref-enumeration-constant + +:ref:`SizeFlags` **SIZE_FILL** = ``1`` + +Tells the parent :ref:`Container` to expand the bounds of this node to fill all the available space without pushing any other node. It is mutually exclusive with shrink size flags. Use with :ref:`size_flags_horizontal` and :ref:`size_flags_vertical`. + .. _class_Control_constant_SIZE_EXPAND: +.. rst-class:: classref-enumeration-constant + +:ref:`SizeFlags` **SIZE_EXPAND** = ``2`` + +Tells the parent :ref:`Container` to let this node take all the available space on the axis you flag. If multiple neighboring nodes are set to expand, they'll share the space based on their stretch ratio. See :ref:`size_flags_stretch_ratio`. Use with :ref:`size_flags_horizontal` and :ref:`size_flags_vertical`. + .. _class_Control_constant_SIZE_EXPAND_FILL: +.. rst-class:: classref-enumeration-constant + +:ref:`SizeFlags` **SIZE_EXPAND_FILL** = ``3`` + +Sets the node's size flags to both fill and expand. See :ref:`SIZE_FILL` and :ref:`SIZE_EXPAND` for more information. + .. _class_Control_constant_SIZE_SHRINK_CENTER: +.. rst-class:: classref-enumeration-constant + +:ref:`SizeFlags` **SIZE_SHRINK_CENTER** = ``4`` + +Tells the parent :ref:`Container` to center the node in the available space. It is mutually exclusive with :ref:`SIZE_FILL` and other shrink size flags, but can be used with :ref:`SIZE_EXPAND` in some containers. Use with :ref:`size_flags_horizontal` and :ref:`size_flags_vertical`. + .. _class_Control_constant_SIZE_SHRINK_END: -enum **SizeFlags**: +.. rst-class:: classref-enumeration-constant + +:ref:`SizeFlags` **SIZE_SHRINK_END** = ``8`` + +Tells the parent :ref:`Container` to align the node with its end, either the bottom or the right edge. It is mutually exclusive with :ref:`SIZE_FILL` and other shrink size flags, but can be used with :ref:`SIZE_EXPAND` in some containers. Use with :ref:`size_flags_horizontal` and :ref:`size_flags_vertical`. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_MouseFilter: + +.. rst-class:: classref-enumeration + +enum **MouseFilter**: :ref:`🔗` + +.. _class_Control_constant_MOUSE_FILTER_STOP: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseFilter` **MOUSE_FILTER_STOP** = ``0`` + +The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input()`. The control will also receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls. + +.. _class_Control_constant_MOUSE_FILTER_PASS: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseFilter` **MOUSE_FILTER_PASS** = ``1`` + +The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input()`. The control will also receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. + +If this control does not handle the event, the event will propagate up to its parent control if it has one. The event is bubbled up the node hierarchy until it reaches a non-:ref:`CanvasItem`, a control with :ref:`MOUSE_FILTER_STOP`, or a :ref:`CanvasItem` with :ref:`CanvasItem.top_level` enabled. This will allow signals to fire in all controls it reaches. If no control handled it, the event will be passed to :ref:`Node._shortcut_input()` for further processing. + +.. _class_Control_constant_MOUSE_FILTER_IGNORE: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseFilter` **MOUSE_FILTER_IGNORE** = ``2`` + +The control will not receive any mouse movement input events nor mouse button input events through :ref:`_gui_input()`. The control will also not receive the :ref:`mouse_entered` nor :ref:`mouse_exited` signals. This will not block other controls from receiving these events or firing the signals. Ignored events will not be handled automatically. If a child has :ref:`MOUSE_FILTER_PASS` and an event was passed to this control, the event will further propagate up to the control's parent. + +\ **Note:** If the control has received :ref:`mouse_entered` but not :ref:`mouse_exited`, changing the :ref:`mouse_filter` to :ref:`MOUSE_FILTER_IGNORE` will cause :ref:`mouse_exited` to be emitted. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_GrowDirection: + +.. rst-class:: classref-enumeration + +enum **GrowDirection**: :ref:`🔗` + +.. _class_Control_constant_GROW_DIRECTION_BEGIN: + +.. rst-class:: classref-enumeration-constant + +:ref:`GrowDirection` **GROW_DIRECTION_BEGIN** = ``0`` + +The control will grow to the left or top to make up if its minimum size is changed to be greater than its current size on the respective axis. + +.. _class_Control_constant_GROW_DIRECTION_END: + +.. rst-class:: classref-enumeration-constant + +:ref:`GrowDirection` **GROW_DIRECTION_END** = ``1`` + +The control will grow to the right or bottom to make up if its minimum size is changed to be greater than its current size on the respective axis. + +.. _class_Control_constant_GROW_DIRECTION_BOTH: + +.. rst-class:: classref-enumeration-constant + +:ref:`GrowDirection` **GROW_DIRECTION_BOTH** = ``2`` + +The control will grow in both directions equally to make up if its minimum size is changed to be greater than its current size. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_Anchor: + +.. rst-class:: classref-enumeration + +enum **Anchor**: :ref:`🔗` + +.. _class_Control_constant_ANCHOR_BEGIN: + +.. rst-class:: classref-enumeration-constant + +:ref:`Anchor` **ANCHOR_BEGIN** = ``0`` + +Snaps one of the 4 anchor's sides to the origin of the node's ``Rect``, in the top left. Use it with one of the ``anchor_*`` member variables, like :ref:`anchor_left`. To change all 4 anchors at once, use :ref:`set_anchors_preset()`. + +.. _class_Control_constant_ANCHOR_END: + +.. rst-class:: classref-enumeration-constant + +:ref:`Anchor` **ANCHOR_END** = ``1`` + +Snaps one of the 4 anchor's sides to the end of the node's ``Rect``, in the bottom right. Use it with one of the ``anchor_*`` member variables, like :ref:`anchor_left`. To change all 4 anchors at once, use :ref:`set_anchors_preset()`. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_LayoutDirection: + +.. rst-class:: classref-enumeration + +enum **LayoutDirection**: :ref:`🔗` + +.. _class_Control_constant_LAYOUT_DIRECTION_INHERITED: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_INHERITED** = ``0`` + +Automatic layout direction, determined from the parent control layout direction. + +.. _class_Control_constant_LAYOUT_DIRECTION_APPLICATION_LOCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_APPLICATION_LOCALE** = ``1`` + +Automatic layout direction, determined from the current locale. Right-to-left layout direction is automatically used for languages that require it such as Arabic and Hebrew, but only if a valid translation file is loaded for the given language (unless said language is configured as a fallback in :ref:`ProjectSettings.internationalization/locale/fallback`). For all other languages (or if no valid translation file is found by Godot), left-to-right layout direction is used. If using :ref:`TextServerFallback` (:ref:`ProjectSettings.internationalization/rendering/text_driver`), left-to-right layout direction is always used regardless of the language. Right-to-left layout direction can also be forced using :ref:`ProjectSettings.internationalization/rendering/force_right_to_left_layout_direction`. + +.. _class_Control_constant_LAYOUT_DIRECTION_LTR: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_LTR** = ``2`` + +Left-to-right layout direction. + +.. _class_Control_constant_LAYOUT_DIRECTION_RTL: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_RTL** = ``3`` + +Right-to-left layout direction. + +.. _class_Control_constant_LAYOUT_DIRECTION_SYSTEM_LOCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_SYSTEM_LOCALE** = ``4`` + +Automatic layout direction, determined from the system locale. Right-to-left layout direction is automatically used for languages that require it such as Arabic and Hebrew, but only if a valid translation file is loaded for the given language. For all other languages (or if no valid translation file is found by Godot), left-to-right layout direction is used. If using :ref:`TextServerFallback` (:ref:`ProjectSettings.internationalization/rendering/text_driver`), left-to-right layout direction is always used regardless of the language. + +.. _class_Control_constant_LAYOUT_DIRECTION_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_MAX** = ``5`` + +Represents the size of the :ref:`LayoutDirection` enum. + +.. _class_Control_constant_LAYOUT_DIRECTION_LOCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_LOCALE** = ``1`` + +**Deprecated:** Use :ref:`LAYOUT_DIRECTION_APPLICATION_LOCALE` instead. + + + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_TextDirection: + +.. rst-class:: classref-enumeration + +enum **TextDirection**: :ref:`🔗` + +.. _class_Control_constant_TEXT_DIRECTION_INHERITED: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextDirection` **TEXT_DIRECTION_INHERITED** = ``3`` + +Text writing direction is the same as layout direction. + +.. _class_Control_constant_TEXT_DIRECTION_AUTO: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextDirection` **TEXT_DIRECTION_AUTO** = ``0`` + +Automatic text writing direction, determined from the current locale and text content. + +.. _class_Control_constant_TEXT_DIRECTION_LTR: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextDirection` **TEXT_DIRECTION_LTR** = ``1`` + +Left-to-right text writing direction. + +.. _class_Control_constant_TEXT_DIRECTION_RTL: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextDirection` **TEXT_DIRECTION_RTL** = ``2`` + +Right-to-left text writing direction. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_Control_constant_NOTIFICATION_RESIZED: + +.. rst-class:: classref-constant + +**NOTIFICATION_RESIZED** = ``40`` :ref:`🔗` + +Sent when the node changes size. Use :ref:`size` to get the new size. + +.. _class_Control_constant_NOTIFICATION_MOUSE_ENTER: + +.. rst-class:: classref-constant + +**NOTIFICATION_MOUSE_ENTER** = ``41`` :ref:`🔗` + +Sent when the mouse cursor enters the control's (or any child control's) visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** :ref:`CanvasItem.z_index` doesn't affect which Control receives the notification. + +See also :ref:`NOTIFICATION_MOUSE_ENTER_SELF`. + +.. _class_Control_constant_NOTIFICATION_MOUSE_EXIT: + +.. rst-class:: classref-constant + +**NOTIFICATION_MOUSE_EXIT** = ``42`` :ref:`🔗` + +Sent when the mouse cursor leaves the control's (and all child control's) visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** :ref:`CanvasItem.z_index` doesn't affect which Control receives the notification. + +See also :ref:`NOTIFICATION_MOUSE_EXIT_SELF`. + +.. _class_Control_constant_NOTIFICATION_MOUSE_ENTER_SELF: + +.. rst-class:: classref-constant + +**NOTIFICATION_MOUSE_ENTER_SELF** = ``60`` :ref:`🔗` + +**Experimental:** The reason this notification is sent may change in the future. + +Sent when the mouse cursor enters the control's visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** :ref:`CanvasItem.z_index` doesn't affect which Control receives the notification. + +See also :ref:`NOTIFICATION_MOUSE_ENTER`. + +.. _class_Control_constant_NOTIFICATION_MOUSE_EXIT_SELF: + +.. rst-class:: classref-constant + +**NOTIFICATION_MOUSE_EXIT_SELF** = ``61`` :ref:`🔗` + +**Experimental:** The reason this notification is sent may change in the future. + +Sent when the mouse cursor leaves the control's visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** :ref:`CanvasItem.z_index` doesn't affect which Control receives the notification. + +See also :ref:`NOTIFICATION_MOUSE_EXIT`. + +.. _class_Control_constant_NOTIFICATION_FOCUS_ENTER: + +.. rst-class:: classref-constant + +**NOTIFICATION_FOCUS_ENTER** = ``43`` :ref:`🔗` + +Sent when the node grabs focus. + +.. _class_Control_constant_NOTIFICATION_FOCUS_EXIT: + +.. rst-class:: classref-constant + +**NOTIFICATION_FOCUS_EXIT** = ``44`` :ref:`🔗` + +Sent when the node loses focus. + +.. _class_Control_constant_NOTIFICATION_THEME_CHANGED: + +.. rst-class:: classref-constant + +**NOTIFICATION_THEME_CHANGED** = ``45`` :ref:`🔗` + +Sent when the node needs to refresh its theme items. This happens in one of the following cases: + +- The :ref:`theme` property is changed on this node or any of its ancestors. + +- The :ref:`theme_type_variation` property is changed on this node. + +- One of the node's theme property overrides is changed. + +- The node enters the scene tree. + +\ **Note:** As an optimization, this notification won't be sent from changes that occur while this node is outside of the scene tree. Instead, all of the theme item updates can be applied at once when the node enters the scene tree. + +\ **Note:** This notification is received alongside :ref:`Node.NOTIFICATION_ENTER_TREE`, so if you are instantiating a scene, the child nodes will not be initialized yet. You can use it to setup theming for this node, child nodes created from script, or if you want to access child nodes added in the editor, make sure the node is ready using :ref:`Node.is_node_ready()`. + +:: + + func _notification(what): + if what == NOTIFICATION_THEME_CHANGED: + if not is_node_ready(): + await ready # Wait until ready signal. + $Label.add_theme_color_override("font_color", Color.YELLOW) + +.. _class_Control_constant_NOTIFICATION_SCROLL_BEGIN: + +.. rst-class:: classref-constant + +**NOTIFICATION_SCROLL_BEGIN** = ``47`` :ref:`🔗` + +Sent when this node is inside a :ref:`ScrollContainer` which has begun being scrolled when dragging the scrollable area *with a touch event*. This notification is *not* sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + +\ **Note:** This signal is only emitted on Android or iOS, or on desktop/web platforms when :ref:`ProjectSettings.input_devices/pointing/emulate_touch_from_mouse` is enabled. + +.. _class_Control_constant_NOTIFICATION_SCROLL_END: + +.. rst-class:: classref-constant + +**NOTIFICATION_SCROLL_END** = ``48`` :ref:`🔗` + +Sent when this node is inside a :ref:`ScrollContainer` which has stopped being scrolled when dragging the scrollable area *with a touch event*. This notification is *not* sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + +\ **Note:** This signal is only emitted on Android or iOS, or on desktop/web platforms when :ref:`ProjectSettings.input_devices/pointing/emulate_touch_from_mouse` is enabled. + +.. _class_Control_constant_NOTIFICATION_LAYOUT_DIRECTION_CHANGED: + +.. rst-class:: classref-constant + +**NOTIFICATION_LAYOUT_DIRECTION_CHANGED** = ``49`` :ref:`🔗` + +Sent when the control layout direction is changed from LTR or RTL or vice versa. This notification is propagated to child Control nodes as result of a change to :ref:`layout_direction`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_Control_property_accessibility_controls_nodes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`NodePath`\] **accessibility_controls_nodes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_controls_nodes**\ (\ value\: :ref:`Array`\[:ref:`NodePath`\]\ ) +- :ref:`Array`\[:ref:`NodePath`\] **get_accessibility_controls_nodes**\ (\ ) + +The paths to the nodes which are controlled by this node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_described_by_nodes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`NodePath`\] **accessibility_described_by_nodes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_described_by_nodes**\ (\ value\: :ref:`Array`\[:ref:`NodePath`\]\ ) +- :ref:`Array`\[:ref:`NodePath`\] **get_accessibility_described_by_nodes**\ (\ ) + +The paths to the nodes which are describing this node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_description: + +.. rst-class:: classref-property + +:ref:`String` **accessibility_description** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_description**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_accessibility_description**\ (\ ) + +The human-readable node description that is reported to assistive apps. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_flow_to_nodes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`NodePath`\] **accessibility_flow_to_nodes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_flow_to_nodes**\ (\ value\: :ref:`Array`\[:ref:`NodePath`\]\ ) +- :ref:`Array`\[:ref:`NodePath`\] **get_accessibility_flow_to_nodes**\ (\ ) + +The paths to the nodes which this node flows into. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_labeled_by_nodes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`NodePath`\] **accessibility_labeled_by_nodes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_labeled_by_nodes**\ (\ value\: :ref:`Array`\[:ref:`NodePath`\]\ ) +- :ref:`Array`\[:ref:`NodePath`\] **get_accessibility_labeled_by_nodes**\ (\ ) + +The paths to the nodes which label this node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_live: + +.. rst-class:: classref-property + +:ref:`AccessibilityLiveMode` **accessibility_live** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_live**\ (\ value\: :ref:`AccessibilityLiveMode`\ ) +- :ref:`AccessibilityLiveMode` **get_accessibility_live**\ (\ ) + +The mode with which a live region updates. A live region is a :ref:`Node` that is updated as a result of an external event when the user's focus may be elsewhere. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_name: + +.. rst-class:: classref-property + +:ref:`String` **accessibility_name** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_name**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_accessibility_name**\ (\ ) + +The human-readable node name that is reported to assistive apps. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_anchor_bottom: + +.. rst-class:: classref-property + +:ref:`float` **anchor_bottom** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`float` **get_anchor**\ (\ side\: :ref:`Side`\ ) |const| + +Anchors the bottom edge of the node to the origin, the center, or the end of its parent control. It changes how the bottom offset updates when the node moves or changes size. You can use one of the :ref:`Anchor` constants for convenience. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_anchor_left: + +.. rst-class:: classref-property + +:ref:`float` **anchor_left** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`float` **get_anchor**\ (\ side\: :ref:`Side`\ ) |const| + +Anchors the left edge of the node to the origin, the center or the end of its parent control. It changes how the left offset updates when the node moves or changes size. You can use one of the :ref:`Anchor` constants for convenience. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_anchor_right: + +.. rst-class:: classref-property + +:ref:`float` **anchor_right** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`float` **get_anchor**\ (\ side\: :ref:`Side`\ ) |const| + +Anchors the right edge of the node to the origin, the center or the end of its parent control. It changes how the right offset updates when the node moves or changes size. You can use one of the :ref:`Anchor` constants for convenience. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_anchor_top: + +.. rst-class:: classref-property + +:ref:`float` **anchor_top** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`float` **get_anchor**\ (\ side\: :ref:`Side`\ ) |const| + +Anchors the top edge of the node to the origin, the center or the end of its parent control. It changes how the top offset updates when the node moves or changes size. You can use one of the :ref:`Anchor` constants for convenience. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_auto_translate: + +.. rst-class:: classref-property + +:ref:`bool` **auto_translate** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_translate**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_auto_translating**\ (\ ) + +**Deprecated:** Use :ref:`Node.auto_translate_mode` and :ref:`Node.can_auto_translate()` instead. + +Toggles if any text should automatically change to its translated version depending on the current locale. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_clip_contents: + +.. rst-class:: classref-property + +:ref:`bool` **clip_contents** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_clip_contents**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_clipping_contents**\ (\ ) + +Enables whether rendering of :ref:`CanvasItem` based children should be clipped to this control's rectangle. If ``true``, parts of a child which would be visibly outside of this control's rectangle will not be rendered and won't receive input. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_custom_minimum_size: + +.. rst-class:: classref-property + +:ref:`Vector2` **custom_minimum_size** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_custom_minimum_size**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_custom_minimum_size**\ (\ ) + +The minimum size of the node's bounding rectangle. If you set it to a value greater than ``(0, 0)``, the node's bounding rectangle will always have at least this size. Note that **Control** nodes have their internal minimum size returned by :ref:`get_minimum_size()`. It depends on the control's contents, like text, textures, or style boxes. The actual minimum size is the maximum value of this property and the internal minimum size (see :ref:`get_combined_minimum_size()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_behavior_recursive: + +.. rst-class:: classref-property + +:ref:`FocusBehaviorRecursive` **focus_behavior_recursive** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_behavior_recursive**\ (\ value\: :ref:`FocusBehaviorRecursive`\ ) +- :ref:`FocusBehaviorRecursive` **get_focus_behavior_recursive**\ (\ ) + +Determines which controls can be focused together with :ref:`focus_mode`. See :ref:`get_focus_mode_with_override()`. Since the default behavior is :ref:`FOCUS_BEHAVIOR_INHERITED`, this can be used to prevent all children controls from getting focused. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_mode: + +.. rst-class:: classref-property + +:ref:`FocusMode` **focus_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_mode**\ (\ value\: :ref:`FocusMode`\ ) +- :ref:`FocusMode` **get_focus_mode**\ (\ ) + +Determines which controls can be focused. Only one control can be focused at a time, and the focused control will receive keyboard, gamepad, and mouse events in :ref:`_gui_input()`. Use :ref:`get_focus_mode_with_override()` to determine if a control can grab focus, since :ref:`focus_behavior_recursive` also affects it. See also :ref:`grab_focus()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_neighbor_bottom: + +.. rst-class:: classref-property + +:ref:`NodePath` **focus_neighbor_bottom** = ``NodePath("")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_neighbor**\ (\ side\: :ref:`Side`, neighbor\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_focus_neighbor**\ (\ side\: :ref:`Side`\ ) |const| + +Tells Godot which node it should give focus to if the user presses the down arrow on the keyboard or down on a gamepad by default. You can change the key by editing the :ref:`ProjectSettings.input/ui_down` input action. The node must be a **Control**. If this property is not set, Godot will give focus to the closest **Control** to the bottom of this one. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_neighbor_left: + +.. rst-class:: classref-property + +:ref:`NodePath` **focus_neighbor_left** = ``NodePath("")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_neighbor**\ (\ side\: :ref:`Side`, neighbor\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_focus_neighbor**\ (\ side\: :ref:`Side`\ ) |const| + +Tells Godot which node it should give focus to if the user presses the left arrow on the keyboard or left on a gamepad by default. You can change the key by editing the :ref:`ProjectSettings.input/ui_left` input action. The node must be a **Control**. If this property is not set, Godot will give focus to the closest **Control** to the left of this one. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_neighbor_right: + +.. rst-class:: classref-property + +:ref:`NodePath` **focus_neighbor_right** = ``NodePath("")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_neighbor**\ (\ side\: :ref:`Side`, neighbor\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_focus_neighbor**\ (\ side\: :ref:`Side`\ ) |const| + +Tells Godot which node it should give focus to if the user presses the right arrow on the keyboard or right on a gamepad by default. You can change the key by editing the :ref:`ProjectSettings.input/ui_right` input action. The node must be a **Control**. If this property is not set, Godot will give focus to the closest **Control** to the right of this one. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_neighbor_top: + +.. rst-class:: classref-property + +:ref:`NodePath` **focus_neighbor_top** = ``NodePath("")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_neighbor**\ (\ side\: :ref:`Side`, neighbor\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_focus_neighbor**\ (\ side\: :ref:`Side`\ ) |const| + +Tells Godot which node it should give focus to if the user presses the top arrow on the keyboard or top on a gamepad by default. You can change the key by editing the :ref:`ProjectSettings.input/ui_up` input action. The node must be a **Control**. If this property is not set, Godot will give focus to the closest **Control** to the top of this one. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_next: + +.. rst-class:: classref-property + +:ref:`NodePath` **focus_next** = ``NodePath("")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_next**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_focus_next**\ (\ ) + +Tells Godot which node it should give focus to if the user presses :kbd:`Tab` on a keyboard by default. You can change the key by editing the :ref:`ProjectSettings.input/ui_focus_next` input action. + +If this property is not set, Godot will select a "best guess" based on surrounding nodes in the scene tree. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_previous: + +.. rst-class:: classref-property + +:ref:`NodePath` **focus_previous** = ``NodePath("")`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_previous**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_focus_previous**\ (\ ) + +Tells Godot which node it should give focus to if the user presses :kbd:`Shift + Tab` on a keyboard by default. You can change the key by editing the :ref:`ProjectSettings.input/ui_focus_prev` input action. + +If this property is not set, Godot will select a "best guess" based on surrounding nodes in the scene tree. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_global_position: + +.. rst-class:: classref-property + +:ref:`Vector2` **global_position** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`Vector2` **get_global_position**\ (\ ) + +The node's global position, relative to the world (usually to the :ref:`CanvasLayer`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_grow_horizontal: + +.. rst-class:: classref-property + +:ref:`GrowDirection` **grow_horizontal** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_h_grow_direction**\ (\ value\: :ref:`GrowDirection`\ ) +- :ref:`GrowDirection` **get_h_grow_direction**\ (\ ) + +Controls the direction on the horizontal axis in which the control should grow if its horizontal minimum size is changed to be greater than its current size, as the control always has to be at least the minimum size. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_grow_vertical: + +.. rst-class:: classref-property + +:ref:`GrowDirection` **grow_vertical** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_v_grow_direction**\ (\ value\: :ref:`GrowDirection`\ ) +- :ref:`GrowDirection` **get_v_grow_direction**\ (\ ) + +Controls the direction on the vertical axis in which the control should grow if its vertical minimum size is changed to be greater than its current size, as the control always has to be at least the minimum size. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_layout_direction: + +.. rst-class:: classref-property + +:ref:`LayoutDirection` **layout_direction** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_layout_direction**\ (\ value\: :ref:`LayoutDirection`\ ) +- :ref:`LayoutDirection` **get_layout_direction**\ (\ ) + +Controls layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew). See also :ref:`is_layout_rtl()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_localize_numeral_system: + +.. rst-class:: classref-property + +:ref:`bool` **localize_numeral_system** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_localize_numeral_system**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_localizing_numeral_system**\ (\ ) + +If ``true``, automatically converts code line numbers, list indices, :ref:`SpinBox` and :ref:`ProgressBar` values from the Western Arabic (0..9) to the numeral systems used in current locale. + +\ **Note:** Numbers within the text are not automatically converted, it can be done manually, using :ref:`TextServer.format_number()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_mouse_behavior_recursive: + +.. rst-class:: classref-property + +:ref:`MouseBehaviorRecursive` **mouse_behavior_recursive** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mouse_behavior_recursive**\ (\ value\: :ref:`MouseBehaviorRecursive`\ ) +- :ref:`MouseBehaviorRecursive` **get_mouse_behavior_recursive**\ (\ ) + +Determines which controls can receive mouse input together with :ref:`mouse_filter`. See :ref:`get_mouse_filter_with_override()`. Since the default behavior is :ref:`MOUSE_BEHAVIOR_INHERITED`, this can be used to prevent all children controls from receiving mouse input. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_mouse_default_cursor_shape: + +.. rst-class:: classref-property + +:ref:`CursorShape` **mouse_default_cursor_shape** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_default_cursor_shape**\ (\ value\: :ref:`CursorShape`\ ) +- :ref:`CursorShape` **get_default_cursor_shape**\ (\ ) + +The default cursor shape for this control. Useful for Godot plugins and applications or games that use the system's mouse cursors. + +\ **Note:** On Linux, shapes may vary depending on the cursor theme of the system. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_mouse_filter: + +.. rst-class:: classref-property + +:ref:`MouseFilter` **mouse_filter** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mouse_filter**\ (\ value\: :ref:`MouseFilter`\ ) +- :ref:`MouseFilter` **get_mouse_filter**\ (\ ) + +Determines which controls will be able to receive mouse button input events through :ref:`_gui_input()` and the :ref:`mouse_entered`, and :ref:`mouse_exited` signals. Also determines how these events should be propagated. See the constants to learn what each does. Use :ref:`get_mouse_filter_with_override()` to determine if a control can receive mouse input, since :ref:`mouse_behavior_recursive` also affects it. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_mouse_force_pass_scroll_events: + +.. rst-class:: classref-property + +:ref:`bool` **mouse_force_pass_scroll_events** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_force_pass_scroll_events**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_force_pass_scroll_events**\ (\ ) + +When enabled, scroll wheel events processed by :ref:`_gui_input()` will be passed to the parent control even if :ref:`mouse_filter` is set to :ref:`MOUSE_FILTER_STOP`. + +You should disable it on the root of your UI if you do not want scroll events to go to the :ref:`Node._unhandled_input()` processing. + +\ **Note:** Because this property defaults to ``true``, this allows nested scrollable containers to work out of the box. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_offset_bottom: + +.. rst-class:: classref-property + +:ref:`float` **offset_bottom** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_offset**\ (\ side\: :ref:`Side`, offset\: :ref:`float`\ ) +- :ref:`float` **get_offset**\ (\ offset\: :ref:`Side`\ ) |const| + +Distance between the node's bottom edge and its parent control, based on :ref:`anchor_bottom`. + +Offsets are often controlled by one or multiple parent :ref:`Container` nodes, so you should not modify them manually if your node is a direct child of a :ref:`Container`. Offsets update automatically when you move or resize the node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_offset_left: + +.. rst-class:: classref-property + +:ref:`float` **offset_left** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_offset**\ (\ side\: :ref:`Side`, offset\: :ref:`float`\ ) +- :ref:`float` **get_offset**\ (\ offset\: :ref:`Side`\ ) |const| + +Distance between the node's left edge and its parent control, based on :ref:`anchor_left`. + +Offsets are often controlled by one or multiple parent :ref:`Container` nodes, so you should not modify them manually if your node is a direct child of a :ref:`Container`. Offsets update automatically when you move or resize the node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_offset_right: + +.. rst-class:: classref-property + +:ref:`float` **offset_right** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_offset**\ (\ side\: :ref:`Side`, offset\: :ref:`float`\ ) +- :ref:`float` **get_offset**\ (\ offset\: :ref:`Side`\ ) |const| + +Distance between the node's right edge and its parent control, based on :ref:`anchor_right`. + +Offsets are often controlled by one or multiple parent :ref:`Container` nodes, so you should not modify them manually if your node is a direct child of a :ref:`Container`. Offsets update automatically when you move or resize the node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_offset_top: + +.. rst-class:: classref-property + +:ref:`float` **offset_top** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_offset**\ (\ side\: :ref:`Side`, offset\: :ref:`float`\ ) +- :ref:`float` **get_offset**\ (\ offset\: :ref:`Side`\ ) |const| + +Distance between the node's top edge and its parent control, based on :ref:`anchor_top`. + +Offsets are often controlled by one or multiple parent :ref:`Container` nodes, so you should not modify them manually if your node is a direct child of a :ref:`Container`. Offsets update automatically when you move or resize the node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_pivot_offset: + +.. rst-class:: classref-property + +:ref:`Vector2` **pivot_offset** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pivot_offset**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_pivot_offset**\ (\ ) + +By default, the node's pivot is its top-left corner. When you change its :ref:`rotation` or :ref:`scale`, it will rotate or scale around this pivot. + +The actual offset is the combined value of this property and :ref:`pivot_offset_ratio`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_pivot_offset_ratio: + +.. rst-class:: classref-property + +:ref:`Vector2` **pivot_offset_ratio** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pivot_offset_ratio**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_pivot_offset_ratio**\ (\ ) + +Same as :ref:`pivot_offset`, but expressed as uniform vector, where ``Vector2(0, 0)`` is the top-left corner of this control, and ``Vector2(1, 1)`` is its bottom-right corner. Set this property to ``Vector2(0.5, 0.5)`` to pivot around this control's center. + +The actual offset is the combined value of this property and :ref:`pivot_offset`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_position: + +.. rst-class:: classref-property + +:ref:`Vector2` **position** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`Vector2` **get_position**\ (\ ) + +The node's position, relative to its containing node. It corresponds to the rectangle's top-left corner. The property is not affected by :ref:`pivot_offset`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_rotation: + +.. rst-class:: classref-property + +:ref:`float` **rotation** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_rotation**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_rotation**\ (\ ) + +The node's rotation around its pivot, in radians. See :ref:`pivot_offset` to change the pivot's position. + +\ **Note:** This property is edited in the inspector in degrees. If you want to use degrees in a script, use :ref:`rotation_degrees`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_rotation_degrees: + +.. rst-class:: classref-property + +:ref:`float` **rotation_degrees** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_rotation_degrees**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_rotation_degrees**\ (\ ) + +Helper property to access :ref:`rotation` in degrees instead of radians. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_scale: + +.. rst-class:: classref-property + +:ref:`Vector2` **scale** = ``Vector2(1, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_scale**\ (\ value\: :ref:`Vector2`\ ) +- :ref:`Vector2` **get_scale**\ (\ ) + +The node's scale, relative to its :ref:`size`. Change this property to scale the node around its :ref:`pivot_offset`. The Control's tooltip will also scale according to this value. + +\ **Note:** This property is mainly intended to be used for animation purposes. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the :doc:`documentation <../tutorials/rendering/multiple_resolutions>` instead of scaling Controls individually. + +\ **Note:** :ref:`FontFile.oversampling` does *not* take **Control** :ref:`scale` into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling :ref:`ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field` (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, :ref:`SystemFont.multichannel_signed_distance_field` can be enabled in the inspector. + +\ **Note:** If the Control node is a child of a :ref:`Container` node, the scale will be reset to ``Vector2(1, 1)`` when the scene is instantiated. To set the Control's scale when it's instantiated, wait for one frame using ``await get_tree().process_frame`` then set its :ref:`scale` property. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_shortcut_context: + +.. rst-class:: classref-property + +:ref:`Node` **shortcut_context** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_shortcut_context**\ (\ value\: :ref:`Node`\ ) +- :ref:`Node` **get_shortcut_context**\ (\ ) + +The :ref:`Node` which must be a parent of the focused **Control** for the shortcut to be activated. If ``null``, the shortcut can be activated when any control is focused (a global shortcut). This allows shortcuts to be accepted only when the user has a certain area of the GUI focused. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_size: + +.. rst-class:: classref-property + +:ref:`Vector2` **size** = ``Vector2(0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`Vector2` **get_size**\ (\ ) + +The size of the node's bounding rectangle, in the node's coordinate system. :ref:`Container` nodes update this property automatically. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_size_flags_horizontal: + +.. rst-class:: classref-property + +|bitfield|\[:ref:`SizeFlags`\] **size_flags_horizontal** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_h_size_flags**\ (\ value\: |bitfield|\[:ref:`SizeFlags`\]\ ) +- |bitfield|\[:ref:`SizeFlags`\] **get_h_size_flags**\ (\ ) + +Tells the parent :ref:`Container` nodes how they should resize and place the node on the X axis. Use a combination of the :ref:`SizeFlags` constants to change the flags. See the constants to learn what each does. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_size_flags_stretch_ratio: + +.. rst-class:: classref-property + +:ref:`float` **size_flags_stretch_ratio** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stretch_ratio**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_stretch_ratio**\ (\ ) + +If the node and at least one of its neighbors uses the :ref:`SIZE_EXPAND` size flag, the parent :ref:`Container` will let it take more or less space depending on this property. If this node has a stretch ratio of 2 and its neighbor a ratio of 1, this node will take two thirds of the available space. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_size_flags_vertical: + +.. rst-class:: classref-property + +|bitfield|\[:ref:`SizeFlags`\] **size_flags_vertical** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_v_size_flags**\ (\ value\: |bitfield|\[:ref:`SizeFlags`\]\ ) +- |bitfield|\[:ref:`SizeFlags`\] **get_v_size_flags**\ (\ ) + +Tells the parent :ref:`Container` nodes how they should resize and place the node on the Y axis. Use a combination of the :ref:`SizeFlags` constants to change the flags. See the constants to learn what each does. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_theme: + +.. rst-class:: classref-property + +:ref:`Theme` **theme** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_theme**\ (\ value\: :ref:`Theme`\ ) +- :ref:`Theme` **get_theme**\ (\ ) + +The :ref:`Theme` resource this node and all its **Control** and :ref:`Window` children use. If a child node has its own :ref:`Theme` resource set, theme items are merged with child's definitions having higher priority. + +\ **Note:** :ref:`Window` styles will have no effect unless the window is embedded. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_theme_type_variation: + +.. rst-class:: classref-property + +:ref:`StringName` **theme_type_variation** = ``&""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_theme_type_variation**\ (\ value\: :ref:`StringName`\ ) +- :ref:`StringName` **get_theme_type_variation**\ (\ ) + +The name of a theme type variation used by this **Control** to look up its own theme items. When empty, the class name of the node is used (e.g. ``Button`` for the :ref:`Button` control), as well as the class names of all parent classes (in order of inheritance). + +When set, this property gives the highest priority to the type of the specified name. This type can in turn extend another type, forming a dependency chain. See :ref:`Theme.set_type_variation()`. If the theme item cannot be found using this type or its base types, lookup falls back on the class names. + +\ **Note:** To look up **Control**'s own items use various ``get_theme_*`` methods without specifying ``theme_type``. + +\ **Note:** Theme items are looked for in the tree order, from branch to root, where each **Control** node is checked for its :ref:`theme` property. The earliest match against any type/class name is returned. The project-level Theme and the default Theme are checked last. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_tooltip_auto_translate_mode: + +.. rst-class:: classref-property + +:ref:`AutoTranslateMode` **tooltip_auto_translate_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_tooltip_auto_translate_mode**\ (\ value\: :ref:`AutoTranslateMode`\ ) +- :ref:`AutoTranslateMode` **get_tooltip_auto_translate_mode**\ (\ ) + +Defines if tooltip text should automatically change to its translated version depending on the current locale. Uses the same auto translate mode as this control when set to :ref:`Node.AUTO_TRANSLATE_MODE_INHERIT`. + +\ **Note:** Tooltips customized using :ref:`_make_custom_tooltip()` do not use this auto translate mode automatically. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_tooltip_text: + +.. rst-class:: classref-property + +:ref:`String` **tooltip_text** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_tooltip_text**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_tooltip_text**\ (\ ) + +The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the :ref:`mouse_filter` property is not :ref:`MOUSE_FILTER_IGNORE`. The time required for the tooltip to appear can be changed with the :ref:`ProjectSettings.gui/timers/tooltip_delay_sec` setting. + +This string is the default return value of :ref:`get_tooltip()`. Override :ref:`_get_tooltip()` to generate tooltip text dynamically. Override :ref:`_make_custom_tooltip()` to customize the tooltip interface and behavior. + +The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding :ref:`_make_custom_tooltip()`. The default tooltip includes a :ref:`PopupPanel` and :ref:`Label` whose theme properties can be customized using :ref:`Theme` methods with the ``"TooltipPanel"`` and ``"TooltipLabel"`` respectively. For example: + + +.. tabs:: + + .. code-tab:: gdscript + + var style_box = StyleBoxFlat.new() + style_box.set_bg_color(Color(1, 1, 0)) + style_box.set_border_width_all(2) + # We assume here that the `theme` property has been assigned a custom Theme beforehand. + theme.set_stylebox("panel", "TooltipPanel", style_box) + theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1)) + + .. code-tab:: csharp + + var styleBox = new StyleBoxFlat(); + styleBox.SetBgColor(new Color(1, 1, 0)); + styleBox.SetBorderWidthAll(2); + // We assume here that the `Theme` property has been assigned a custom Theme beforehand. + Theme.SetStyleBox("panel", "TooltipPanel", styleBox); + Theme.SetColor("font_color", "TooltipLabel", new Color(0, 1, 1)); + + + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_Control_private_method__accessibility_get_contextual_info: + +.. rst-class:: classref-method + +:ref:`String` **_accessibility_get_contextual_info**\ (\ ) |virtual| |const| :ref:`🔗` + +Return the description of the keyboard shortcuts and other contextual help for this control. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__can_drop_data: + +.. rst-class:: classref-method + +:ref:`bool` **_can_drop_data**\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| |const| :ref:`🔗` + +Godot calls this method to test if ``data`` from a control's :ref:`_get_drag_data()` can be dropped at ``at_position``. ``at_position`` is local to this control. + +This method should only be used to test the data. Process the data in :ref:`_drop_data()`. + +\ **Note:** If the drag was initiated by a keyboard shortcut or :ref:`accessibility_drag()`, ``at_position`` is set to :ref:`Vector2.INF`, and the currently selected item/text position should be used as the drop position. + + +.. tabs:: + + .. code-tab:: gdscript + + func _can_drop_data(position, data): + # Check position if it is relevant to you + # Otherwise, just check data + return typeof(data) == TYPE_DICTIONARY and data.has("expected") + + .. code-tab:: csharp + + public override bool _CanDropData(Vector2 atPosition, Variant data) + { + // Check position if it is relevant to you + // Otherwise, just check data + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("expected"); + } + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__drop_data: + +.. rst-class:: classref-method + +|void| **_drop_data**\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| :ref:`🔗` + +Godot calls this method to pass you the ``data`` from a control's :ref:`_get_drag_data()` result. Godot first calls :ref:`_can_drop_data()` to test if ``data`` is allowed to drop at ``at_position`` where ``at_position`` is local to this control. + +\ **Note:** If the drag was initiated by a keyboard shortcut or :ref:`accessibility_drag()`, ``at_position`` is set to :ref:`Vector2.INF`, and the currently selected item/text position should be used as the drop position. + + +.. tabs:: + + .. code-tab:: gdscript + + func _can_drop_data(position, data): + return typeof(data) == TYPE_DICTIONARY and data.has("color") + + func _drop_data(position, data): + var color = data["color"] + + .. code-tab:: csharp + + public override bool _CanDropData(Vector2 atPosition, Variant data) + { + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("color"); + } + + public override void _DropData(Vector2 atPosition, Variant data) + { + Color color = data.AsGodotDictionary()["color"].AsColor(); + } + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__get_accessibility_container_name: + +.. rst-class:: classref-method + +:ref:`String` **_get_accessibility_container_name**\ (\ node\: :ref:`Node`\ ) |virtual| |const| :ref:`🔗` + +Override this method to return a human-readable description of the position of the child ``node`` in the custom container, added to the :ref:`accessibility_name`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__get_drag_data: + +.. rst-class:: classref-method + +:ref:`Variant` **_get_drag_data**\ (\ at_position\: :ref:`Vector2`\ ) |virtual| :ref:`🔗` + +Godot calls this method to get data that can be dragged and dropped onto controls that expect drop data. Returns ``null`` if there is no data to drag. Controls that want to receive drop data should implement :ref:`_can_drop_data()` and :ref:`_drop_data()`. ``at_position`` is local to this control. Drag may be forced with :ref:`force_drag()`. + +A preview that will follow the mouse that should represent the data can be set with :ref:`set_drag_preview()`. A good time to set the preview is in this method. + +\ **Note:** If the drag was initiated by a keyboard shortcut or :ref:`accessibility_drag()`, ``at_position`` is set to :ref:`Vector2.INF`, and the currently selected item/text position should be used as the drag position. + + +.. tabs:: + + .. code-tab:: gdscript + + func _get_drag_data(position): + var mydata = make_data() # This is your custom method generating the drag data. + set_drag_preview(make_preview(mydata)) # This is your custom method generating the preview of the drag data. + return mydata + + .. code-tab:: csharp + + public override Variant _GetDragData(Vector2 atPosition) + { + var myData = MakeData(); // This is your custom method generating the drag data. + SetDragPreview(MakePreview(myData)); // This is your custom method generating the preview of the drag data. + return myData; + } + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__get_minimum_size: + +.. rst-class:: classref-method + +:ref:`Vector2` **_get_minimum_size**\ (\ ) |virtual| |const| :ref:`🔗` + +Virtual method to be implemented by the user. Returns the minimum size for this control. Alternative to :ref:`custom_minimum_size` for controlling minimum size via code. The actual minimum size will be the max value of these two (in each axis separately). + +If not overridden, defaults to :ref:`Vector2.ZERO`. + +\ **Note:** This method will not be called when the script is attached to a **Control** node that already overrides its minimum size (e.g. :ref:`Label`, :ref:`Button`, :ref:`PanelContainer` etc.). It can only be used with most basic GUI nodes, like **Control**, :ref:`Container`, :ref:`Panel` etc. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__get_tooltip: + +.. rst-class:: classref-method + +:ref:`String` **_get_tooltip**\ (\ at_position\: :ref:`Vector2`\ ) |virtual| |const| :ref:`🔗` + +Virtual method to be implemented by the user. Returns the tooltip text for the position ``at_position`` in control's local coordinates, which will typically appear when the cursor is resting over this control. See :ref:`get_tooltip()`. + +\ **Note:** If this method returns an empty :ref:`String` and :ref:`_make_custom_tooltip()` is not overridden, no tooltip is displayed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__gui_input: + +.. rst-class:: classref-method + +|void| **_gui_input**\ (\ event\: :ref:`InputEvent`\ ) |virtual| :ref:`🔗` + +Virtual method to be implemented by the user. Override this method to handle and accept inputs on UI elements. See also :ref:`accept_event()`. + +\ **Example:** Click on the control to print a message: + + +.. tabs:: + + .. code-tab:: gdscript + + func _gui_input(event): + if event is InputEventMouseButton: + if event.button_index == MOUSE_BUTTON_LEFT and event.pressed: + print("I've been clicked D:") + + .. code-tab:: csharp + + public override void _GuiInput(InputEvent @event) + { + if (@event is InputEventMouseButton mb) + { + if (mb.ButtonIndex == MouseButton.Left && mb.Pressed) + { + GD.Print("I've been clicked D:"); + } + } + } + + + +If the ``event`` inherits :ref:`InputEventMouse`, this method will **not** be called when: + +- the control's :ref:`mouse_filter` is set to :ref:`MOUSE_FILTER_IGNORE`; + +- the control is obstructed by another control on top, that doesn't have :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_IGNORE`; + +- the control's parent has :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_STOP` or has accepted the event; + +- the control's parent has :ref:`clip_contents` enabled and the ``event``'s position is outside the parent's rectangle; + +- the ``event``'s position is outside the control (see :ref:`_has_point()`). + +\ **Note:** The ``event``'s position is relative to this control's origin. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__has_point: + +.. rst-class:: classref-method + +:ref:`bool` **_has_point**\ (\ point\: :ref:`Vector2`\ ) |virtual| |const| :ref:`🔗` + +Virtual method to be implemented by the user. Returns whether the given ``point`` is inside this control. + +If not overridden, default behavior is checking if the point is within control's Rect. + +\ **Note:** If you want to check if a point is inside the control, you can use ``Rect2(Vector2.ZERO, size).has_point(point)``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__make_custom_tooltip: + +.. rst-class:: classref-method + +:ref:`Object` **_make_custom_tooltip**\ (\ for_text\: :ref:`String`\ ) |virtual| |const| :ref:`🔗` + +Virtual method to be implemented by the user. Returns a **Control** node that should be used as a tooltip instead of the default one. ``for_text`` is the return value of :ref:`get_tooltip()`. + +The returned node must be of type **Control** or Control-derived. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance (if you want to use a pre-existing node from your scene tree, you can duplicate it and pass the duplicated instance). When ``null`` or a non-Control node is returned, the default tooltip will be used instead. + +The returned node will be added as child to a :ref:`PopupPanel`, so you should only provide the contents of that panel. That :ref:`PopupPanel` can be themed using :ref:`Theme.set_stylebox()` for the type ``"TooltipPanel"`` (see :ref:`tooltip_text` for an example). + +\ **Note:** The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its :ref:`custom_minimum_size` to some non-zero value. + +\ **Note:** The node (and any relevant children) should have their :ref:`CanvasItem.visible` set to ``true`` when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. + +\ **Note:** If overridden, this method is called even if :ref:`get_tooltip()` returns an empty string. When this happens with the default tooltip, it is not displayed. To copy this behavior, return ``null`` in this method when ``for_text`` is empty. + +\ **Example:** Use a constructed node as a tooltip: + + +.. tabs:: + + .. code-tab:: gdscript + + func _make_custom_tooltip(for_text): + var label = Label.new() + label.text = for_text + return label + + .. code-tab:: csharp + + public override Control _MakeCustomTooltip(string forText) + { + var label = new Label(); + label.Text = forText; + return label; + } + + + +\ **Example:** Use a scene instance as a tooltip: + + +.. tabs:: + + .. code-tab:: gdscript + + func _make_custom_tooltip(for_text): + var tooltip = preload("res://some_tooltip_scene.tscn").instantiate() + tooltip.get_node("Label").text = for_text + return tooltip + + .. code-tab:: csharp + + public override Control _MakeCustomTooltip(string forText) + { + Node tooltip = ResourceLoader.Load("res://some_tooltip_scene.tscn").Instantiate(); + tooltip.GetNode