Skip to content

Commit

Permalink
Merge pull request #36 from Spartan322/merge/4895db1
Browse files Browse the repository at this point in the history 
Merge commit godotengine/godot-docs@4895db1
  • Loading branch information
@Spartan322
Spartan322 authored Oct 21, 2024
2 parents 52e071d + 5386dc0 commit 649a398
Show file tree
Hide file tree
Showing 44 changed files with 548 additions and 533 deletions.
12 changes: 6 additions & 6 deletions _tools/redirects/redirects.csv
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,13 +108,13 @@ source,destination
/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/animation.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/lights.html
/getting_started/workflow/assets/escn_exporter/material.html,/tutorials/assets_pipeline/escn_exporter/material.html
/getting_started/workflow/assets/escn_exporter/mesh.html,/tutorials/assets_pipeline/escn_exporter/mesh.html
/getting_started/workflow/assets/escn_exporter/physics.html,/tutorials/assets_pipeline/escn_exporter/physics.html
/getting_started/workflow/assets/escn_exporter/skeleton.html,/tutorials/assets_pipeline/escn_exporter/skeleton.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
Expand Down
45 changes: 18 additions & 27 deletions contributing/development/compiling/compiling_for_ios.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,6 @@ Requirements
Xcode and need to install iOS support, go to *Xcode -> Settings... -> Platforms*.
- Go to *Xcode -> Settings... -> Locations -> Command Line Tools* and select
an installed version. Even if one is already selected, re-select it.

If you are building the ``master`` branch:

- Download and follow README instructions to build a static ``.xcframework``
from the `MoltenVK SDK <https://github.com/KhronosGroup/MoltenVK#fetching-moltenvk-source-code>`__.

Expand All @@ -49,46 +46,40 @@ If you are building the ``master`` branch:
Compiling
---------

Open a Terminal, go to the root dir of the engine source code and type:
Open a Terminal, go to the root folder of the engine source code and type
the following to compile a debug build:

::

scons platform=ios target=template_debug
scons platform=ios target=template_debug generate_bundle=yes

for a debug build, or:
To compile a release build:

::

scons platform=ios target=template_release

for a release build (check ``platform/ios/detect.py`` for the compiler
flags used for each configuration).
scons platform=ios target=template_release generate_bundle=yes

Alternatively, you can run
Alternatively, you can run the following command for Xcode simulator libraries (optional):

::

scons platform=ios target=template_debug ios_simulator=yes arch=x86_64
scons platform=ios target=template_debug ios_simulator=yes arch=arm64
scons platform=ios target=template_debug ios_simulator=yes arch=x86_64 generate_bundle=yes

for a Simulator libraries.
These simulator libraries cannot be used to run the exported project on the
target device. Instead, they can be used to run the exported project directly on
your Mac while still testing iOS platform-specific functionality.

To create an Xcode project like in the official builds, you need to use the
template located in ``misc/dist/ios_xcode``. The release and debug libraries
should be placed in ``libgodot.ios.debug.xcframework`` and ``libgodot.ios.release.xcframework`` respectively.

::

cp -r misc/dist/ios_xcode .

cp libgodot.ios.template_debug.arm64.a ios_xcode/libgodot.ios.debug.xcframework/ios-arm64/libgodot.a
lipo -create libgodot.ios.template_debug.arm64.simulator.a libgodot.ios.template_debug.x86_64.simulator.a -output ios_xcode/libgodot.ios.debug.xcframework/ios-arm64_x86_64-simulator/libgodot.a

cp libgodot.ios.template_release.arm64.a ios_xcode/libgodot.ios.release.xcframework/ios-arm64/libgodot.a
lipo -create libgodot.ios.template_release.arm64.simulator.a libgodot.ios.template_release.x86_64.simulator.a -output ios_xcode/libgodot.ios.release.xcframework/ios-arm64_x86_64-simulator/libgodot.a

