# Бибилотека первоапрельских розыгрышей для форумов MyBB

Базовое использование:

```html
<!-- Первоапрельские шутки -->
<script src="https://static.kozhilya.ru/script/april-fools.min.js"></script>
<script>
  // Установка настроек системы
  window.AprilJokes.settings = {
    // ...
  };
</script>
<!-- Конец первоапрельских шуток -->
```

---

## Полный список шуток

- `shake` — **Форумо-трясение**. Страница форума начинает трястись.
- `mirror` — **Зеркало**. Элементы форума отражаются... По крайней мере, пытаются.
- `carnival` — **Карнавал**. Аватарки приобретают интересные цвета.
- `humanitarian_hell` — **Ад гуманитария**. Все "тся" заменяются на "ться", а все "ться" на "тся".
- `crazy_letters` — **Мама, Я сОшЛа С уМа!** иМеНа ЗаБоРчИкОм
- `letter_chaos` — **Буквенный хаос**. Все буквы в словах, кроме первой и последней, перемешены.
- `cursor` — **Красивые курсоры**. Эффекты, следующие за курсором.
- `stupid_title` — **Глупые статусы**. Каждому пользователю даётся новый глупый статус.

---

## Тестирование шуток

Что бы проверить работу системы, вы можете включить "режим тестера". Для этого добавьте свой `UserID` в настройку `core.testers`: 

```js
window.AprilJokes.settings = {
  // ...
  core: {
    testers: [ 2, 3, 1186 ],
  },
  // ...
};
```

---

## Настройка шуток

Настройка шуток происходит при присвоении объекта `window.AprilJokes.settings`.
Это присвоедние должно произойти **после** загрузки скрипта.

Для всех шуток определны 2 общих поля:

```js
window.AprilJokes.settings = {
  // ...
  example: {
    /**
     * Активность шутки.
     * Установите это значение `false`, что бы отключить шутку.
     * Если `true`, то шутка будет обработана как обычно.
     */
    enabled: true,

    /**
     * Вероятность срабатывания в процентах.
     * Если установлено значение `100`, шутка будет срабатывать всегда.
     * Если установлено значение `0`, шутка никогда не сработает.
     * Лучше отключать шутку, используя enabled = false!
     */
    chance: 20,
  },
  // ...
};
```

Полный список настроек с объяснениями вы можете посмотреть в файле [`settings.example.js`](./settings.example.js). Также представлен файл [`settings.compact.js`](./settings.compact.js), который также содержит все настройки, но без коментариев.

При этом, объективно, вставлять весь этот код в HTML-начало может быть "немного" неудобно, поэтому вы можете скачать код (кнопка "Raw" над файлом), изменить его, и загрузить в файлы форума, подключив скрипт таким образом:

```html
<!-- Первоапрельские шутки -->
<script src="https://static.kozhilya.ru/script/april-fools.min.js"></script>
<script src="https://forumstatic.ru/files/$$$$/$$/$$/$$$$$.js"></script>
<!-- Конец первоапрельских шуток -->
```

Заметьте, что во всех примерах приведены значения настроек по умолчанию. Вы _можете_ удалять строки, значения по умолчанию которых вас устраивают.

Если вас интерсует только несколько шуток, вы можете использовать метод `disableAll()`, что бы выключить выполнение всех шуток, а потом включать отдельные шутки через установку настройки `enabled`:

```js
window.AprilJokes.disableAll();

window.AprilJokes.settings = {
  // ...
  example: {
    enabled: true,
    // ...
  },
  // ...
};
```

Обратите внимание, что метод `disableAll()` должен быть вызван _до_ установки настроек `settings`, иначе заданные значения `enabled` будут сброшены.

Так же есть метод `window.AprilJokes.enableAll()`, который включает все шутки, в том числе отключённые по умолчанию.

---

### Настройка `shake` (Форумо-трясение)

Тряска элементов происходит путём изменения перечисленных направлений `margin` на значение ±`force` от стандартного значения.

> **Важно**: эта шутка может вызвать дискомфорт у пользователей. Настоятельно рекомендуется оставить вероятность срабатывания шутки (`chance`) очень низкой, что бы у пользователей была возможность избавиться от шутки простым обновлением страницы! Вариант отключить шутку (`enabled: false`) тоже вариант.

---

### Настройка `mirror` (Зеркало)

Элементы форума отражаются по весьма специфичному алгоритму... И из-за этого, шутка может работать _очень_ плохо на некоторых дизайнах, поэтому данная шутка по умолчанию **отключена**

Для того, что бы попробовать, сработает ли шутка для вашего дизайна, используйте в консоли разработчика:

```js
window.AprilJokes.start("mirror", true);
```

