# yl_cinema

## Purpose

The yl_cinema mod enables staff or code to show movies to players.

## Download

Download the mod from [here](https://gitea.your-land.de/your-land/yl_cinema).

## Installation

1. Copy the "yl_cinema" folder to your mod directory.
2. Enable the mod in your world.mt file.

## Configuration

The mod's configuration can be found in `./settingtypes.txt`. Modify the following settings:

```lua
yl_cinema.settings.save_path = "yl_cinema_movies"
yl_cinema.settings.admin_priv = "staff"
yl_cinema.settings.enable_bigscreen = true
yl_cinema.settings.enable_craft_bigscreen = true
yl_cinema.settings.enable_craft_bigscreen_recipe = "wool:grey,wool:grey,wool:grey,wool:grey,wool:grey,wool:grey,wool:black,,wool:black"
```

## Modmakers

### API Functions

The yl_cinema mod provides the following API functions that can be called from your own mod:

```lua
success, msg, movielist = yl_cinema.listmovies(searchterm)
```

Parameters:
- `searchterm` (optional): A string used to filter the movie list by title or description.

Returns:
- `success`: A boolean indicating whether the movie list was returned successfully.
- `msg`: An error message if `success` is false, or the number of movies if `success` is true.
- `movielist`: An unordered table of movie IDs in the format `{"id1","id7","id27","id3"}`. It may be empty `{}` if no movies were found.

```lua
success, movie = yl_cinema.showmovie(name, movie_id, target_player_name)
```

Parameters:
- `name`: The name of the player who triggers the movie to be shown.
- `movie_id`: The ID of the movie to be shown.
- `target_player_name` (optional): The name of the player the movie is shown to.

Returns:
- `success`: A boolean indicating whether the movie was shown successfully.
- `movie`: A string containing an error message if `success` is false, or a table representing the movie if `success` is true.

```lua
success, msg = yl_cinema.getmovie(movie_id)
```

Parameters:
- `movie_id`: The ID of the movie you want to retrieve.

Returns:
- `success`: A boolean indicating whether the movie was retrieved successfully.
- `msg`: An error message if `success` is false, or a table with the movie structure (as described in "Create a movie") if `success` is true.

## Usage

The mod provides two chat commands for showing movies and listing movies:

- `/showmovie <name> <movie>`: Shows the `<movie>` to the specified `<player>`.
- `/listmovies [<searchstring>]`: Lists all movies. Optionally, you can provide a `<searchstring>` to filter the movie list.

## Create a Movie

To create a movie, follow these steps:

1. Create a folder with the movie ID as the name. Consult your admin for any required prefixes, suffixes, or other markings.
2. Inside the folder, create a JSON file with the following structure: `{movie_id, name, description, title_texture, version, replay, [{order, texturename, caption, captionposx, captionposy, duration},{...}]}`.
3. Create a "textures" folder inside the movie ID folder and place all the textures of your movie in it. Ensure that the filenames correspond to the `title_texture` and `texturename` specified in the JSON file.
4. Copy the movie to the yl_cinema.save_path, which is by default "yl_cinema_movies".

## Uninstall

To uninstall the mod:

1. Remove the mod from your mod folder.
2. Deactivate it in your world.mt file.

Note: If other mods depend on yl_cinema, they will stop working if the mod is removed without a proper replacement.

## License

This mod is licensed under the MIT License.