The MoltenVK static ``.xcframework`` folder must also be placed in the ``ios_xcode``
folder once it has been created.
should be placed in ``libgodot.ios.debug.xcframework`` and
``libgodot.ios.release.xcframework`` respectively. This process can be automated
by using the ``generate_bundle=yes`` option on the *last* SCons command used to
build export templates (so that all binaries can be included).

The MoltenVK static ``.xcframework`` folder must also be placed in the
``ios_xcode`` folder once it has been created. MoltenVK is always statically
linked on iOS; there is no dynamic linking option available, unlike macOS.

Run
---
Expand Down
52 changes: 22 additions & 30 deletions contributing/development/compiling/compiling_for_macos.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,54 +119,46 @@ To build macOS export templates, you have to compile using the targets without
the editor: ``target=template_release`` (release template) and
``target=template_debug``.

Official templates are universal binaries which support both Intel x86_64 and
ARM64 architectures. You can also create export templates that support only one
of those two architectures by leaving out the ``lipo`` step below.
Official templates are *Universal 2* binaries which support both ARM64 and Intel
x86_64 architectures.

- For Intel x86_64::
- To support ARM64 (Apple Silicon) + Intel x86_64::

scons platform=macos target=template_release arch=x86_64
scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64
scons platform=macos target=template_debug arch=x86_64
scons platform=macos target=template_release arch=x86_64 generate_bundle=yes

- For Arm64 (Apple M1)::
- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware)::

scons platform=macos target=template_release arch=arm64
scons platform=macos target=template_debug arch=arm64

To support both architectures in a single "Universal 2" binary, run the above
two commands blocks and then use ``lipo`` to bundle them together::

lipo -create bin/godot.macos.template_release.x86_64 bin/godot.macos.template_release.arm64 -output bin/godot.macos.template_release.universal
lipo -create bin/godot.macos.template_debug.x86_64 bin/godot.macos.template_debug.arm64 -output bin/godot.macos.template_debug.universal
scons platform=macos target=template_release arch=arm64 generate_bundle=yes

To create an ``.app`` bundle like in the official builds, you need to use the
template located in ``misc/dist/macos_template.app``. The release and debug
builds should be placed in ``macos_template.app/Contents/MacOS`` with the names
``godot_macos_release.universal`` and ``godot_macos_debug.universal`` respectively. You can do so
with the following commands (assuming a universal build, otherwise replace the
``.universal`` extension with the one of your arch-specific binaries)::

cp -r misc/dist/macos_template.app .
mkdir -p macos_template.app/Contents/MacOS
cp bin/godot.macos.template_release.universal macos_template.app/Contents/MacOS/godot_macos_release.universal
cp bin/godot.macos.template_debug.universal macos_template.app/Contents/MacOS/godot_macos_debug.universal
chmod +x macos_template.app/Contents/MacOS/godot_macos*
template located in ``misc/dist/macos_template.app``. This process can be automated by using
the ``generate_bundle=yes`` option on the *last* SCons command used to build export templates
(so that all binaries can be included). This option also takes care of calling ``lipo`` to create
an *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both were compiled beforehand).

.. note::

If you are building the ``master`` branch, you also need to include support
for the MoltenVK Vulkan portability library. By default, it will be linked
statically from your installation of the Vulkan SDK for macOS.
You can also choose to link it dynamically by passing ``use_volk=yes`` and
including the dynamic library in your ``.app`` bundle::
You also need to include support for the MoltenVK Vulkan portability
library. By default, it will be linked statically from your installation of
the Vulkan SDK for macOS. You can also choose to link it dynamically by
passing ``use_volk=yes`` and including the dynamic library in your ``.app``
bundle::

mkdir -p macos_template.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib

In most cases, static linking should be preferred as it makes distribution
easier. The main upside of dynamic linking is that it allows updating
MoltenVK without having to recompile export templates.

You can then zip the ``macos_template.app`` folder to reproduce the ``macos.zip``
template from the official Godot distribution::

zip -q -9 -r macos.zip macos_template.app
zip -r9 macos.zip macos_template.app