Так же можете [посмотреть](./src/jokes/mirror.ts#L16) на метод `MirrorJoke.start`, что бы узнать как именно проиходит отражение.

---

### Настройка `cursor` (Красивые курсоры)

Используются курсоры, предложенные в библотеке `tholman/cursor-effects` от Tim Holman ([Github](https://github.com/tholman/cursor-effects), [сайт](https://tholman.com/cursor-effects/)).

Код предусматривает, что одновременно активировано не более 1 курсора из этой библиотеки. Так же для каждого курсора установлен свой шанс срабатывания, однако из-за необходимости активации строго одного эффекта, предусмотрено использование весового коэффициента `weight`: если говорить просто, то чем больше это значение, то тем больше шанс срабатывания эффекта относительно других эффектов.

Так же для каждого эффекта определена настройка `enabled`, позволяющая отключить эффекты, и метод `disableAll` для отключения эффектов:

```js
window.AprilJokes.jokes.cursor.disableAll();
```

---

### Настройка `stupid_title` (Глупые статусы)

> **Важно**: этот блок может быть чрезвычайно капризым из-за особенностей хранения данных, особенно блок `variants`. Изменяя его, строго следуйте этой инструкции, иначе скрипт может перестать работать ожидаемым образом.

Данная шутка генерирет статус из случайных слов. За счёт использования псевдослучайного генератора, хеширования и привязки к времени UTC, ожидается что все пользователи одновременно будут видеть один и тот же статус для каждого пользователя, при этом он меняется каждые `change_frequency` минут. Установите это значение равным `0`, что бы статус генерировался при каждом обновлении страницы.

Для настройки списка слов используется функция `BuildStupdiTitleVariant`, которая преобразует список слов во внутренний формат скрипта. Настоятельно рекомендуется использовать именно её, а не записывать параметры напрямую:

```js
window.AprilJokes.settings = {
  // ...
  stupid_title: {
    // ...
    variants: {
      adj: {
        ...window.AprilJokes.settings.stupid_title.variants.adj,
        ...BuildStupdiTitleVariant(true, "скромный, шутливый, !грубый"),
        ...BuildStupdiTitleVariant(false, "скромная, шутливая, !грубая"),
      },
      noun: { ...window.AprilJokes.settings.stupid_title.variants.noun },
      verb: { ...window.AprilJokes.settings.stupid_title.variants.verb },
      place: { ...window.AprilJokes.settings.stupid_title.variants.place },
      adv: { ...window.AprilJokes.settings.stupid_title.variants.adv },
      p: { ...window.AprilJokes.settings.stupid_title.variants.p },
    },
    // ...
  },
  // ...
};
```

Обратите внимание на конструкции вида `{ ...something }` — эта конструкция позволяет перенести все поля нескольких старых объектов в один новый. При этом, если в двух объединяемых объектах есть совпадающие значения, то будет сохранено последнее.

Говоря проще: добовляйте ваши настройки _после_ строки вида `...window.AprilJokes.settings.stupid_title.variants.adj`, что бы ваши настройки не были перезаписаны.

Метод `BuildStupdiTitleVariant` принимает 2 аргумента:

- `gender` — определённый род для генерации. Используйте `true` для мужского рода, `false` для женского и `null`, если добавляемые варианты могут использоваться в обоих случаях.
- `words` — строка, со списоком вариантов через запятую. В качестве вариантов могут быть слова из русских или английских букв, пробелов или дефисов, то есть можно использовать `"...,  почему-то и зачем-то , ..."` и `почему-то и зачем-то` будет воспринят как один вариант. Также варианты можно модифицировать, добавив один или несколько модификаторов:
  - `!` отключает использование слова. Этим модификатором можно отключать слова из списка по умолчанию (см `!грубый` в примере выше).
  - `%` помечает слово как редкое. Шанс его использования понижается в 2 раза.
  - `^` помечает слово как частое. Шанс его использования повышается в 2 раза.
  - `$` помечает слово как грубое. Такие слова не будут отображаться, если в настройках отключена соответсвующая настройка `rude`.

Полный список слов по умолчанию вы можете посмотреть [в Google Таблице](https://docs.google.com/spreadsheets/d/1MJIfENqy7a9DczRj38c34t27ZQtEmBSi/edit?usp=sharing&ouid=112152128398997742033&rtpof=true&sd=true) или [в исходном файле](./src/data/stupid_title_variants.ts).

---

## Разработка дополнений

Использование для тестирования:

```html
<!-- Первоапрельские шутки: версия для разработчиков -->
<script src="https://static.kozhilya.ru/script/april-fools.js"></script>
<script>
  // Установка настроек системы
  window.AprilJokes.settings = {
    // ...
  };

  // Создание новой шутки
  window.AprilJokes.addCustom(
    // ID шутки
    "alert",

    // Вызываемая функция шутки
    (settings) => {
      alert(settings.text);
    },

    // Стандартные настройки
    {
      enabled: true,
      chance: 30,
      text: "Fooled!",
    }
  );

  // Запуск шутки
  // true - отключает проверки случайности
  window.AprilJokes.start("alert", true);
</script>
<!-- Конец первоапрельских шуток: версия для разработчиков -->
```

Обратите внимание на то, что имя скрипта здесь `april-fools.js` (в стандартном примере — `april-fools.min.js`). Эта версия скрипта обновляется чаще, а также позволяет видеть относительно читабельный код в DevTools.