1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
//! A crate for reading the [LDtk] tile map format.
//!
//! This crate implements the Rust structures necessary to Serialize and Deserialize the LDtk map
//! format using [`serde`].
//!
//! # Example
//!
//! **`Cargo.toml`:**
//!
//! ```toml
//! # Note: We must specify the version of LDtk we want to support in a feature flag
//! ldtk = { version = "0.4.0", features = ["ldtk-v0-9-3"] }
//! ```
//!
//! **`main.rs`:**
//!
//! ```rust
//! use ldtk::Project;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Load the map
//! let map: Project =
//! serde_json::from_slice(include_bytes!("../examples/full-features.ldtk"))?;
//!
//! // Debug print the map
//! dbg!(map);
//!
//! Ok(())
//! }
//! ```
//!
//! [ldtk]: https://github.com/deepnight/ldtk
//!
//! # Extra Documentation
//!
//! For more information on using the LDtk project structure inside of games see the [LDtk
//! docs][ldtk_docs].
//!
//! # Naming Conventions
//!
//! This crate uses the same struct field names as the raw JSON format in almost all cases. The
//! exception to this rule is for fields that are named `type`. In this case the name of the field
//! will be prefixed with the name of it's struct, converted to snake case, for instance
//! `field_def_type`.
//!
//! ## The `__field_name` Convention
//!
//! It is a convention of the LDtk map format to prefix certain convenience fields with two
//! underscores, such as `__tile_src_rect`. These fields are redundant, as the information in them
//! is also present elsewhere in the project structure, but they are provided in some cases where it
//! may make traversing the project structure much more convenient.
//!
//! The double underscore prefix does **not** indicate that the field is a private field or an
//! implementation detail.
//!
//! [ldtk_docs]: https://ldtk.io/docs/game-dev/json-overview/
//!
//! # Build Configuration & Features
//!
//! This entire crate is automatically generated from the [JSON Schema](http://json-schema.org/)
//! from the [LDtk repo](https://github.com/deepnight/ldtk/blob/master/docs/JSON_SCHEMA.json) and
//! can be automatically updated with LDtk releases.
//!
//! By default the crate requires that you pass a feature indicating a version of the JSON schema
//! that is built into the crate so that it doesn't require network access to build, but you can
//! also supply the `download-schema` cargo feature to make the crate download the JSON schema from
//! the LDtk repo instead ( See "Downloading the Schema" below ).
//!
//! This crate currently has the schema for the following versions of LDtk built-in:
//!
//! - `v0.9.3`
//! - `v0.8.1` ( patched, see note below )
//! - `v0.7.0`
//!
//! The format of the feature flags for specific versions is like this: `ldtk-v0-9-3`. Note that the
//! periods in the version have been replaced with dashes to be conformat with cargo's feature
//! naming conventions.
//!
//! > **Note:** In version 0.8.1 there was a field that was marked as non-null in the JSON schema,
//! > but in one of the LDtk sample maps the field was null. We patched the JSON schema to make the
//! > field nullable so that the map would load correctly.
//!
//! As newer LDtk versions are released we may add new built-in schemas. These will each be under
//! new feature flags so that updates to the schema do not need to be breaking changes.
//!
//! ## Downloading the Schema
//!
//! When the `download-schema` feature is provided, you can specify which version of LDtk you want
//! to build this crate for by setting the `LDTK_VERSION` environment variable at build time.
//! `LDTK_VERSION` will default to `master` which will pull the latest schema from the master branch
//! of the LDtk git repo.
//!
//! # License
//!
//! LDtk-rs is licensed under the [Katharos License][k_license] which places certain restrictions on
//! what you are allowed to use it for. Please read and understand the terms before using LDtk-rs
//! for your project.
//!
//! [k_license]: https://github.com/katharostech/katharos-license
// The actual code is generated in the `build.rs`.
include!;