Using Pyston for faster development
-----------------------------------
Expand Down
16 changes: 16 additions & 0 deletions contributing/development/configuring_an_ide/visual_studio_code.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,22 @@ To run and debug the project you need to create a new configuration in the ``lau
"preLaunchTask": "build"
}

.. code-tab:: js Mac

{
"name": "Launch Project",
"type": "lldb",
"request": "custom",
"targetCreateCommands": [
"target create ${workspaceFolder}/bin/godot.macos.editor.dev.x86_64"
],
// Change the arguments below for the project you want to test with.
// To run the project instead of editing it, remove the "--editor" argument.
"processCreateCommands": [
"process launch -- --editor --path path-to-your-godot-project-folder"
]
}

.. figure:: img/vscode_2_launch.json.png
:figclass: figure-w480
:align: center
Expand Down
140 changes: 117 additions & 23 deletions contributing/development/core_and_modules/variant_class.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,21 @@ Variant class
About
-----

Variant is the most important datatype of Godot, it's the most important
class in the engine. A Variant takes up only 20 bytes and can store
almost any engine datatype inside of it. Variants are rarely used to
hold information for long periods of time, instead they are used mainly
for communication, editing, serialization and generally moving data
around.
Variant is the most important datatype in Godot. A Variant takes up only 24
bytes on 64-bit platforms (20 bytes on 32-bit platforms) and can store almost
any engine datatype inside of it. Variants are rarely used to hold information
for long periods of time, instead they are used mainly for communication,
editing, serialization and generally moving data around.

A Variant can:

- Store almost any datatype
- Store almost any datatype.
- Perform operations between many variants (GDScript uses Variant as
its atomic/native datatype).
- Be hashed, so it can be compared quickly to other variants
- Be used to convert safely between datatypes
- Be hashed, so it can be compared quickly to other variants.
- Be used to convert safely between datatypes.
- Be used to abstract calling methods and their arguments (Godot
exports all its functions through variants)
exports all its functions through variants).
- Be used to defer calls or move data between threads.
- Be serialized as binary and stored to disk, or transferred via
network.
Expand All @@ -34,27 +33,122 @@ Basically, thanks to the Variant class, writing Godot itself was a much,
much easier task, as it allows for highly dynamic constructs not common
of C++ with little effort. Become a friend of Variant today.

References:
~~~~~~~~~~~
.. note::

All types within Variant except Nil and Object **cannot** be ``null`` and
must always store a valid value. These types within Variant are therefore
called *non-nullable* types.

One of the Variant types is *Nil* which can only store the value ``null``.
Therefore, it is possible for a Variant to contain the value ``null``, even
though all Variant types excluding Nil and Object are non-nullable.

References
~~~~~~~~~~

- `core/variant/variant.h <https://github.com/godotengine/godot/blob/master/core/variant/variant.h>`__

Containers: Dictionary and Array
List of variant types
---------------------

These types are available in Variant:

