godotengine / godotengine/godot-docs

Clarify what an imported resource really is and how to load external files (png, jpg, ogg, wav...)

Open
#2,148 13 comments 18 reactions 0 assignees View on GitHub
area:manual enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

it's not the first time (and won't be the last) where an user tries to load an external file (a file that has not been imported) with `load()` or `ResourceLoader.load()` and gets confused because it doesn't load or it fails.

We need to explain them that those functions only work with imported files and what they should do to load external files. I think we need to specify somewhere that imported resources aren't the same as files and how to load external files but I have no idea where.

I'll try to explain it and hope that someone can unmess the mess I write 😅

> In godot, imported resources aren't the same as files.
>
> Explanation on what godot does when you import a file here https://docs.godotengine.org/en/latest/getting_started/workflow/assets/import_process.html
>
> So a resource links a file with one or more converted files. For example, the path `res://icon.png` doesn't point to the file `my_project/icon.png` but it will read the `icon.png.import` file and this file will contain the path to the converted files something like `my_project/.import/icon-47---.stex` and `my_project/.import/icon-12---.stex` which are the files that the engine has created from your file and they are the ones that it will use at runtime.
>
> When you export your project `my_project/icon.png` won't be in exported into the `pck` file but only the `icon.png.import` file pointing to those converted files.

And some examples to load different files:

Load an ogg file:
```gdscript
func play_external_file(path):
var ogg = AudioStreamOGGVorbis.new()
var file = File.new()
file.open(path, File.READ)
ogg.data = file.get_buffer(file.get_len())
file.close()
$AudioStreamPlayer.stream = ogg
$AudioStreamPlayer.play()
```

Load a png file:
```gdscript
func get_external_texture(path):
var img = Image.new()
img.load(path)
var texture = ImageTexture.new()
texture.create_from_image(img)
return texture
```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.