+---------------------------------+---------------------------+
| Type | Notes |
+=================================+===========================+
| Nil (can only store ``null``) | Nullable type |
+---------------------------------+---------------------------+
| :ref:`class_bool` | |
+---------------------------------+---------------------------+
| :ref:`class_int` | |
+---------------------------------+---------------------------+
| :ref:`class_float` | |
+---------------------------------+---------------------------+
| :ref:`class_string` | |
+---------------------------------+---------------------------+
| :ref:`class_vector2` | |
+---------------------------------+---------------------------+
| :ref:`class_vector2i` | |
+---------------------------------+---------------------------+
| :ref:`class_rect2` | 2D counterpart of AABB |
+---------------------------------+---------------------------+
| :ref:`class_rect2i` | |
+---------------------------------+---------------------------+
| :ref:`class_vector3` | |
+---------------------------------+---------------------------+
| :ref:`class_vector3i` | |
+---------------------------------+---------------------------+
| :ref:`class_transform2d` | |
+---------------------------------+---------------------------+
| :ref:`class_vector4` | |
+---------------------------------+---------------------------+
| :ref:`class_vector4i` | |
+---------------------------------+---------------------------+
| :ref:`class_plane` | |
+---------------------------------+---------------------------+
| :ref:`class_quaternion` | |
+---------------------------------+---------------------------+
| :ref:`class_aabb` | 3D counterpart of Rect2 |
+---------------------------------+---------------------------+
| :ref:`class_basis` | |
+---------------------------------+---------------------------+
| :ref:`class_transform3d` | |
+---------------------------------+---------------------------+
| :ref:`class_projection` | |
+---------------------------------+---------------------------+
| :ref:`class_color` | |
+---------------------------------+---------------------------+
| :ref:`class_stringname` | |
+---------------------------------+---------------------------+
| :ref:`class_nodepath` | |
+---------------------------------+---------------------------+
| :ref:`class_rid` | |
+---------------------------------+---------------------------+
| :ref:`class_object` | Nullable type |
+---------------------------------+---------------------------+
| :ref:`class_callable` | |
+---------------------------------+---------------------------+
| :ref:`class_signal` | |
+---------------------------------+---------------------------+
| :ref:`class_dictionary` | |
+---------------------------------+---------------------------+
| :ref:`class_array` | |
+---------------------------------+---------------------------+
| :ref:`class_packedbytearray` | |
+---------------------------------+---------------------------+
| :ref:`class_packedint32array` | |
+---------------------------------+---------------------------+
| :ref:`class_packedint64array` | |
+---------------------------------+---------------------------+
| :ref:`class_packedfloat32array` | |
+---------------------------------+---------------------------+
| :ref:`class_packedfloat64array` | |
+---------------------------------+---------------------------+
| :ref:`class_packedstringarray` | |
+---------------------------------+---------------------------+
| :ref:`class_packedvector2array` | |
+---------------------------------+---------------------------+
| :ref:`class_packedvector3array` | |
+---------------------------------+---------------------------+
| :ref:`class_packedcolorarray` | |
+---------------------------------+---------------------------+
| :ref:`class_packedvector4array` | |
+---------------------------------+---------------------------+

Containers: Array and Dictionary
--------------------------------

Both are implemented using variants. A Dictionary can match any datatype
used as key to any other datatype. An Array just holds an array of
Variants. Of course, a Variant can also hold a Dictionary and an Array
inside, making it even more flexible.
Both :ref:`class_array` and :ref:`class_dictionary` are implemented using
variants. A Dictionary can match any datatype used as key to any other datatype.
An Array just holds an array of Variants. Of course, a Variant can also hold a
Dictionary or an Array inside, making it even more flexible.

Modifications to a container will modify all references to
it. A Mutex should be created to lock it if multi threaded access is
desired.

Copy-on-write (COW) mode support for containers was dropped with Godot 3.0.
it. A Mutex should be created to lock it if
:ref:`multi-threaded access <doc_using_multiple_threads>` is desired.

References:
~~~~~~~~~~~
References
~~~~~~~~~~

- `core/variant/dictionary.h <https://github.com/godotengine/godot/blob/master/core/variant/dictionary.h>`__
- `core/variant/array.h <https://github.com/godotengine/godot/blob/master/core/variant/array.h>`__
2 changes: 2 additions & 0 deletions tutorials/2d/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
canvas_layers
2d_transforms

.. _doc_2d_rendering:

Rendering
---------

Expand Down
2 changes: 2 additions & 0 deletions tutorials/3d/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@
procedural_geometry/index
3d_text

.. _doc_3d_rendering:

Rendering
---------

Expand Down
6 changes: 6 additions & 0 deletions tutorials/3d/standard_material_3d.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -658,6 +658,12 @@ make it black and unshaded, reverse culling (Cull Front), and add some grow:

.. image:: img/spatial_material11.png

.. note::

For Grow to work as expected, the mesh must have connected faces with shared
vertices, or "smooth shading". If the mesh has disconnected faces with unique
vertices, or "flat shading", the mesh will appear to have gaps when using Grow.

Transform
---------

Expand Down
Loading

0 comments on commit 649a398

Please sign in to comment.